diff --git a/core/modules/simpletest/lib/Drupal/simpletest/WebTestBase.php b/core/modules/simpletest/lib/Drupal/simpletest/WebTestBase.php index 7cfbc58..667f405 100644 --- a/core/modules/simpletest/lib/Drupal/simpletest/WebTestBase.php +++ b/core/modules/simpletest/lib/Drupal/simpletest/WebTestBase.php @@ -26,6 +26,8 @@ /** * Test case for typical Drupal tests. + * + * @ingroup testing */ abstract class WebTestBase extends TestBase { diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php index c8a5ede..82a5e92 100644 --- a/core/modules/system/core.api.php +++ b/core/modules/system/core.api.php @@ -620,12 +620,88 @@ * @{ * Overview of PHPUnit tests and Simpletest tests. * - * @todo write this - * - * Additional documentation paragraphs need to be written, and functions, - * classes, and interfaces need to be added to this topic. - * - * See https://drupal.org/simpletest and https://drupal.org/phpunit + * The Drupal project has embraced a philosophy of using automated regression + * tests. The basic idea is to have automated tests in place, both unit tests + * (which test the functionality of classes at a low level) and functional tests + * (which test the functionality of Drupal systems at a higher level, usually + * involving web output). This way, when a code change (patch) is proposed for + * Drupal, we can run the automated test suite, and assuming that the tests pass + * and are sufficiently comprehensive, we can be reasonably certain that the + * patch will not break existing functionality. + * + * In order to implement this philosophy, developers need to do the following: + * - When making a patch to fix a bug, start by writing a test that illustrates + * the bug and demonstrating that this test fails. Then fix the bug, and + * demonstrate that the test passes. + * - When making a patch to implement a new feature, include new unit and/or + * functional tests in the patch. This serves to both demonstrate that the + * code actually works, and ensure that later changes do not break the new + * functionality. + * + * @section running Running tests + * Both unit tests and functional tests are automatically run whenever you + * submit a patch for review to the Drupal Core project on https://drupal.org. + * Some contributed patches also have automated patch review set up. + * + * You can run tests yourself using the core/scripts/run-tests.sh script, + * using @link https://drupal.org/project/drush Drush @endlink, or from the + * Drupal user interface using the core Testing module. + * + * @section write_unit Writing unit tests + * Unit tests are written using the industry-standard PHPUnit framework. Use a + * unit test to test functionality of a class, classes, and/or functions, if + * the Drupal environment (database, settings, etc.) and web browser are not + * needed for the test, or if the Drupal environment can be replaced by a + * "mocking" class. To write a unit test: + * - Define a class that extends \Drupal\Tests\UnitTestCase. + * - The class name needs to end in the word Test. + * - The namespace must be a subspace/subdirectory of \Drupal\yourmodule\Tests, + * where yourmodule is your module's machine name. + * - The test class file must be named and placed under the yourmodule/tests + * directory, according to the PSR-4 standard. + * - Your test class needs a getInfo() method, which gives information about + * the test. + * - Methods in your test class whose names start with 'test', and which have + * no arguments, are the actual test cases. Each one should test a logical + * subset of the functionality. + * For more details, see: + * - https://drupal.org/phpunit for full documentation on how to write PHPUnit + * tests for Drupal. + * - http://phpunit.de/manual/3.7/en/automating-tests.html for general + * information on the PHPUnit framework. + * - @link oo_conventions Object-oriented programming topic @endlink for more + * on PSR-4, namespaces, and where to place classes. + * + * @section write_functional Writing functional tests + * Functional tests are written using a Drupal-specific framework that is, for + * historical reasons, known as "Simpletest". Use a Simpletest test to test the + * functionality of sub-system of Drupal, if the functionality depends on the + * Drupal database and settings, and to test the web output of Drupal. To + * write a Simpletest test: + * - For most functional tests, define a class that extends + * \Drupal\simpletest\WebTestBase, which contains an internal web browser and + * defines many helpful test assertion methods that you can use in your tests. + * - The class name needs to end in the word Test. + * - The namespace must be a subspace/subdirectory of \Drupal\yourmodule\Tests, + * where yourmodule is your module's machine name. + * - The test class file must be named and placed under the yourmodule/src + * directory, according to the PSR-4 standard. + * - Your test class needs a getInfo() method, which gives information about + * the test. + * - You may also override the default setUp() method, which can set be used to + * set up content types and similar procedures. + * - You can define additional modules to be enabled by overriding the + * $modules member variable. In some cases, you may need to make a test + * module to support your test; put such modules under the + * yourmodule/tests/modules directory. + * - Methods in your test class whose names start with 'test', and which have + * no arguments, are the actual test cases. Each one should test a logical + * subset of the functionality. + * For more details, see: + * - https://drupal.org/simpletest for full documentation on how to write + * functional tests for Drupal. + * - @link oo_conventions Object-oriented programming topic @endlink for more + * on PSR-4, namespaces, and where to place classes. * @} */ diff --git a/core/tests/Drupal/Tests/UnitTestCase.php b/core/tests/Drupal/Tests/UnitTestCase.php index 898f40e..518cf0a 100644 --- a/core/tests/Drupal/Tests/UnitTestCase.php +++ b/core/tests/Drupal/Tests/UnitTestCase.php @@ -14,6 +14,8 @@ /** * Provides a base class and helpers for Drupal unit tests. + * + * @ingroup testing */ abstract class UnitTestCase extends \PHPUnit_Framework_TestCase {