nixos/test-driver: deprecate shell_interact() (#535097)

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

@@ -43,6 +43,11 @@ test script).
 
 ## Shell access to VMs in interactive mode {#sec-nixos-test-shell-access}
 
+::: {.warning}
+Using `shell_interact()` is deprecated. Use the
+[interactive SSH backdoor](#sec-nixos-test-ssh-access) instead.
+:::
+
 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()`.

nixos/doc/manual/release-notes/rl-2611.section.md

@@ -69,6 +69,8 @@
 
 - `komodo` has been updated to the v2 release line (2.x). See the [upstream v1 → v2 upgrade guide](https://github.com/moghtech/komodo/releases/tag/v2.0.0).
 
+- The `shell_interact()` function on interactive runs of NixOS VM tests has been deprecated. Use the SSH backdoor instead.
+
 - `security.run0.enableSudoAlias` now uses the `run0-sudo-shim` instead of a shell-script to improve compatibility.
 
 - With `system.etc.overlay.mutable = false`, NixOS now ships an empty `/etc/machine-id` in the image. Previously the file was absent and systemd logged `System cannot boot: Missing /etc/machine-id and /etc/ is read-only` while `ConditionFirstBoot` fired on every boot. With this change, systemd now overlays a transient ID from `/run/machine-id` for the session, and `systemd-machine-id-commit.service` has `ConditionFirstBoot` so it writes the machine-id through to a persistent backing file when one is bind-mounted over `/etc/machine-id`. To persist the machine-id across reboots, bind-mount a writable file containing `uninitialized` over `/etc/machine-id` from the initrd, or set `systemd.machine_id=` on the kernel command line (use `systemd.machine_id=firmware` to derive a stable ID on hardware that supports it).

nixos/lib/test-driver/src/test_driver/__init__.py

@@ -6,6 +6,7 @@ import warnings
 from pathlib import Path
 
 import ptpython.ipython
+import ptpython.repl
 from colorama import Fore, Style
 
 from test_driver.debug import Debug, DebugAbstract, DebugNop
@@ -174,6 +175,7 @@ def main() -> None:
         if args.interactive:
             history_dir = os.getcwd()
             history_path = os.path.join(history_dir, ".nixos-test-history")
+            ptpython.repl.enable_deprecation_warnings()
             ptpython.ipython.embed(
                 user_ns=driver.test_symbols(),
                 history_filename=history_path,

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

@@ -908,6 +908,7 @@ class QemuMachine(BaseMachine):
 
         return (rc, output.decode(errors="replace"))
 
+    @warnings.deprecated("Use the SSH backdoor instead")
     def shell_interact(self, address: str | None = None) -> None:
         """
         Allows you to directly interact with the guest shell. This should