Running Tests {#sec-running-nixos-tests}

You can run tests using nix-build. For example, to run the test login.nix, you do:

$ cd /my/git/clone/of/nixpkgs
$ nix-build -A nixosTests.login

After building/downloading all required dependencies, this will perform a build that starts a QEMU/KVM virtual machine containing a NixOS system. The virtual machine mounts the Nix store of the host; this makes VM creation very fast, as no disk image needs to be created. Afterwards, you can view a log of the test:

$ nix-store --read-log result

System Requirements {#sec-running-nixos-tests-requirements}

NixOS tests using QEMU virtual machine nodes require virtualization support. This means that the machine must have kvm in its system features list, or apple-virt in case of macOS. These features are autodetected locally, but apple-virt is only autodetected since Nix 2.19.0.

Features of remote builders must additionally be configured manually on the client, e.g. on NixOS with nix.buildMachines.*.supportedFeatures or through general Nix configuration.

If you run the tests on a macOS machine, you also need a "remote" builder for Linux; possibly a VM. nix-darwin users may enable nix.linux-builder.enable to launch such a VM.

NixOS tests using systemd-nspawn containers require the Nix daemon to be configured with the following settings:

{
  nix.settings = {
    auto-allocate-uids = true;
    extra-system-features = [ "uid-range" ];
    experimental-features = [
      "auto-allocate-uids"
      "cgroups"
    ];
  };
}

See the documentation of the settings auto-allocate-uids, uid-range, and cgroups for more information.

If the test uses both systemd-nspawn containers and QEMU virtual machine nodes and requires them share a common VLAN, /dev/net must be present in the sandbox. This allows them to be bridged over a TAP interface. To make this path available, set the following option:

{
  nix.settings.sandbox-paths = [ "/dev/net" ];
}