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

nixos/doc/manual/development/running-nixos-tests-interactively.section.md

+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

nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml

+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>

nixos/lib/test-driver/test_driver/machine.py

+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