diff --git a/core/core.api.php b/core/core.api.php
index 639e55d..4427ee6 100644
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -1121,6 +1121,43 @@
  * - @link oo_conventions Object-oriented programming topic @endlink for more
  *   on PSR-4, namespaces, and where to place classes.
  *
+ * @section write_functional_phpunit Write functional PHP tests (phpunit)
+ * Functional tests are written using the BrowserTestBase base class, and use
+ * PHPUnit as their underlying framework. They use a simulated browser, in which
+ * the test can click links, visit URLs, post to forms, etc. To write a
+ * functional test:
+ * - Extend \Drupal\Tests\BrowserTestBase.
+ * - Place the test in the yourmodule/tests/src/Functional directory and use
+ *   the Drupal\Tests\yourmodule\Functional namespace.
+ * - Add a @group annotation. For example, if the test is for a Drupal 6
+ *   migration process, the group core uses is migrate_drupal_6. Use yourmodule
+ *   as the group name if the test does not belong to another larger group.
+ * - You may also override the default setUp() method, which can be used to set
+ *   up content types and similar procedures. Don't forget to call the parent
+ *   method.
+ * - 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, 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.
+ *
+ * @section write_jsfunctional_phpunit Write functional JavaScript tests (phpunit)
+ * A lot of functionality relies on JavaScript. To write a functional test that
+ * relies on JavaScript:
+ * - Extend \Drupal\FunctionalJavaScriptTests\JavascriptTestBase.
+ * - Place the test into the yourmodule/tests/src/FunctionalJavascript directory
+ *   and use the Drupal\Tests\yourmodule\FunctionalJavascript namespace.
+ * - Add a @group annotation. Use yourmodule as the group name if the test does
+ *   not belong to another larger group.
+ * - Set up PhantomJS; see http://phantomjs.org/download.html.
+ * - To run tests, see core/tests/README.md.
+ * - When clicking a link/button with Ajax behavior attached, you need to keep
+ *   in mind that the underlying browser might need a while to deliver changes
+ *   to the HTML. Use $this->assertSession()->assertWaitOnAjaxRequest() to wait
+ *   for that.
+ *
  * @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