Building Build Tests
====================

{kiwi} provides a collection of integration test images for
different architectures and distributions. The test descriptions
cover a number of appliance features that can be built with {kiwi}.
The test descriptions are stored in a directory structure of the
following layout: `build-tests/ARCH/DISTRIBUTION/test-image-NAME`.
To build integration test image(s), the script `build-tests.sh`
exists.

The implementation of `build-tests.sh` calls kiwi's `boxbuild`
command, by default in container mode, which allows calling the script on
any host system that allows you to run container instances
via `podman`. The `--vm` option of `build-tests.sh` runs the build in a
virtual machine instead.

.. warning:: **Architectures**

   Cross-architecture image building is possible and also supported
   via boxbuild, but the performance impact is big, even in containers
   using qemu-binfmt, and even bigger in full qemu arch emulation.
   This would slow down building the integration tests a lot, and
   therefore, `build-tests.sh` requires the host architecture to
   match the image target architecture.

Prior to calling `build-tests.sh`, the following requirements must be met:

``Tools``

  Install the packages providing the following tools:

  * tree
  * git
  * xmllint
  * podman
  * pip

``Source Checkout``

  Check out the kiwi git repo, which provides the test descriptions
  as well as the `build-tests.sh` script.

  .. code:: bash

     $ git clone https://github.com/OSInside/kiwi.git

``kiwi``

  Install {kiwi}. It provides the boxbuild command used by
  `build-tests.sh`. If there are no {kiwi} packages for your host,
  install {kiwi} from pip:

  .. code:: bash

     $ pip install --upgrade kiwi

  .. warning::

     Make sure to be able to execute `kiwi-ng`. When installed from
     pip as a user, `kiwi-ng` is placed in `~/.local/bin`. Update your
     path via `export PATH=~/.local/bin:$PATH` if needed.

Building a specific integration test can be done as follows:

.. code:: bash

   $ cd kiwi
   $ ./build-tests.sh \
         --test-dir build-tests/x86/tumbleweed/ \
         --test-name test-image-disk

Building all integration tests for a specific arch and distribution
can be done as follows:

.. code:: bash

   $ cd kiwi
   $ ./build-tests.sh \
         --test-dir build-tests/x86/tumbleweed/

.. note::

   Building all integration tests can take some time and depends
   on the number of tests provided as well as on the build power
   of the host system. In general, the tests can also run in
   parallel or be distributed to multiple hosts.