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

The branch main has been updated by fernape:

URL: https://cgit.FreeBSD.org/doc/commit/?id=becd110894c01e81dc9ad451ab34765cf9bf2f86

commit becd110894c01e81dc9ad451ab34765cf9bf2f86
Author:     Fernando Apesteguía <[email protected]>
AuthorDate: 2023-08-28 11:48:01 +0000
Commit:     Fernando Apesteguía <[email protected]>
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: https://reviews.freebsd.org/D41626
---
 .../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]#bsd.port.mk# 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.
 
+[[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