Issue #3086532 by Mile23, heddn: Further document Build and in general improve testing docs

core/core.api.php

@@ -1119,6 +1119,17 @@
  *     subdirectory)
  *   - Directory location: yourmodule/tests/src/FunctionalJavascript (or a
  *     subdirectory)
+ * - Build tests:
+ *   - Purpose: Test building processes and their outcomes, such as whether a
+ *     live update process actually works, or whether a Composer project
+ *     template actually builds a working site. Provides a temporary build
+ *     workspace and a PHP-native HTTP server to send requests to the site
+ *     you've built.
+ *   - Base class: \Drupal\BuildTests\Framework\BuildTestBase
+ *   - Namespace: \Drupal\Tests\yourmodule\Build (or a
+ *     subdirectory)
+ *   - Directory location: yourmodule/tests/src/Build (or a
+ *     subdirectory)
  *
  * Some notes about writing PHP test classes:
  * - The class needs a phpDoc comment block with a description and

core/tests/README.md

@@ -44,7 +44,7 @@ to install the following additional software:
   https://sites.google.com/a/chromium.org/chromedriver/
 * PHP 7.1 or higher
 
-## Running unit, functional, and kernel tests
+## Running tests
 
 The PHPUnit executable is vendor/bin/phpunit -- you will need to locate your
 vendor directory (which may be outside the Drupal root).
@@ -57,10 +57,30 @@ a particular group:
 ./vendor/bin/phpunit -c /path/to/your/phpunit.xml --group Groupname
 ```
 
+Drupal core currently has a number of different types of tests that can be run
+using PHPUnit:
+- unit
+- kernel
+- functional
+- functional-javascript
+- build
+
+These are organized into PHPUnit test suites. You can run one test suite or many
+in combination by using `--testsuite` on the command line:
+```
+./vendor/bin/phpunit -c /path/to/your/phpunit.xml --testsuite unit
+./vendor/bin/phpunit -c /path/to/your/phpunit.xml --testsuite functional,functional-javascript
+```
+These can be combined with groups and filters:
+```
+./vendor/bin/phpunit -c /path/to/your/phpunit.xml --testsuite build --group Composer
+./vendor/bin/phpunit -c /path/to/your/phpunit.xml --testsuite build --exclude-group Build
+./vendor/bin/phpunit -c /path/to/your/phpunit.xml --testsuite unit --filter ClassTest::testMethod
+```
 More information on running tests can be found at
 https://www.drupal.org/docs/8/phpunit/running-phpunit-tests
 
-## Running Functional JavaScript tests
+## Setup for running Functional JavaScript tests
 
 You can run JavaScript tests that are based on the
 \Drupal\FunctionalJavascriptTests\WebDriverTestBase base class in the same way