Skip to content

Latest commit

 

History

History
355 lines (287 loc) · 14 KB

external-tests.md

File metadata and controls

355 lines (287 loc) · 14 KB
Raw
parent nav_order
Testing with Kola
2

Integrating external test suites

{: .no_toc }

  1. TOC {:toc}

Rationale

Fedora CoreOS is comprised of a number of upstream projects, from the Linux kernel to systemd, ostree, Ignition, podman and numerous others.

We want to support keeping tests in their respective upstream repositories, and allow these projects to target Fedora CoreOS in e.g. their own CI. And we also want to run unmodified upstream tests, without rebuilding the project.

Using kola run with externally defined tests

The --exttest (-E) argument to kola run is one way to accomplish this; you provide the path to an upstream project git repository. Tests will be found in the tests/kola directory. If this project contains binaries that require building, it is assumed that make (or equivalent) has already been invoked.

In addition to using -E, you may also copy tests to /usr/lib/coreos-assembler/tests/kola.

The tests/kola directory will be traversed recursively to find tests.

The core idea is to express a test as a single binary (plus an optional directory of dependencies named data) that will be uploaded to a CoreOS system and run as a systemd unit, along with an optional Ignition config named config.ign.

Concretely then, an external test directory can have the following content:

  • config.ign (optional): Ignition config provided
  • config.bu (optional): See https://coreos.github.io/butane/
  • kola.json (optional): JSON file described below
  • data (optional): Directory (or symlink to dir): Will be uploaded and available as ${KOLA_EXT_DATA}
  • one or more executables: Each executable is its own test, run independently with the Ignition config and/or dependency data provided.

Normally the test will be named ext.<projname>.<subdirectory>.<executable>. However there is a special case to make it nicer to test Ignition configs; In the case of a test directory with a single executable named test.sh, the kola test name will be ext.<projname>.<subdirectory> (i.e. test.sh will be omitted).

Currently the test systemd unit runs with full privileges - tests are assumed to be (potentially) destructive and a general assumption is tests are run in easily disposable virtual machines. A future enhancement will support nondestructive tests.

A best practice for doing this is to write your tests in a language that compiles to a single binary - Rust and Go for example, but there exist for example tools like PyInstaller too. This way you can usually avoid the need for a data directory.

This mechanism is suitable for testing most userspace components of CoreOS; for example, one can have the binary drive a container runtime.

A test is considered failed if the unit exits with any non-zero exit status or dies from any signal other than SIGTERM.

Environment variables

The following environment variables are accessible to the test:

  • KOLA_EXT_DATA: path to test data; see above
  • KOLA_UNIT: name of systemd unit running the test itself
  • KOLA_TEST: name of the kola test
  • KOLA_TEST_EXE: basename of the test executable as found by kola

Support for rebooting

An important feature of exttests is support for rebooting the host system. This allows one to easily test OS updates for example. In order to more easily allow sharing tests, kola has adopted a subset of the Debian autopkgtest interface.

See the section titled Reboot during a test there. For convenience an example is included below:

#!/bin/bash
# Copy of the reboot example from https://salsa.debian.org/ci-team/autopkgtest/raw/master/doc/README.package-tests.rst
set -xeuo pipefail
case "${AUTOPKGTEST_REBOOT_MARK:-}" in
  "") echo "test beginning"; /tmp/autopkgtest-reboot mark1 ;;
  mark1) echo "test in mark1"; /tmp/autopkgtest-reboot mark2 ;;
  mark2) echo "test in mark2" ;;
  *) echo "unexpected mark: ${AUTOPKGTEST_REBOOT_MARK}"; exit 1;;
esac
echo "ok autopkgtest rebooting"

This will trigger the monitoring kola process to invoke a reboot.

The rationale for this is that it helps kola to know when a reboot is happening so that it can correctly follow the state of the systemd journal, etc. A future enhancement will support directly invoking reboot and having kola just figure it out.

(Previously the API for this was to send SIGTERM to the current process; that method is deprecated and will be removed at some point)

HTTP Server

The kolet binary is copied into the /usr/local/bin/ directory on the CoreOS system running the tests. Notably, it contains the built-in command kolet httpd for starting an HTTP file server to serve the contents of the file system. By default, it starts the server listening on port 80 and serves the contents of the file system at ./; you can use the --port and --path flags to override the defaults.

For example, if you're using a bash script as your test, you can start an HTTP server to serve the contents at /var/home/core like this:

echo testdata > /var/home/core/testdata.txt
systemd-run /usr/local/bin/kolet httpd --path /var/home/core/
# It may take some time for the server to start.
sleep 1
curl localhost/testdata.txt

Alternatively, you can create an Ignition config (or Fedora CoreOS config) and include it in your external test directory. This would start the HTTP server before your test is run and may be useful if you would like to predefine the files to serve.

In the following Fedora CoreOS config example, the Ignition config includes a path unit and a service unit. The path unit ensures that the httpd service runs automatically once the Kolet binary is copied to the system. Note that the path unit has a Before= dependency on kola-runext.service to ensure that the server is brought up before the test is run. An HTTP server will be started at localhost and serve the files in /var/www/. Your test can then do e.g. curl localhost/hello_world.txt.

Example:

variant: fcos
version: 1.1.0
systemd:
  units:
    - name: kolet-httpd.path
      enabled: true
      contents: |
        [Unit]
        Before=kola-runext.service
        [Path]
        PathExists=/usr/local/bin/kolet
        [Install]
        WantedBy=kola-runext.service
    - name: kolet-httpd.service
      contents: |
        [Service]
        ExecStart=/usr/local/bin/kolet httpd --path /var/www -v
        [Install]
        WantedBy=kola-runext.service
storage:
  files:
    - path: /var/www/my-kola-test-data
      contents:
        inline: Hello, world!
      mode: 0644
      user:
        name: core
      group:
        name: core

kola.json

Kola internally supports limiting tests to specific architectures and plaforms, as well as "clusters" of machines that have size > 1. External tests are hardcoded to 1 machine at the moment.

Here's an example kola.json:

{
    "architectures": "!s390x ppc64le",
    "distros": "fcos",
    "platforms": "qemu",
    "tags": "sometagname needs-internet skip-base-checks othertag",
    "requiredTag": "special",
    "primaryDisk": ["20G:mpath"],
    "additionalDisks": [ "5G" ],
    "minMemory": 4096,
    "minDisk": 15,
    "additionalNics": 2,
    "appendKernelArgs": "enforcing=0"
    "appendFirstbootKernelArgs": "ip=bond0:dhcp bond=bond0:ens5,ens6:mode=active-backup,miimon=100"
    "timeoutMin": 8,
    "exclusive": true,
    "conflicts": ["ext.config.some-test", "podman.some-other-test"],
    "description": "test description"
}

The only supported keys are those mentioned above; any or none may be provided as well. For architectures, platforms and tags, each value is a single string, which is a whitespace-separated list. The reason to use a single string (instead of a native JSON list) is twofold. First, it's easier to type than a JSON list, and we don't need to support values with whitespace. Second, for architectures and platforms by providing ! at the front of the string, the value instead declares exclusions i.e. ExclusiveArchitectures instead of Architectures in reference to kola internals. The distros tag can be used to restrict a test to run on just one distribution, either fcos or rhcos. By default, tests will run on all distributions. (Typically, the distros key is used to restrict a test to just fcos.)

In this example, sometagname and othertag are arbitrary tags one can use with kola run --tag, but some tags have semantic meaning.

Tags with semantic meaning:

  • needs-internet: Taken from the Autopkgtest (linked above). Currently only the qemu platform enforces this restriction.
  • platform-independent: This test should pass or fail on all platforms (clouds and hardware architectures); it may be run less often.
  • skip-base-checks: Skip built-in checks for e.g. kernel warnings on the console or systemd unit failures.

If a test has a requiredTag, it is run only if the required tag is specified. In the example above, the test would only run if --tag special was provided.

The additionalDisks key has the same semantics as the --add-disk argument to qemuexec. It is currently only supported on qemu. The primaryDisk key also supports the same syntax and controls the primary boot disk. Only for the primaryDisk key, the size can be omitted (e.g. :mpath), in which case the qcow2 will not be resized.

The injectContainer boolean if set will cause the framework to inject the ostree base image container into the target system; the path can be found in the environment variable KOLA_EXT_OSTREE_OCIARCHIVE. This will be an .ociarchive file that can be e.g. loaded into the containers storage via skopeo copy oci-archive:$KOLA_EXT_OSTREE_OCIARCHIVE containers-storage:localhost/os.

The minDisk key takes a size in GB and ensures that an instance type with at least the specified amount of primary disk space is used. On QEMU, this is equivalent to the --qemu-size argument to qemuexec. This is currently only enforced on qemu and aws.

The minMemory key takes a size in MB and ensures that an instance type with at least the specified amount of memory is used. On QEMU, this is equivalent to the --memory argument to qemuexec. This is currently only enforced on qemu.

The additionalNics key has the same semantics as the --additional-nics argument to qemuexec. It is currently only supported on qemu.

The appendKernelArgs key has the same semantics at the --kargs argument to qemuexec. It is currently only supported on qemu.

The appendFirstbootKernelArgs key has the same semantics at the --firstbootkargs argument to qemuexec. It is currently only supported on qemu.

The timeoutMin key takes a positive integer and specifies a timeout for the test in minutes. After the specified amount of time, the test will be interrupted.

The exclusive key takes a boolean value. If true, the test will be run by itself in its own VM such that other tests do not conflict with it. If this key is marked false, the test is run with other "non-exclusive" tests. If a test is simple and is not expected to conflict with other tests, it should be marked exclusive: false. When the exclusive key is not provided, tests are marked exclusive: true by default.

The conflicts key takes a list of test names that conflict with this test. This key can only be specified if exclusive is marked false since exclusive: true tests are run exclusively in their own VM. At runtime, this test will be separated from the tests it is conflicting with.

More recently, you can also (useful for shell scripts) include the JSON file inline per test, like this:

#!/bin/bash
set -xeuo pipefail
# kola: { "architectures": "x86_64", "platforms": "aws gcp", "tags": "needs-internet", "description": "test" }
test code here

This metadata stanza must start with # kola: and have a single line of JSON.

Even more recently, you can write the test metadata as YAML inline; this is signified by using ## kola: . The lines after it starting with ## will be parsed as metadata YAML. For example:

#!/bin/bash
set -xeuo pipefail
## kola:
##   architectures: x86_64
##   platforms: "aws gcp"  # azure support is pending
##   tags: needs-internet
##   description: test description
test code here

A notable advantage of YAML here is support for inline comments.

Quick Start

  1. In your project's upstream repository, create the tests/kola directory, if it does not already exist
  2. Move into it and find or create an appropriate subdirectory for your test to live in
  3. Add your test to the subdirectory and make sure it is executable (chmod a+x)
  4. Your test should now be able to be run by kola when you provide the --exttest (-E) argument to kola run

Example

Say we want to add a simple noop test in the project my-project externally. If we follow the above instructions, it would look like this:

$ git clone [email protected]:$GITHUB_USERNAME/my-project.git
$ cd my-project/tests/kola
$ $EDITOR basic/noop # Add the `noop` test
#!/bin/bash
set -xeuo pipefail
# kola: { "architectures": "x86_64", "platforms": "qemu", "tags": "needs-internet", "description": "test" }
# Test: I'm a NOOP!
test 2 -gt 1
$ chmod a+x basic/noop # Make sure the test is executable
$ cosa kola run -p qemu --qemu-image path/to/qcow2 -E path/to/my-project/ 'ext.my-project.basic' # Run the test
=== RUN   ext.my-project.basic
--- PASS: ext.my-project.basic (35.57s)
PASS, output in _kola_temp/qemu-2020-08-18-1815-2295199

Fast build and iteration on your project's tests

First, use cosa build-fast if it applies to you (e.g. you're not working on something in the kernel or initramfs). From your project's git repository, do e.g.:

$ export COSA_DIR=/path/to/cosadir
$ cosa build-fast
$ kola run --qemu-image fastbuild*.qcow2 'ext.*'

Whenever you change your project's code, rerun cosa build-fast to create a new qcow2. If you just changed a test script, you can just directly rerun kola.

For more tips, see also the Working with CoreOS Assembler.