diff --git a/core/modules/simpletest/lib/Drupal/simpletest/UnitTestBase.php b/core/modules/simpletest/lib/Drupal/simpletest/UnitTestBase.php index 9d93fa0..301c7b6 100644 --- a/core/modules/simpletest/lib/Drupal/simpletest/UnitTestBase.php +++ b/core/modules/simpletest/lib/Drupal/simpletest/UnitTestBase.php @@ -17,6 +17,8 @@ * function that needs the database will throw exceptions. These include * watchdog(), \Drupal::moduleHandler()->getImplementations(), * \Drupal::moduleHandler()->invokeAll() etc. + * + * @ingroup testing */ abstract class UnitTestBase extends TestBase { diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php index 82a5e92..decdd48 100644 --- a/core/modules/system/core.api.php +++ b/core/modules/system/core.api.php @@ -620,55 +620,45 @@ * @{ * Overview of PHPUnit tests and Simpletest tests. * - * 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. + * The Drupal project has embraced a philosophy of using automated tests, + * consisting of 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). The goal is to + * have test coverage for all or most of the components and features, and to + * run the automated tests before any code is changed or added, to make sure + * it doesn't break any existing functionality (regression testing). * * 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 fix a bug, make sure that the bug fix patch includes + * a test that fails without the code change and passes with the code change. + * This helps reviewers understand what the bug is, demonstrates that the code + * actually fixes the bug, and ensures the bug will not reappear due to later + * code changes. * - 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: + * @section write_unit Writing PHPUnit tests for classes + * PHPUnit tests for classes are written using the industry-standard PHPUnit + * framework. Use a PHPUnit test to test functionality of a class 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 PHPUnit 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 + * - The test class file must be named and placed under the yourmodule/tests/src * 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. + * - Methods in your test class whose names start with 'test' 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. + * - http://phpunit.de 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. * @@ -676,32 +666,51 @@ * 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 + * Drupal database and settings, or 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. + * - For functional tests of the web output of Drupal, 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. You can define additional modules to be enabled by + * overriding the $modules member variable -- keep in mind that by default, + * WebTestBase uses a "testing" install profile, with a minimal set of + * modules enabled. + * - For functional tests that do not test web output, define a class that + * extends \Drupal\simpletest\UnitTestBase. This class is much faster than + * WebTestBase, because instead of making a full install of Drupal, it uses + * an in-memory pseudo-installation. To use this test class, you will need + * to create the database tables you need and include the module files you + * need manually. * - 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 + * - The test class file must be named and placed under the yourmodule/src/Tests * 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. + * - In some cases, you may need to write 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. + * subset of the functionality, and each one runs in a new, isolated test + * environment, so it can only rely on the setUp() method, not what has + * been set up by other test methods. * 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. + * + * @section running Running tests + * You can run both Simpletest and PHPUnit tests by enabling the core Testing + * module (core/modules/simpletest). Once that module is enabled, tests can be + * run usin the core/scripts/run-tests.sh script, using + * @link https://drupal.org/project/drush Drush @endlink, or from the Testing + * module user interface. + * + * PHPUnit tests can also be run from the PHPUnit framework. * @} */