commit: b2ad7639d04e296312820025c9b8f77d22272028 Author: Florian Schmaus <flo <AT> geekplace <DOT> eu> AuthorDate: Sun Aug 2 17:17:15 2020 +0000 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> CommitDate: Wed Aug 19 17:29:42 2020 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b2ad7639
ebuild-writing/functions/src_test: re-organize, merge sections Merge "Common src_test Tasks" and "Skipping Tests" sections into a new section right after "Sample src_test". Also forward the reader to the related paragraph on test-only dependencies in this new section. Before that, the src_test documentation page was silent about that, rather important, topic. This also includes the RESTRICT="!test? ( test )" idiom. Signed-off-by: Florian Schmaus <flo <AT> geekplace.eu> Closes: https://bugs.gentoo.org/735570 [Whitespace changes] Signed-off-by: Ulrich Müller <ulm <AT> 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() { </body> </section> +<section> +<title>Supporting test suites in packages</title> +<body> + +<p> +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. +</p> + +<codesample lang="ebuild"> +IUSE="test" +</codesample> + +<p> +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 +<uri link="::general-concepts/dependencies/#Test Dependencies"/> +for more information. +</p> + +<p> +Often the default <c>src_test</c> 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: +</p> + +<ul> + <li> + Needing to work with files which are disallowed by the sandbox. + </li> + <li>Requiring user input (<c>src_test</c> must not be interactive).</li> + <li>Requiring root privileges.</li> +</ul> + +<p> +Usually, removing the relevant test from the <c>Makefile</c> +using <c>sed</c> or skipping a particular <c>make</c> target is +sufficient. +</p> + +<p> +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 <c>RESTRICT="test"</c> in the ebuild. +</p> + +<note> +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. +</note> +</body> +</section> + <section> <title>Tests that require network or service access</title> <body> @@ -207,53 +267,5 @@ src_test() { </body> </section> -<section> -<title>Common <c>src_test</c> Tasks</title> -<body> -<p> -Often the default <c>src_test</c> 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: -</p> - -<ul> - <li> - Needing to work with files which are disallowed by the sandbox. - </li> - <li>Requiring user input (src_test must not be interactive).</li> - <li>Requiring root privileges.</li> -</ul> - -<p> -Usually, removing the relevant test from the <c>Makefile</c> -using <c>sed</c> or skipping a particular <c>make</c> target is -sufficient. -</p> - -<p> -Try to ensure that tests work properly for your ebuild. A good test -suite is extremely helpful for arch maintainers. -</p> - -</body> -</section> - -<section> -<title>Skipping Tests</title> -<body> -<p> -Sometimes it is necessary to skip tests entirely. This can be done by -setting <c>RESTRICT="test"</c> in the ebuild. -</p> - -<note> -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. -</note> -</body> -</section> - </chapter> </guide>
