git: becd110894 - main - [phb]: Document make test

From: Fernando Apesteguía <>
Date: Tue, 29 Aug 2023 11:08:31 UTC
The branch main has been updated by fernape:


commit becd110894c01e81dc9ad451ab34765cf9bf2f86
Author:     Fernando Apesteguía <>
AuthorDate: 2023-08-28 11:48:01 +0000
Commit:     Fernando Apesteguía <>
CommitDate: 2023-08-29 11:07:05 +0000

    [phb]: Document make test
    Along with the relevant variables.
    PR:             248678
    Reported by:    diizzy@
    Reviewed by:    carlavilla@, ceri@
    Differential Revision:
 .../en/books/porters-handbook/testing/_index.adoc  | 29 ++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/documentation/content/en/books/porters-handbook/testing/_index.adoc b/documentation/content/en/books/porters-handbook/testing/_index.adoc
index 2efafe01e4..6f326f6ac8 100644
--- a/documentation/content/en/books/porters-handbook/testing/_index.adoc
+++ b/documentation/content/en/books/porters-handbook/testing/_index.adoc
@@ -65,6 +65,35 @@ See [.filename] for the meaning of the string produced.
 Also note that running a recent version of `portlint` (as specified in the next section) will cause `make describe` to be run automatically.
+== 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 ``.
+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.
+Please make sure that tests do not break when updating a port.
 == Portclippy / Portfmt