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
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…
};

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

@ -6,15 +6,9 @@
<programlisting language="bash">
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 <literal>testScript</literal> 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 <literal>machine</literal> (if you need
only one machine in your test) or by the attribute
<literal>nodes</literal> (if you need multiple machines). For
instance,
<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
virtual console, whether device ownership is correctly maintained
when switching between consoles, and so on. On the other hand,
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>,
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 <literal>nodes</literal>.
</para>
<para>
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>.
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
<link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>.
It uses two client nodes to test correct locking across server
crashes.
</para>
<para>
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 <literal>name</literal> if this is also the
identifier of the machine in the declarative config. If you didn't
specify multiple machines using the <literal>nodes</literal>
attribute, it is just <literal>machine</literal>. The following
identifier of the machine in the declarative config. If you
specified a node <literal>nodes.machine</literal>, 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 &quot;Linux&quot; in machine.succeed(&quot;uname&quot;):
raise Exception(&quot;Wrong OS&quot;)
</programlisting>
<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
<literal>wait_for_unit</literal> or <literal>succeed</literal>). If
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">
import ./make-test-python.nix {
skipLint = true;
machine =
nodes.machine =
{ config, pkgs, ... }:
{ configuration…
};

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

@ -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; }
);