diff --git a/core/core.api.php b/core/core.api.php
index 4b2fe62..69f2a60 100644
--- a/core/core.api.php
+++ b/core/core.api.php
@@ -1121,6 +1121,42 @@
  * - @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 tests (phpunit)
+ * Functional tests are written using PHPUnit as underlying framework, we call
+ * them BrowserTestBase, as they use a simulated browser, which can click links
+ * goto URLs, post to forms, and much more. To write a functional test:
+ * - You need to extend \Drupal\Tests\BrowserTestBase. There are a couple of
+ *   base assertions for stuff related with pure data ($this->assertEquals), but
+ *   more important with $this->assertSession() you get a
+ *   \Drupal\Tests\WebAssert object containing browser related assertions like
+ *   linkExists().
+ * - The expected folder is yourmodule/tests/src/Functional and using a
+ *   namespace like Drupal\Tests\yourmodule\Functional.
+ *   a @group annotation, 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.
+ * - 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 javascript tests
+ * Quite some functionality relies on Javascript. In order to allow
+ * people to write functional test coverage for those Drupal provides another
+ * base class, \Drupal\FunctionalJavascriptTests\JavascriptTestBase, which works
+ * really similar to BrowserTestBase.
+ * - You need to put the tests into tests/src/FunctionalJavascript and use
+ *   the Drupal\Tests\$module\FunctionalJavascript namespace
+ * - You need to run phantomjs, see core/tests/README.md
+ * - You use the same assertions as BrowserTestBase
+ * - When clicking a link/button with ajax behaviour, you need to keep in mind
+ *   that the underlying browser might need a while to deliver changes to the
+ *   HTML, which is why we provide
+ *   $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