Unverified Commit e80e3878 authored by Jörg Thalheim's avatar Jörg Thalheim Committed by GitHub
Browse files

Merge pull request #178533 from Mic92/nixos-tests-shell

nixos/tests: extend shell_interact to accept alternative socat addresses
parents 68d1aeab 29db54c3
Loading
Loading
Loading
Loading
+33 −0
Original line number Diff line number Diff line
@@ -24,6 +24,39 @@ 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).

## Shell access in interactive mode {#sec-nixos-test-shell-access}

The function `<yourmachine>.shell_interact()` grants access to a shell running
inside a virtual machine. To use it, replace `<yourmachine>` with the name of a
virtual machine defined in the test, for example: `machine.shell_interact()`.
Keep in mind that this shell may not display everything correctly as it is
running within an interactive Python REPL, and logging output from the virtual
machine may overwrite input and output from the guest shell:

```py
>>> machine.shell_interact()
machine: Terminal is ready (there is no initial prompt):
$ hostname
machine
```

As an alternative, you can proxy the guest shell to a local TCP server by first
starting a TCP server in a terminal using the command:

```ShellSession
$ socat 'READLINE,PROMPT=$ ' tcp-listen:4444,reuseaddr`
```

In the terminal where the test driver is running, connect to this server by
using:

```py
>>> machine.shell_interact("tcp:127.0.0.1:4444")
```

Once the connection is established, you can enter commands in the socat terminal
where socat is running.

## Reuse VM state {#sec-nixos-test-reuse-vm-state}

You can re-use the VM states coming from a previous run by setting the
+40 −0
Original line number Diff line number Diff line
@@ -25,6 +25,46 @@ $ ./result/bin/nixos-test-driver
    completion. This allows you to inspect the state of the VMs after
    the test (e.g. to debug the test script).
  </para>
  <section xml:id="sec-nixos-test-shell-access">
    <title>Shell access in interactive mode</title>
    <para>
      The function
      <literal>&lt;yourmachine&gt;.shell_interact()</literal> grants
      access to a shell running inside a virtual machine. To use it,
      replace <literal>&lt;yourmachine&gt;</literal> with the name of a
      virtual machine defined in the test, for example:
      <literal>machine.shell_interact()</literal>. Keep in mind that
      this shell may not display everything correctly as it is running
      within an interactive Python REPL, and logging output from the
      virtual machine may overwrite input and output from the guest
      shell:
    </para>
    <programlisting language="python">
&gt;&gt;&gt; machine.shell_interact()
machine: Terminal is ready (there is no initial prompt):
$ hostname
machine
</programlisting>
    <para>
      As an alternative, you can proxy the guest shell to a local TCP
      server by first starting a TCP server in a terminal using the
      command:
    </para>
    <programlisting>
$ socat 'READLINE,PROMPT=$ ' tcp-listen:4444,reuseaddr`
</programlisting>
    <para>
      In the terminal where the test driver is running, connect to this
      server by using:
    </para>
    <programlisting language="python">
&gt;&gt;&gt; machine.shell_interact(&quot;tcp:127.0.0.1:4444&quot;)
</programlisting>
    <para>
      Once the connection is established, you can enter commands in the
      socat terminal where socat is running.
    </para>
  </section>
  <section xml:id="sec-nixos-test-reuse-vm-state">
    <title>Reuse VM state</title>
    <para>
+17 −8
Original line number Diff line number Diff line
@@ -549,18 +549,27 @@ class Machine:

        return (rc, output.decode())

    def shell_interact(self) -> None:
        """Allows you to interact with the guest shell
    def shell_interact(self, address: Optional[str] = None) -> None:
        """Allows you to interact with the guest shell for debugging purposes.

        Should only be used during test development, not in the production test."""
        @address string passed to socat that will be connected to the guest shell.
        Check the `Running Tests interactivly` chapter of NixOS manual for an example.
        """
        self.connect()

        if address is None:
            address = "READLINE,prompt=$ "
            self.log("Terminal is ready (there is no initial prompt):")

        assert self.shell
        try:
            subprocess.run(
            ["socat", "READLINE,prompt=$ ", f"FD:{self.shell.fileno()}"],
                ["socat", address, f"FD:{self.shell.fileno()}"],
                pass_fds=[self.shell.fileno()],
            )
            # allow users to cancel this command without breaking the test
        except KeyboardInterrupt:
            pass

    def console_interact(self) -> None:
        """Allows you to interact with QEMU's stdin