Supporting test suites in packages

gentoo.org> ebuild-writing/functions/src_test/text.xml | 108 ++++++++++++++++------------- 1 file changed, 60 insertions(+), 48 deletions(-) diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml index c278aa0..fbd0751 100644 --- a/ebuild-writing/functions/src_test/text.xml +++ b/ebuild-writing/functions/src_test/text.xml @@ -62,6 +62,66 @@ src_test() { +

+Supporting test suites in packages + + +

+If the packaged software is equipped with a test suite, it is sensible +to make the package aware of it. This allows the package manager to +run the software's unit tests. Packages with a test suite must +announce the "test" USE flag. +

+ + +IUSE="test" + + +

+The next important aspect to consider are test-only dependencies, i.e. +dependencies that are only required to run the test suite. Test-only +dependencies should be specified in a DEPEND behind a USE flag. +Please refer to the section on + +for more information. +

+ +

+Often the default src_test is fine. Sometimes it is necessary +to remove certain tests from the list if they cannot be used with a +portage environment. Reasons for such a failure could include: +

+ +

+ Needing to work with files which are disallowed by the sandbox. +
Requiring user input (src_test must not be interactive).
Requiring root privileges.

+ +

+Usually, removing the relevant test from the Makefile +using sed or skipping a particular make target is +sufficient. +

+ +

+Try to ensure that tests work properly for your ebuild. A good test +suite is extremely helpful for arch maintainers. +Sometimes it is necessary to skip tests entirely. This can be done by +setting RESTRICT="test" in the ebuild. +

+ + +If upstream provides a test suite that doesn't work, consider talking +to them about getting it fixed. A broken test suite requires developers +to investigate each test failure in order to determine whether it is +genuine or indicates a broken test. + + +

Tests that require network or service access @@ -207,53 +267,5 @@ src_test() {

-Common <c>src_test</c> Tasks - -

-Often the default src_test is fine. Sometimes it is necessary -to remove certain tests from the list if they cannot be used with a -portage environment. Reasons for such a failure could include: -

- -

- Needing to work with files which are disallowed by the sandbox. -
Requiring user input (src_test must not be interactive).
Requiring root privileges.

- -

-Usually, removing the relevant test from the Makefile -using sed or skipping a particular make target is -sufficient. -

- -

-Try to ensure that tests work properly for your ebuild. A good test -suite is extremely helpful for arch maintainers. -

- - -

- -

-Skipping Tests - -

-Sometimes it is necessary to skip tests entirely. This can be done by -setting RESTRICT="test" in the ebuild. -

- - -If upstream provides a test suite that doesn't work, consider talking -to them about getting it fixed. A broken test suite requires developers -to investigate each test failure in order to determine whether it is -genuine or indicates a broken test. - - -