diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
@@ -65,6 +65,35 @@
 
 Also note that running a recent version of `portlint` (as specified in the next section) will cause `make describe` to be run automatically.
 
+[[make-test]]
+== Running `make test`
+
+Even if the port builds fine, it is a good idea to ensure that the software
+correctly does what it is supposed to do.
+If the original upstream project provides tests along with the software, it is a
+good idea to run them and check everything works as expected.
+
+A port can enable tests automatically by using the `TEST_TARGET` variable.
+When set, this variable contains the name of the testing target of the port.
+This is usually just `test` but other names include `tests`, `check` or for
+specific cases things like `run_tests.py`.
+
+In addition to the `TEST_TARGET` variable the framework provides the following
+variables to control the tests execution:
+
+* `TEST_WRKSRC` is the directory to do the tests in.
+* `TEST_ENV` contains additional variables to be passed to the test stage.
+* `TEST_ARGS` contains any extra arguments passed to  the test stage.
+
+Examples of use of these variables can be found in package:cad/xyce[],
+package:www/libjwt[] and others.
+
+[NOTE]
+====
+Please make sure that tests do not break when updating a port.
+====
+
+
 [[testing-portclippy]]
 == Portclippy / Portfmt