nixos/test: Pythonify documentation
This commit is contained in:
parent
ac97edf013
commit
7d19c5aaa7
|
@ -14,14 +14,14 @@
|
|||
starting VDE switch for network 1
|
||||
<prompt>></prompt>
|
||||
</screen>
|
||||
You can then take any Perl statement, e.g.
|
||||
You can then take any Python statement, e.g.
|
||||
<screen>
|
||||
<prompt>></prompt> startAll
|
||||
<prompt>></prompt> testScript
|
||||
<prompt>></prompt> $machine->succeed("touch /tmp/foo")
|
||||
<prompt>></prompt> print($machine->succeed("pwd")) # Show stdout of command
|
||||
<prompt>></prompt> start_all()
|
||||
<prompt>></prompt> test_script()
|
||||
<prompt>></prompt> machine.succeed("touch /tmp/foo")
|
||||
<prompt>></prompt> print(machine.succeed("pwd")) # Show stdout of command
|
||||
</screen>
|
||||
The function <command>testScript</command> executes the entire test script
|
||||
The function <command>test_script</command> executes the entire test script
|
||||
and drops you back into the test driver command line upon its completion.
|
||||
This allows you to inspect the state of the VMs after the test (e.g. to debug
|
||||
the test script).
|
||||
|
|
|
@ -8,7 +8,7 @@
|
|||
<para>
|
||||
A NixOS test is a Nix expression that has the following structure:
|
||||
<programlisting>
|
||||
import ./make-test.nix {
|
||||
import ./make-test-python.nix {
|
||||
|
||||
# Either the configuration of a single machine:
|
||||
machine =
|
||||
|
@ -27,11 +27,11 @@ import ./make-test.nix {
|
|||
|
||||
testScript =
|
||||
''
|
||||
<replaceable>Perl code…</replaceable>
|
||||
<replaceable>Python code…</replaceable>
|
||||
'';
|
||||
}
|
||||
</programlisting>
|
||||
The attribute <literal>testScript</literal> is a bit of Perl code that
|
||||
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
|
||||
|
@ -96,26 +96,27 @@ xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualis
|
|||
</para>
|
||||
|
||||
<para>
|
||||
The test script is a sequence of Perl statements that perform various
|
||||
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
|
||||
<literal>$<replaceable>name</replaceable></literal>, where
|
||||
<replaceable>name</replaceable> is the identifier of the machine (which is
|
||||
just <literal>machine</literal> if you didn’t specify multiple machines
|
||||
using the <literal>nodes</literal> attribute). For instance, the following
|
||||
starts the machine, waits until it has finished booting, then executes a
|
||||
command and checks that the output is more-or-less correct:
|
||||
<literal><replaceable>name</replaceable></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 example starts the machine, waits until it has finished booting,
|
||||
then executes a command and checks that the output is more-or-less correct:
|
||||
<programlisting>
|
||||
$machine->start;
|
||||
$machine->waitForUnit("default.target");
|
||||
$machine->succeed("uname") =~ /Linux/ or die;
|
||||
machine.start()
|
||||
machine.wait_for_unit("default.target")
|
||||
if not "Linux" in machine.succeed("uname"):
|
||||
raise Exception("Wrong OS")
|
||||
</programlisting>
|
||||
The first line is actually unnecessary; machines are implicitly started when
|
||||
you first execute an action on them (such as <literal>waitForUnit</literal>
|
||||
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 them in parallel:
|
||||
<programlisting>
|
||||
startAll;
|
||||
start_all()
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
|
@ -187,7 +188,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>getScreenText</methodname>
|
||||
<methodname>get_screen_text</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -204,7 +205,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>sendMonitorCommand</methodname>
|
||||
<methodname>send_monitor_command</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -215,23 +216,23 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>sendKeys</methodname>
|
||||
<methodname>send_keys</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Simulate pressing keys on the virtual keyboard, e.g.,
|
||||
<literal>sendKeys("ctrl-alt-delete")</literal>.
|
||||
<literal>send_keys("ctrl-alt-delete")</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>sendChars</methodname>
|
||||
<methodname>send_chars</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Simulate typing a sequence of characters on the virtual keyboard, e.g.,
|
||||
<literal>sendKeys("foobar\n")</literal> will type the string
|
||||
<literal>send_keys("foobar\n")</literal> will type the string
|
||||
<literal>foobar</literal> followed by the Enter key.
|
||||
</para>
|
||||
</listitem>
|
||||
|
@ -272,7 +273,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitUntilSucceeds</methodname>
|
||||
<methodname>wait_until_succeeds</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -282,7 +283,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitUntilFails</methodname>
|
||||
<methodname>wait_until_fails</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -292,7 +293,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForUnit</methodname>
|
||||
<methodname>wait_for_unit</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -302,7 +303,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForFile</methodname>
|
||||
<methodname>wait_for_file</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -312,7 +313,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForOpenPort</methodname>
|
||||
<methodname>wait_for_open_port</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -323,7 +324,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForClosedPort</methodname>
|
||||
<methodname>wait_for_closed_port</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -333,7 +334,7 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForX</methodname>
|
||||
<methodname>wait_for_x</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
|
@ -343,13 +344,13 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForText</methodname>
|
||||
<methodname>wait_for_text</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Wait until the supplied regular expressions matches the textual contents
|
||||
of the screen by using optical character recognition (see
|
||||
<methodname>getScreenText</methodname>).
|
||||
<methodname>get_screen_text</methodname>).
|
||||
</para>
|
||||
<note>
|
||||
<para>
|
||||
|
@ -361,23 +362,23 @@ startAll;
|
|||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>waitForWindow</methodname>
|
||||
<methodname>wait_for_window</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Wait until an X11 window has appeared whose name matches the given
|
||||
regular expression, e.g., <literal>waitForWindow(qr/Terminal/)</literal>.
|
||||
regular expression, e.g., <literal>wait_for_window("Terminal")</literal>.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term>
|
||||
<methodname>copyFileFromHost</methodname>
|
||||
<methodname>copy_file_from_host</methodname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Copies a file from host to machine, e.g.,
|
||||
<literal>copyFileFromHost("myfile", "/etc/my/important/file")</literal>.
|
||||
<literal>copy_file_from_host("myfile", "/etc/my/important/file")</literal>.
|
||||
</para>
|
||||
<para>
|
||||
The first argument is the file on the host. The file needs to be
|
||||
|
@ -397,8 +398,8 @@ startAll;
|
|||
</para>
|
||||
<para>
|
||||
<programlisting>
|
||||
$machine->systemctl("list-jobs --no-pager"); // runs `systemctl list-jobs --no-pager`
|
||||
$machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager`
|
||||
machine.systemctl("list-jobs --no-pager") # runs `systemctl list-jobs --no-pager`
|
||||
machine.systemctl("list-jobs --no-pager", "any-user") # spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager`
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
|
@ -408,14 +409,14 @@ $machine->systemctl("list-jobs --no-pager", "any-user"); // spawns a shell for `
|
|||
|
||||
<para>
|
||||
To test user units declared by <literal>systemd.user.services</literal> the
|
||||
optional <literal>$user</literal> argument can be used:
|
||||
optional <literal>user</literal> argument can be used:
|
||||
<programlisting>
|
||||
$machine->start;
|
||||
$machine->waitForX;
|
||||
$machine->waitForUnit("xautolock.service", "x-session-user");
|
||||
machine.start()
|
||||
machine.wait_for_x()
|
||||
machine.wait_for_unit("xautolock.service", "x-session-user")
|
||||
</programlisting>
|
||||
This applies to <literal>systemctl</literal>, <literal>getUnitInfo</literal>,
|
||||
<literal>waitForUnit</literal>, <literal>startJob</literal> and
|
||||
<literal>stopJob</literal>.
|
||||
This applies to <literal>systemctl</literal>, <literal>get_unit_info</literal>,
|
||||
<literal>wait_for_unit</literal>, <literal>start_job</literal> and
|
||||
<literal>stop_job</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
|
Loading…
Reference in a new issue