commit ecbf5ae27a9ee6e877a20e3abce85c21e4bda9c2 · pyrox.dev/nixpkgs

+14 -22

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

···

       5
       5
        
       ```nix

     

       6
       6
        
       import ./make-test-python.nix {

     

       7
       7
        
       

     

       8
       8
       -
         # Either the configuration of a single machine:

     

       9
       9
       -
         machine =

     

       10
       10
       -
           { config, pkgs, ... }:

     

       11
       11
       -
           { configuration…

     

       12
       12
       -
           };

     

       13
       13
       -
       

     

       14
       14
       -
         # Or a set of machines:

     

       8
       8
       +
         # One or more machines:

     

       15
       9
        
         nodes =

     

       16
       16
       -
           { machine1 =

     

       10
       10
       +
           { machine =

     

       17
       11
        
               { config, pkgs, ... }: { … };

     

       18
       12
        
             machine2 =

     

       19
       13
        
               { config, pkgs, ... }: { … };

     
···

       29
       23
        
       

     

       30
       24
        
       The attribute `testScript` is a bit of Python code that executes the

     

       31
       25
        
       test (described below). During the test, it will start one or more

     

       32
       32
       -
       virtual machines, the configuration of which is described by the

     

       33
       33
       -
       attribute `machine` (if you need only one machine in your test) or by

     

       34
       34
       -
       the attribute `nodes` (if you need multiple machines). For instance,

     

       35
       35
       -
       [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix)

     

       36
       36
       -
       only needs a single machine to test whether users can log in

     

       26
       26
       +
       virtual machines, the configuration of which is described by

     

       27
       27
       +
       the attribute `nodes`.

     

       28
       28
       +
       

     

       29
       29
       +
       An example of a single-node test is

     

       30
       30
       +
       [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix).

     

       31
       31
       +
       It only needs a single machine to test whether users can log in

     

       37
       32
        
       on the virtual console, whether device ownership is correctly maintained

     

       38
       38
       -
       when switching between consoles, and so on. On the other hand,

     

       39
       39
       -
       [`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix),

     

       40
       40
       -
       which tests NFS client and server functionality in the

     

       41
       41
       -
       Linux kernel (including whether locks are maintained across server

     

       42
       42
       -
       crashes), requires three machines: a server and two clients.

     

       33
       33
       +
       when switching between consoles, and so on. An interesting multi-node test is

     

       34
       34
       +
       [`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix).

     

       35
       35
       +
       It uses two client nodes to test correct locking across server crashes.

     

       43
       36
        
       

     

       44
       37
        
       There are a few special NixOS configuration options for test VMs:

     

       45
       38
        
       

     
···

       67
       60
        
       actions, such as starting VMs, executing commands in the VMs, and so on.

     

       68
       61
        
       Each virtual machine is represented as an object stored in the variable

     

       69
       62
        
       `name` if this is also the identifier of the machine in the declarative

     

       70
       70
       -
       config. If you didn\'t specify multiple machines using the `nodes`

     

       71
       71
       -
       attribute, it is just `machine`. The following example starts the

     

       63
       63
       +
       config. If you specified a node `nodes.machine`, the following example starts the

     

       72
       64
        
       machine, waits until it has finished booting, then executes a command

     

       73
       65
        
       and checks that the output is more-or-less correct:

     

       74
       66
        
       

     
···

       79
       71
        
         raise Exception("Wrong OS")

     

       80
       72
        
       ```

     

       81
       73
        
       

     

       82
       82
       -
       The first line is actually unnecessary; machines are implicitly started

     

       74
       74
       +
       The first line is technically unnecessary; machines are implicitly started

     

       83
       75
        
       when you first execute an action on them (such as `wait_for_unit` or

     

       84
       76
        
       `succeed`). If you have multiple machines, you can speed up the test by

     

       85
       77
        
       starting them in parallel:

     
···

       303
       295
        
       ```nix

     

       304
       296
        
       import ./make-test-python.nix {

     

       305
       297
        
         skipLint = true;

     

       306
       306
       -
         machine =

     

       298
       298
       +
         nodes.machine =

     

       307
       299
        
           { config, pkgs, ... }:

     

       308
       300
        
           { configuration…

     

       309
       301
        
           };

+18 -25

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

···

       6
       6
        
         <programlisting language="bash">

     

       7
       7
        
       import ./make-test-python.nix {

     

       8
       8
        
       

     

       9
       9
       -
         # Either the configuration of a single machine:

     

       10
       10
       -
         machine =

     

       11
       11
       -
           { config, pkgs, ... }:

     

       12
       12
       -
           { configuration…

     

       13
       13
       -
           };

     

       14
       14
       -
       

     

       15
       15
       -
         # Or a set of machines:

     

       9
       9
       +
         # One or more machines:

     

       16
       10
        
         nodes =

     

       17
       17
       -
           { machine1 =

     

       11
       11
       +
           { machine =

     

       18
       12
        
               { config, pkgs, ... }: { … };

     

       19
       13
        
             machine2 =

     

       20
       14
        
               { config, pkgs, ... }: { … };

     
···

       31
       25
        
           The attribute <literal>testScript</literal> is a bit of Python code

     

       32
       26
        
           that executes the test (described below). During the test, it will

     

       33
       27
        
           start one or more virtual machines, the configuration of which is

     

       34
       34
       -
           described by the attribute <literal>machine</literal> (if you need

     

       35
       35
       -
           only one machine in your test) or by the attribute

     

       36
       36
       -
           <literal>nodes</literal> (if you need multiple machines). For

     

       37
       37
       -
           instance,

     

       38
       38
       -
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>

     

       39
       39
       -
           only needs a single machine to test whether users can log in on the

     

       40
       40
       -
           virtual console, whether device ownership is correctly maintained

     

       41
       41
       -
           when switching between consoles, and so on. On the other hand,

     

       42
       42
       -
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>,

     

       43
       43
       -
           which tests NFS client and server functionality in the Linux kernel

     

       44
       44
       -
           (including whether locks are maintained across server crashes),

     

       45
       45
       -
           requires three machines: a server and two clients.

     

       28
       28
       +
           described by the attribute <literal>nodes</literal>.

     

       29
       29
       +
         </para>

     

       30
       30
       +
         <para>

     

       31
       31
       +
           An example of a single-node test is

     

       32
       32
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>.

     

       33
       33
       +
           It only needs a single machine to test whether users can log in on

     

       34
       34
       +
           the virtual console, whether device ownership is correctly

     

       35
       35
       +
           maintained when switching between consoles, and so on. An

     

       36
       36
       +
           interesting multi-node test is

     

       37
       37
       +
           <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix"><literal>nfs/simple.nix</literal></link>.

     

       38
       38
       +
           It uses two client nodes to test correct locking across server

     

       39
       39
       +
           crashes.

     

       46
       40
        
         </para>

     

       47
       41
        
         <para>

     

       48
       42
        
           There are a few special NixOS configuration options for test VMs:

     
···

       94
       88
        
           various actions, such as starting VMs, executing commands in the

     

       95
       89
        
           VMs, and so on. Each virtual machine is represented as an object

     

       96
       90
        
           stored in the variable <literal>name</literal> if this is also the

     

       97
       97
       -
           identifier of the machine in the declarative config. If you didn't

     

       98
       98
       -
           specify multiple machines using the <literal>nodes</literal>

     

       99
       99
       -
           attribute, it is just <literal>machine</literal>. The following

     

       91
       91
       +
           identifier of the machine in the declarative config. If you

     

       92
       92
       +
           specified a node <literal>nodes.machine</literal>, the following

     

       100
       93
        
           example starts the machine, waits until it has finished booting,

     

       101
       94
        
           then executes a command and checks that the output is more-or-less

     

       102
       95
        
           correct:

     
···

       108
       101
        
         raise Exception(&quot;Wrong OS&quot;)

     

       109
       102
        
       </programlisting>

     

       110
       103
        
         <para>

     

       111
       111
       -
           The first line is actually unnecessary; machines are implicitly

     

       104
       104
       +
           The first line is technically unnecessary; machines are implicitly

     

       112
       105
        
           started when you first execute an action on them (such as

     

       113
       106
        
           <literal>wait_for_unit</literal> or <literal>succeed</literal>). If

     

       114
       107
        
           you have multiple machines, you can speed up the test by starting

     
···

       554
       547
        
           <programlisting language="bash">

     

       555
       548
        
       import ./make-test-python.nix {

     

       556
       549
        
         skipLint = true;

     

       557
       557
       -
         machine =

     

       550
       550
       +
         nodes.machine =

     

       558
       551
        
           { config, pkgs, ... }:

     

       559
       552
        
           { configuration…

     

       560
       553
        
           };

nixos/lib/testing-python.nix

···

       206
       206
        
                   )];

     

       207
       207
        
                 };

     

       208
       208
        
               in

     

       209
       209
       +
                 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'."

     

       209
       210
        
                 build-vms.buildVirtualNetwork (

     

       210
       211
        
                     nodes // lib.optionalAttrs (machine != null) { inherit machine; }

     

       211
       212
        
                 );