diff options
Diffstat (limited to 'nixos/doc/manual/development')
3 files changed, 85 insertions, 25 deletions
diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md index a1431859ff5..d9c316f4b13 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -24,6 +24,8 @@ back into the test driver command line upon its completion. This allows you to inspect the state of the VMs after the test (e.g. to debug the test script). +## Reuse VM state {#sec-nixos-test-reuse-vm-state} + You can re-use the VM states coming from a previous run by setting the `--keep-vm-state` flag. @@ -33,3 +35,15 @@ $ ./result/bin/nixos-test-driver --keep-vm-state The machine state is stored in the `$TMPDIR/vm-state-machinename` directory. + +## Interactive-only test configuration {#sec-nixos-test-interactive-configuration} + +The `.driverInteractive` attribute combines the regular test configuration with +definitions from the [`interactive` submodule](#opt-interactive). This gives you +a more usable, graphical, but slightly different configuration. + +You can add your own interactive-only test configuration by adding extra +configuration to the [`interactive` submodule](#opt-interactive). + +To interactively run only the regular configuration, build the `<test>.driver` attribute +instead, and call it with the flag `result/bin/nixos-test-driver --interactive`. diff --git a/nixos/doc/manual/development/running-nixos-tests.section.md b/nixos/doc/manual/development/running-nixos-tests.section.md index 1bec023b613..33076f5dc2a 100644 --- a/nixos/doc/manual/development/running-nixos-tests.section.md +++ b/nixos/doc/manual/development/running-nixos-tests.section.md @@ -2,22 +2,11 @@ You can run tests using `nix-build`. For example, to run the test [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix), -you just do: +you do: ```ShellSession -$ nix-build '<nixpkgs/nixos/tests/login.nix>' -``` - -or, if you don't want to rely on `NIX_PATH`: - -```ShellSession -$ cd /my/nixpkgs/nixos/tests -$ nix-build login.nix -… -running the VM test script -machine: QEMU running (pid 8841) -… -6 out of 6 tests succeeded +$ cd /my/git/clone/of/nixpkgs +$ nix-build -A nixosTests.login ``` After building/downloading all required dependencies, this will perform diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index 6934bb0face..99704ec3c14 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -1,9 +1,9 @@ # Writing Tests {#sec-writing-nixos-tests} -A NixOS test is a Nix expression that has the following structure: +A NixOS test is a module that has the following structure: ```nix -import ./make-test-python.nix { +{ # One or more machines: nodes = @@ -21,10 +21,13 @@ import ./make-test-python.nix { } ``` -The attribute `testScript` is a bit of Python code that executes the +We refer to the whole test above as a test module, whereas the values +in [`nodes.<name>`](#opt-nodes) are NixOS modules themselves. + +The option [`testScript`](#opt-testScript) is a piece of Python code that executes the test (described below). During the test, it will start one or more virtual machines, the configuration of which is described by -the attribute `nodes`. +the option [`nodes`](#opt-nodes). An example of a single-node test is [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix). @@ -34,7 +37,54 @@ when switching between consoles, and so on. An interesting multi-node test is [`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix). It uses two client nodes to test correct locking across server crashes. -There are a few special NixOS configuration options for test VMs: +## Calling a test {#sec-calling-nixos-tests} + +Tests are invoked differently depending on whether the test is part of NixOS or lives in a different project. + +### Testing within NixOS {#sec-call-nixos-test-in-nixos} + +Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix). + +```nix + hostname = runTest ./hostname.nix; +``` + +Overrides can be added by defining an anonymous module in `all-tests.nix`. + +```nix + hostname = runTest { + imports = [ ./hostname.nix ]; + defaults.networking.firewall.enable = false; + }; +``` + +You can run a test with attribute name `hostname` in `nixos/tests/all-tests.nix` by invoking: + +```shell +cd /my/git/clone/of/nixpkgs +nix-build -A nixosTests.hostname +``` + +### Testing outside the NixOS project {#sec-call-nixos-test-outside-nixos} + +Outside the `nixpkgs` repository, you can instantiate the test by first importing the NixOS library, + +```nix +let nixos-lib = import (nixpkgs + "/nixos/lib") { }; +in + +nixos-lib.runTest { + imports = [ ./test.nix ]; + hostPkgs = pkgs; # the Nixpkgs package set used outside the VMs + defaults.services.foo.package = mypkg; +} +``` + +`runTest` returns a derivation that runs the test. + +## Configuring the nodes {#sec-nixos-test-nodes} + +There are a few special NixOS options for test VMs: `virtualisation.memorySize` @@ -121,7 +171,7 @@ The following methods are available on machine objects: least one will be returned. ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `get_screen_text` @@ -130,7 +180,7 @@ The following methods are available on machine objects: machine\'s screen using optical character recognition. ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `send_monitor_command` @@ -241,7 +291,7 @@ The following methods are available on machine objects: `get_screen_text` and `get_screen_text_variants`). ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `wait_for_console_text` @@ -304,7 +354,7 @@ For faster dev cycles it\'s also possible to disable the code-linters (this shouldn\'t be commited though): ```nix -import ./make-test-python.nix { +{ skipLint = true; nodes.machine = { config, pkgs, ... }: @@ -336,7 +386,7 @@ Similarly, the type checking of test scripts can be disabled in the following way: ```nix -import ./make-test-python.nix { +{ skipTypeCheck = true; nodes.machine = { config, pkgs, ... }: @@ -400,7 +450,6 @@ added using the parameter `extraPythonPackages`. For example, you could add `numpy` like this: ```nix -import ./make-test-python.nix { extraPythonPackages = p: [ p.numpy ]; @@ -417,3 +466,11 @@ import ./make-test-python.nix ``` In that case, `numpy` is chosen from the generic `python3Packages`. + +## Test Options Reference {#sec-test-options-reference} + +The following options can be used when writing tests. + +```{=docbook} +<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/> +``` |