diff options
author | Robert Hensing <robert@roberthensing.nl> | 2022-05-05 12:41:34 +0200 |
---|---|---|
committer | Robert Hensing <robert@roberthensing.nl> | 2022-05-05 12:48:47 +0200 |
commit | 7edb41466086f8cd19fc738e8f9c46b7c64fe182 (patch) | |
tree | e69fed8dd94238eed42dc38a79cd21ceda9c15e0 /doc/builders | |
parent | 28f99aad3180b8da8db1bd2f8bbe98947de867c3 (diff) |
testers.nixosTest: Move from top-level and improve docs
Diffstat (limited to 'doc/builders')
-rw-r--r-- | doc/builders/testers.chapter.md | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md index 2c30c8bd240e1..06434c0467e68 100644 --- a/doc/builders/testers.chapter.md +++ b/doc/builders/testers.chapter.md @@ -80,3 +80,49 @@ tests.fetchgit = invalidateFetcherByDrvHash fetchgit { sha256 = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY="; }; ``` + +## `nixosTest` {#tester-nixosTest} + +Run a NixOS VM network test using this evaluation of Nixpkgs. + +NOTE: This function is primarily for external use. NixOS itself uses `make-test-python.nix` directly. + +It is mostly equivalent to the function `import ./make-test-python.nix` from the +[NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), +except that the current application of Nixpkgs (`pkgs`) will be used, instead of +letting NixOS invoke Nixpkgs anew. + +If a test machine needs to set NixOS options under `nixpkgs`, it must set only the +`nixpkgs.pkgs` option. + +### Parameter + +A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), or path to it. Example: + +```nix +{ + name = "my-test"; + nodes = { + machine1 = { lib, pkgs, nodes, ... }: { + environment.systemPackages = [ pkgs.hello ]; + services.foo.enable = true; + }; + # machine2 = ...; + }; + testScript = '' + start_all() + machine1.wait_for_unit("foo.service") + machine1.succeed("hello | foo-send") + ''; +} +``` + +### Result + +A derivation that runs the VM test. + +Notable attributes: + + * `nodes`: the evaluated NixOS configurations. Useful for debugging and exploring the configuration. + + * `driverInteractive`: a script that launches an interactive Python session in the context of the `testScript`. |