NixOS Test Framework: `extend` Function and VM Sandbox Debugging with SSH

}; }; }; }) ``` ::: `extend { modules = ` *modules* `; specialArgs = ` *specialArgs* `; }` : Adds new `nixosTest` modules and/or module arguments to the test, which are evaluated together with the existing modules and [built-in options](#sec-test-options-reference). If you're only looking to extend the _NixOS_ configurations of the test, and not something else about the test, you may use the `extendNixOS` convenience function instead. `modules` : A list of modules to add to the test. These are added to the existing modules and then [evaluated](https://nixos.org/manual/nixpkgs/stable/index.html#module-system-lib-evalModules) together. `specialArgs` : An attribute of arguments to pass to the test. These override the existing arguments, as well as any `_module.args.<name>` that the modules may define. See [`evalModules`/`specialArgs`](https://nixos.org/manual/nixpkgs/stable/#module-system-lib-evalModules-param-specialArgs). ## Test Options Reference {#sec-test-options-reference} The following options can be used when writing tests. ```{=include=} options id-prefix: test-opt- list-id: test-options-list source: @NIXOS_TEST_OPTIONS_JSON@ ``` ## Accessing VMs in the sandbox with SSH {#sec-test-sandbox-breakpoint} ::: {.note} For debugging with SSH access into the machines, it's recommended to try using [the interactive driver](#sec-running-nixos-tests-interactively) with its [SSH backdoor](#sec-nixos-test-ssh-access) first. This feature is mostly intended to debug flaky test failures that aren't reproducible elsewhere. ::: As explained in [](#sec-nixos-test-ssh-access), it's possible to configure an SSH backdoor based on AF_VSOCK. This can be used to SSH into a VM of a running build in a sandbox. This can be done when something in the test fails, e.g. ```nix { nodes.machine = { }; sshBackdoor.enable = true; enableDebugHook = true; testScript = '' start_all() machine.succeed("false") # this will fail ''; } ``` For the AF_VSOCK feature to work, `/dev/vhost-vsock` is needed in the sandbox which can be done with e.g. ``` nix-build -A nixosTests.foo --option sandbox-paths /dev/vhost-vsock ``` This will halt the test execution on a test-failure and print instructions on how to enter the sandbox shell of the VM test. Inside, one can log into e.g. `machine` with ``` ssh -F ./ssh_config vsock/3 ``` As described in [](#sec-nixos-test-ssh-access), the numbers for vsock start at `3` instead of `1`. So the first VM in the network (sorted alphabetically) can be accessed with `vsock/3`. Alternatively, it's possible to explicitly set a breakpoint with `debug.breakpoint()`. This also has the benefit, that one can step through `testScript` with `pdb` like this: ``` $ sudo /nix/store/eeeee-attach <id> bash# telnet 127.0.0.1 4444 pdb$ … ```

This chunk concludes the description of the `extend` function, which allows adding new `nixosTest` modules and/or special arguments to a test's evaluation, overriding existing configurations. It also introduces the "Test Options Reference" section, pointing to a list of available test options. The main part details how to access Virtual Machines (VMs) within the test sandbox using SSH for debugging. This feature is primarily for debugging flaky test failures not reproducible interactively. It involves enabling `sshBackdoor` and `enableDebugHook` in the test configuration, which will halt execution on failure. To facilitate SSH access, `/dev/vhost-vsock` must be available in the sandbox. Users can then SSH into VMs using a provided `ssh_config` and `vsock` addresses (e.g., `vsock/3`). Alternatively, an explicit breakpoint can be set using `debug.breakpoint()`, allowing interaction with `testScript` via `pdb` after attaching to the test.