Commit ecbf5ae2 authored by Robert Hensing's avatar Robert Hensing
Browse files

nixosTest: Simplify doc by deprecating syntax sugar

parent b3de7202

nixos/doc/manual/development/writing-nixos-tests.section.md

+14 −22
Original line number Diff line number Diff line
@@ -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…

    };

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

+18 −25
Original line number Diff line number Diff line
@@ -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…

    };

nixos/lib/testing-python.nix

+1 −0
Original line number Diff line number Diff line
@@ -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; }

          );