diff options
Diffstat (limited to 'nixos/doc/manual/development')
| -rw-r--r-- | nixos/doc/manual/development/running-nixos-tests-interactively.section.md | 33 |
1 files changed, 33 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md index 1130672cb3766..54002941d6349 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -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 |