.. task:: Autopkgtest

Autopkgtest task
----------------

The ``task_data`` associated to this task can contain the following keys:

* ``input`` (required): a dictionary describing the input data:

  * ``source_artifact`` (:ref:`lookup-single`, required): the
    :artifact:`debian:source-package` or :artifact:`debian:upload` artifact
    representing the source package to be tested with autopkgtest
  * ``binary_artifacts`` (:ref:`lookup-multiple`, required): a list of
    :artifact:`debian:binary-package` or :artifact:`debian:upload`
    artifacts representing the binary packages to be tested with
    autopkgtest (they are expected to be part of the same
    source package as the one identified with ``source_artifact``)
  * ``context_artifacts`` (:ref:`lookup-multiple`, optional): a list of
    :artifact:`debian:binary-package` or :artifact:`debian:upload`
    artifacts representing a special context for the tests. This is used
    to trigger autopkgtests of reverse dependencies, where
    ``context_artifacts`` is set to the artifacts of the updated package
    whose reverse dependencies are tested, and source/binary artifacts
    are one of the reverse dependencies whose autopkgtests will be
    executed.

* ``build_architecture`` (required): the Debian architecture that will be
  used in the chroot or VM where tests are going to be run.  The
  packages submitted in ``input:binary_artifacts`` usually have a matching
  architecture (but need not in the case of cross-architecture package
  testing, eg. testing i386 packages in an amd64 system).

* ``environment`` (:ref:`lookup-single` with default category
  :collection:`debian:environments`, required):
  :artifact:`debian:system-tarball` or :artifact:`debian:system-image`
  artifact (as appropriate for the selected backend) that will be used to
  run the tests.

* ``backend`` (optional): the virtualization backend to use, defaults to
  ``auto`` where the task is free to use the most suitable backend.
  Supported: ``incus-lxc``, ``incus-vm``, ``qemu``, and ``unshare``.

* ``include_tests`` (optional): a list of the tests that will be executed.
  If not provided (or empty), defaults to all tests being executed. Translates into
  ``--test-name=TEST`` command line options.

* ``exclude_tests`` (optional): a list of tests that will skipped.
  If not provided (or empty), then no tests are skipped. Translates into
  the ``--skip-test=TEST`` command line options.

* ``debug_level`` (optional, defaults to 0): a debug level between 0 and
  3. Translates into ``-d`` up to ``-ddd`` command line options.

* ``extra_repositories`` (optional): a list of extra repositories to enable.
  Each repository is described by the same dictionary as the
  ``extra_repositories`` option in the :task:`PackageBuild` task.

* ``use_packages_from_base_repository`` (optional, defaults to False): if
  True, then we pass ``--apt-default-release=$DISTRIBUTION`` with the name
  of the base distribution given in the ``distribution`` key.

* ``pin_packages`` (optional): a dictionary mapping release names (suites or
  codenames) to lists of package names; the package names can be either
  individual binary package names, or ``src:SOURCE`` to cover all binary
  packages built by source package ``SOURCE``.  Only the specified packages
  will be used from that release.  If installation of test dependencies fails,
  then it will be retried with the entirety of the given releases.  Translates
  into the ``--pin-packages=RELEASE=PACKAGE,...`` command line options.

  Note that this option is not very explicit about which versions ought to be
  tested, and where possible it is better to specify extra packages to use as
  test dependencies via ``input.context_artifacts`` instead.  However, the
  fallback behaviour of retrying test dependency installation with the entirety
  of the given releases is sometimes useful, and can only be achieved using
  this option.

* ``extra_environment`` (optional): a dictionary listing environment
  variables to inject in the build and test environment. Translates into
  (multiple) ``--env=VAR=VALUE`` command line options.

* ``needs_internet`` (optional, defaults to "run"): Translates directly
  into the ``--needs-internet`` command line option. Allowed values
  are "run", "try" and "skip".

* ``fail_on`` (optional): indicates whether the work request must be
  marked as failed in different scenario identified by the following
  sub-keys:

  * ``failed_test`` (optional, defaults to true): at least one test has
    failed (and the test was not marked as flaky).
  * ``flaky_test`` (optional, defaults to false): at least one flaky test
    has failed.
  * ``skipped_test`` (optional, defaults to false): at least one test has
    been skipped.

* ``timeout`` (optional): a dictionary where each key/value pair maps to
  the corresponding ``--timeout-KEY=VALUE`` command line option with the
  exception of the ``global`` key that maps to ``--timeout=VALUE``.
  Supported keys are ``global``, ``factor``, ``short``, ``install``, ``test``,
  ``copy`` and ``build``.

The task computes dynamic metadata as:

.. dynamic_data::
  :method: debusine.tasks.autopkgtest::Autopkgtest.compute_dynamic_data

autopkgtest is always run with the options ``--apt-upgrade
--output-dir=ARTIFACT-DIR --summary=ARTIFACT-DIR/summary --no-built-binaries``.

A :artifact:`debian:autopkgtest` artifact is generated to store all output
files.
