2 files changed, 177 insertions, 0 deletions
diff --git a/pybuild-autopkgtest b/pybuild-autopkgtest
new file mode 100755
index 0000000..5b3af8d
--- /dev/null
+++ b/pybuild-autopkgtest
@@ -0,0 +1,68 @@
+#! /usr/bin/env perl
+# vim: et ts=4 sw=4
+# Copyright © 2021 Antonio Terceiro <terceiro@debian.org>
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+use strict;
+use warnings;
+use File::Basename;
+use File::Temp qw( tempdir );
+use Debian::Debhelper::Buildsystem::pybuild;
+use Debian::Debhelper::Dh_Lib qw(doit);
+
+sub main {
+    my $tmpdir = tempdir( CLEANUP => 1);
+    my $run = "${tmpdir}/run";
+    open(RUN, ">", $run) or die($!);
+    print(RUN "#!/usr/bin/make -f\n");
+    print(RUN "include debian/rules\n");
+    print(RUN "pybuild-autopkgtest:\n");
+    printf(RUN "\tpybuild-autopkgtest\n");
+    close(RUN);
+    chmod(0755, $run);
+    $ENV{PYBUILD_AUTOPKGTEST} = "1";
+    if (system("grep -q ^before-pybuild-autopkgtest: debian/rules") == 0) {
+        doit($run, "before-pybuild-autopkgtest");
+    }
+    doit($run, "pybuild-autopkgtest");
+    if (system("grep -q ^after-pybuild-autopkgtest: debian/rules") == 0) {
+        doit($run, "after-pybuild-autopkgtest");
+    }
+}
+
+sub child {
+    # The child inherits the environment defined in debian/rules
+    my $dh = Debian::Debhelper::Buildsystem::pybuild->new();
+    foreach my $command ($dh->pybuild_commands('autopkgtest')) {
+        doit(@$command);
+    }
+}
+
+if (scalar(@ARGV) > 0) {
+    my $prog = basename($0);
+    print STDERR "usage: ${prog}\n";
+    exit(1);
+}
+
+if (defined $ENV{PYBUILD_AUTOPKGTEST}) {
+    child;
+} else {
+    main;
+}
diff --git a/pybuild-autopkgtest.rst b/pybuild-autopkgtest.rst
new file mode 100644
index 0000000..76da53d
--- /dev/null
+++ b/pybuild-autopkgtest.rst
@@ -0,0 +1,109 @@
+=====================
+ pybuild-autopkgtest
+=====================
+
+----------------------------------------------------------------------------------------------------
+invokes the test suite against requested Python versions and installed packages
+----------------------------------------------------------------------------------------------------
+
+:Manual section: 1
+:Author: Antonio Terceiro, 2021
+
+SYNOPSIS
+========
+  pybuild-autopkgtest
+
+OPTIONS
+=======
+
+`pybuild-autopkgtest` takes no options or arguments. All configuration is done
+via the same mechanisms you use to control `pybuild` itself, namely by having
+build dependencies on the right packages, or by setting `PYBUILD_*` environment
+variables in `debian/rules`.
+
+DESCRIPTION
+===========
+
+`pybuild-autopkgtest` is an autopkgtest test runner that reuses all the
+`pybuild` infrastructure to run tests against installed packages, as expected
+by autopkgtest. To enable `pybuild-autopkgtest` for your package, you need to
+add **Testsuite: autopkgtest-pkg-pybuild** to the source stanza in
+`debian/control`. This will cause autodep8(1) to produce the correct contents
+for `debian/tests/control`.
+
+`pybuild-autopkgtest` will run the tests in exactly the same way as `pybuild`
+will during the build, with the exception that the tests are not run in the
+build directory. The test files are copied to a temporary directory, so that
+the tests will run against the installed Python modules, and not against
+anything in the source tree.
+
+All the pybuild infrastructure is used, so for most packages you don't need to
+add any extra code configure for `pybuild-autopkgtest`. For example, just
+having a `python3-pytest` as a build dependency is enough to make the test
+runner use `pytest` to run the tests.
+
+The tests are executed via a temporary makefile that includes `debian/rules`
+from the package, so that any environment variables defined there will also be
+available during autopkgtest, including but not limited to `PYBUILD_*`
+variables for configuring the behavior of `pybuild` itself.
+
+ADOPTING PYBUILD-AUTOPKGTEST
+============================
+
+Since `pybuild-autopkgtest` reuses environment variables set in `debian/rules`,
+migrating packages to use `pybuild-autopkgtest` should not require much effort.
+
+You might have a `debian/tests/control` that duplicates what
+`pybuild-autopkgtest` already does, e.g. copying the test files to a temporary
+directory, changing to it, and running the tests from there. Such test entries
+can usually be removed in favor of adding **Testsuite:
+autopkgtest-pkg-pybuild** to `debian/control`.
+
+In general, you want to move any test-related command line arguments to pybuild
+into environment variables in `debian/rules`.
+
+You can also have specialized, manually-written test cases, alongside the ones
+autogenerated by `autodep8`. For this, both set **Testsuite:
+autopkgtest-pkg-pybuild** in `debian/control` and keep your custom tests in
+`debian/tests/control`.
+
+VARYING BEHAVIOR UNDER AUTOPKGTEST
+==================================
+
+Ideally, the behavior of the tests should be the same during the build and
+under autopkgtest, except for the fact that during autopkgtest the tests should
+load the code from the installed package. `pybuild-autopkgtest` should do this
+correctly most of the time.
+
+There are situations, however, in which you need a slightly different behavior
+during the autopkgtest run. There are a few mechanisms to support that:
+
+- `pybuild-autopkgtest` sets the `PYBUILD_AUTOPKGTEST` environment variable to
+  `1` during the test run. This way, you can add conditional behavior in
+  `debian/rules`.
+- Before and after running the tests, `pybuild-autopkgtest` will call the
+  `debian/rules` targets `before-pybuild-autopkgtest` and
+  `after-pybuild-autopkgtest`, respectively, if they exist.
+
+SAMPLE TEST CONTROL FILE
+========================
+
+The control file produced by autodep8(1) looks like this::
+
+    Test-Command: pybuild-autopkgtest
+    Depends: @, @builddeps@,
+    Restrictions: allow-stderr, skippable,
+    Features: test-name=pybuild-autopkgtest
+
+You should never need to hardcode this in `debian/tests/control`. You can add
+extra items to `Restrictions` and `Depends` by providing a configuration file
+for `autodep8` (`debian/tests/autopkgtest-pkg-pybuild.conf`) like this::
+
+    extra_depends=foo, bar
+    extra_restrictions=isolation-container, breaks-testbed
+
+SEE ALSO
+========
+* pybuild(1)
+* autopkgtest(1)
+* autodep8(1)