b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

nixosTest: Simplify doc by deprecating syntax sugar

Browse source
This commit is contained in:
Robert Hensing 2022-03-21 00:14:06 +01:00
parent b3de7202d1
commit ecbf5ae27a
3 changed files with 33 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

36
nixos/doc/manual/development/writing-nixos-tests.section.md
View file

@ -5,15 +5,9 @@ A NixOS test is a Nix expression that has the following structure:
```nix ```nix
import ./make-test-python.nix { import ./make-test-python.nix {
# Either the configuration of a single machine: # One or more machines:
machine =
{ config, pkgs, ... }:
{ configuration…
};
# Or a set of machines:
nodes = nodes =
{ machine1 = { machine =
{ config, pkgs, ... }: { … }; { config, pkgs, ... }: { … };
machine2 = machine2 =
{ config, pkgs, ... }: { … }; { config, pkgs, ... }: { … };
@ -29,17 +23,16 @@ import ./make-test-python.nix {
The attribute `testScript` is a bit of Python code that executes the The attribute `testScript` is a bit of Python code that executes the
test (described below). During the test, it will start one or more test (described below). During the test, it will start one or more
virtual machines, the configuration of which is described by the virtual machines, the configuration of which is described by
attribute `machine` (if you need only one machine in your test) or by the attribute `nodes`.
the attribute `nodes` (if you need multiple machines). For instance,
[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix) An example of a single-node test is
only needs a single machine to test whether users can log in [`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 on the virtual console, whether device ownership is correctly maintained
when switching between consoles, and so on. On the other hand, 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), [`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix).
which tests NFS client and server functionality in the It uses two client nodes to test correct locking across server crashes.
Linux kernel (including whether locks are maintained across server
crashes), requires three machines: a server and two clients.
There are a few special NixOS configuration options for test VMs: 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. 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 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 `name` if this is also the identifier of the machine in the declarative
config. If you didn\'t specify multiple machines using the `nodes` config. If you specified a node `nodes.machine`, the following example starts the
attribute, it is just `machine`. The following example starts the
machine, waits until it has finished booting, then executes a command machine, waits until it has finished booting, then executes a command
and checks that the output is more-or-less correct: 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") 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 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 `succeed`). If you have multiple machines, you can speed up the test by
starting them in parallel: starting them in parallel:
@ -303,7 +295,7 @@ For faster dev cycles it\'s also possible to disable the code-linters
```nix ```nix
import ./make-test-python.nix { import ./make-test-python.nix {
skipLint = true; skipLint = true;
machine = nodes.machine =
{ config, pkgs, ... }: { config, pkgs, ... }:
{ configuration… { configuration…
}; };

43
nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml
View file

@ -6,15 +6,9 @@
<programlisting language="bash"> <programlisting language="bash">
import ./make-test-python.nix { import ./make-test-python.nix {
# Either the configuration of a single machine: # One or more machines:
machine =
{ config, pkgs, ... }:
{ configuration…
};
# Or a set of machines:
nodes = nodes =
{ machine1 = { machine =
{ config, pkgs, ... }: { … }; { config, pkgs, ... }: { … };
machine2 = machine2 =
{ config, pkgs, ... }: { … }; { config, pkgs, ... }: { … };
@ -31,18 +25,18 @@ import ./make-test-python.nix {
The attribute <literal>testScript</literal> is a bit of Python code The attribute <literal>testScript</literal> is a bit of Python code
that executes the test (described below). During the test, it will that executes the test (described below). During the test, it will
start one or more virtual machines, the configuration of which is start one or more virtual machines, the configuration of which is
described by the attribute <literal>machine</literal> (if you need described by the attribute <literal>nodes</literal>.
only one machine in your test) or by the attribute </para>
<literal>nodes</literal> (if you need multiple machines). For <para>
instance, An example of a single-node test is
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link> <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>.
only needs a single machine to test whether users can log in on the It only needs a single machine to test whether users can log in on
virtual console, whether device ownership is correctly maintained the virtual console, whether device ownership is correctly
when switching between consoles, and so on. On the other hand, maintained when switching between consoles, and so on. An
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>, interesting multi-node test is
which tests NFS client and server functionality in the Linux kernel <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>.
(including whether locks are maintained across server crashes), It uses two client nodes to test correct locking across server
requires three machines: a server and two clients. crashes.
</para> </para>
<para> <para>
There are a few special NixOS configuration options for test VMs: 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 various actions, such as starting VMs, executing commands in the
VMs, and so on. Each virtual machine is represented as an object VMs, and so on. Each virtual machine is represented as an object
stored in the variable <literal>name</literal> if this is also the stored in the variable <literal>name</literal> if this is also the
identifier of the machine in the declarative config. If you didn't identifier of the machine in the declarative config. If you
specify multiple machines using the <literal>nodes</literal> specified a node <literal>nodes.machine</literal>, the following
attribute, it is just <literal>machine</literal>. The following
example starts the machine, waits until it has finished booting, example starts the machine, waits until it has finished booting,
then executes a command and checks that the output is more-or-less then executes a command and checks that the output is more-or-less
correct: correct:
@ -108,7 +101,7 @@ if not &quot;Linux&quot; in machine.succeed(&quot;uname&quot;):
raise Exception(&quot;Wrong OS&quot;) raise Exception(&quot;Wrong OS&quot;)
</programlisting> </programlisting>
<para> <para>
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 started when you first execute an action on them (such as
<literal>wait_for_unit</literal> or <literal>succeed</literal>). If <literal>wait_for_unit</literal> or <literal>succeed</literal>). If
you have multiple machines, you can speed up the test by starting you have multiple machines, you can speed up the test by starting
@ -554,7 +547,7 @@ machine.wait_for_unit(&quot;xautolock.service&quot;, &quot;x-session-user&quot;)
<programlisting language="bash"> <programlisting language="bash">
import ./make-test-python.nix { import ./make-test-python.nix {
skipLint = true; skipLint = true;
machine = nodes.machine =
{ config, pkgs, ... }: { config, pkgs, ... }:
{ configuration… { configuration…
}; };

1
nixos/lib/testing-python.nix
View file

@ -206,6 +206,7 @@ rec {
)]; )];
}; };
in 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 ( build-vms.buildVirtualNetwork (
nodes // lib.optionalAttrs (machine != null) { inherit machine; } nodes // lib.optionalAttrs (machine != null) { inherit machine; }
); );