NAME¶

pkgos-run-tests - run a package's shell script unit tests, in parallel

SYNOPSIS¶

pkgos-run-tests [-s|--serial] [-c|--concurrency N] [tests-dir]
pkgos-run-tests -h | --help

DESCRIPTION¶

pkgos-run-tests searches for executable test scripts named test_* under tests-dir (defaulting to tests if present, and runs them, in parallel by default, as every test is expected to run in its own sandbox.

It is modeled after iterate_on_hosts () of OCI's oci-cluster-upgrade-funcs: tests are started as background jobs, waiting for a bounded number of them at a time. As the exit code of a background job cannot be waited upon, each test records its own exit code and output in temporary files, so that failures are correctly reported, with the full output of the failing test, and so that the runner exits non-zero when at least one test failed.

A first line reports the number of tests and folders before anything runs, and a line of the form Running <test> is printed as every test starts, so that progress is visible while the suite runs; results are reported once the batches of folders they belong to are finished.

The intended use is from debian/rules of packages carrying such a test suite, for example with override_dh_install calling pkgos-run-tests tests. openstack-pkg-tools's own debian/rules invokes it from the source tree (this package cannot build-depend on itself), while packages like ikvswitch call the binary that this package ships in /usr/bin.

OPTIONS¶

-s, --serial

Run the tests one after the other, streaming the output of every test as it runs (in parallel mode, the output of a test is captured and only printed when it fails), which is handy to debug a single test.

-c, --concurrency N

At most N tests running concurrently. The default is one job per available CPU, as reported by nproc(1), which also can be set through the RUN_TESTS_MAX_PARALLEL variable.

tests-dir

The folder holding the test_* scripts (defaults to tests if present).

-h, --help

Print a short help message.

EXIT STATUS¶

Returns 0 when every test passed, and non-zero when at least one test failed (the full output of the failing tests is printed), or when the tests folder is missing.

SEE ALSO¶

dh(1), debhelper(7).

AUTHOR¶

This script and its man page: (c) 2026, Thomas Goirand <zigo@debian.org>, released under the Apache-2.0 license.