From ecbf5ae27a9ee6e877a20e3abce85c21e4bda9c2 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Mon, 21 Mar 2022 00:14:06 +0100 Subject: [PATCH] nixosTest: Simplify doc by deprecating syntax sugar --- .../writing-nixos-tests.section.md | 36 ++++++---------- .../writing-nixos-tests.section.xml | 43 ++++++++----------- nixos/lib/testing-python.nix | 1 + 3 files changed, 33 insertions(+), 47 deletions(-) diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index 433e1906f775..a9ffffe2277c 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -5,15 +5,9 @@ A NixOS test is a Nix expression that has the following structure: ```nix import ./make-test-python.nix { - # Either the configuration of a single machine: - machine = - { config, pkgs, ... }: - { configuration… - }; - - # Or a set of machines: + # One or more machines: nodes = - { machine1 = + { machine = { config, pkgs, ... }: { … }; machine2 = { config, pkgs, ... }: { … }; @@ -29,17 +23,16 @@ import ./make-test-python.nix { The attribute `testScript` is a bit 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 `machine` (if you need only one machine in your test) or by -the attribute `nodes` (if you need multiple machines). For instance, -[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix) -only needs a single machine to test whether users can log in +virtual machines, the configuration of which is described by +the attribute `nodes`. + +An example of a single-node test is +[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix). +It only needs a single machine to test whether users can log in on the virtual console, whether device ownership is correctly maintained -when switching between consoles, and so on. On the other hand, -[`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix), -which tests NFS client and server functionality in the -Linux kernel (including whether locks are maintained across server -crashes), requires three machines: a server and two clients. +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: @@ -67,8 +60,7 @@ The test script is a sequence of Python statements that perform various actions, such as starting VMs, executing commands in the VMs, and so on. Each virtual machine is represented as an object stored in the variable `name` if this is also the identifier of the machine in the declarative -config. If you didn\'t specify multiple machines using the `nodes` -attribute, it is just `machine`. The following example starts the +config. If you specified a node `nodes.machine`, the following example starts the machine, waits until it has finished booting, then executes a command and checks that the output is more-or-less correct: @@ -79,7 +71,7 @@ if not "Linux" in machine.succeed("uname"): raise Exception("Wrong OS") ``` -The first line is actually unnecessary; machines are implicitly started +The first line is technically unnecessary; machines are implicitly started when you first execute an action on them (such as `wait_for_unit` or `succeed`). If you have multiple machines, you can speed up the test by starting them in parallel: @@ -303,7 +295,7 @@ For faster dev cycles it\'s also possible to disable the code-linters ```nix import ./make-test-python.nix { skipLint = true; - machine = + nodes.machine = { config, pkgs, ... }: { configuration… }; diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml index 4f856f98f2a2..b194d58e5beb 100644 --- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml +++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml @@ -6,15 +6,9 @@ import ./make-test-python.nix { - # Either the configuration of a single machine: - machine = - { config, pkgs, ... }: - { configuration… - }; - - # Or a set of machines: + # One or more machines: nodes = - { machine1 = + { machine = { config, pkgs, ... }: { … }; machine2 = { config, pkgs, ... }: { … }; @@ -31,18 +25,18 @@ import ./make-test-python.nix { The attribute testScript is a bit 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 machine (if you need - only one machine in your test) or by the attribute - nodes (if you need multiple machines). For - instance, - login.nix - only needs a single machine to test whether users can log in on the - virtual console, whether device ownership is correctly maintained - when switching between consoles, and so on. On the other hand, - nfs/simple.nix, - which tests NFS client and server functionality in the Linux kernel - (including whether locks are maintained across server crashes), - requires three machines: a server and two clients. + described by the attribute nodes. + + + An example of a single-node test is + login.nix. + It only needs a single machine to test whether users can log in on + the virtual console, whether device ownership is correctly + maintained when switching between consoles, and so on. An + interesting multi-node test is + 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: @@ -94,9 +88,8 @@ import ./make-test-python.nix { various actions, such as starting VMs, executing commands in the VMs, and so on. Each virtual machine is represented as an object stored in the variable name if this is also the - identifier of the machine in the declarative config. If you didn't - specify multiple machines using the nodes - attribute, it is just machine. The following + identifier of the machine in the declarative config. If you + specified a node nodes.machine, the following example starts the machine, waits until it has finished booting, then executes a command and checks that the output is more-or-less correct: @@ -108,7 +101,7 @@ if not "Linux" in machine.succeed("uname"): raise Exception("Wrong OS") - The first line is actually unnecessary; machines are implicitly + The first line is technically unnecessary; machines are implicitly started when you first execute an action on them (such as wait_for_unit or succeed). If you have multiple machines, you can speed up the test by starting @@ -554,7 +547,7 @@ machine.wait_for_unit("xautolock.service", "x-session-user") import ./make-test-python.nix { skipLint = true; - machine = + nodes.machine = { config, pkgs, ... }: { configuration… }; diff --git a/nixos/lib/testing-python.nix b/nixos/lib/testing-python.nix index facc7a253a75..cd2bb2f9d4d4 100644 --- a/nixos/lib/testing-python.nix +++ b/nixos/lib/testing-python.nix @@ -206,6 +206,7 @@ rec { )]; }; in + lib.warnIf (t?machine) "In test `${name}': The `machine' attribute in NixOS tests (pkgs.nixosTest / make-test-pyton.nix / testing-python.nix / makeTest) is deprecated. Please use the equivalent `nodes.machine'." build-vms.buildVirtualNetwork ( nodes // lib.optionalAttrs (machine != null) { inherit machine; } );