testers.nixosTest: Move from top-level and improve docs

5 files changed, 76 insertions, 54 deletions

diff --git a/doc/builders/testers.chapter.md b/doc/builders/testers.chapter.md
index 2c30c8bd240e..06434c0467e6 100644
--- a/doc/builders/testers.chapter.md
+++ b/doc/builders/testers.chapter.md
@@ -80,3 +80,49 @@ tests.fetchgit = invalidateFetcherByDrvHash fetchgit {
   sha256 = "sha256-7DszvbCNTjpzGRmpIVAWXk20P0/XTrWZ79KSOGLrUWY=";
 };
 ```
+
+## `nixosTest` {#tester-nixosTest}
+
+Run a NixOS VM network test using this evaluation of Nixpkgs.
+
+NOTE: This function is primarily for external use. NixOS itself uses `make-test-python.nix` directly.
+
+It is mostly equivalent to the function `import ./make-test-python.nix` from the
+[NixOS manual](https://nixos.org/nixos/manual/index.html#sec-nixos-tests),
+except that the current application of Nixpkgs (`pkgs`) will be used, instead of
+letting NixOS invoke Nixpkgs anew.
+
+If a test machine needs to set NixOS options under `nixpkgs`, it must set only the
+`nixpkgs.pkgs` option.
+
+### Parameter
+
+A [NixOS VM test network](https://nixos.org/nixos/manual/index.html#sec-nixos-tests), or path to it. Example:
+
+```nix
+{
+  name = "my-test";
+  nodes = {
+    machine1 = { lib, pkgs, nodes, ... }: {
+      environment.systemPackages = [ pkgs.hello ];
+      services.foo.enable = true;
+    };
+    # machine2 = ...;
+  };
+  testScript = ''
+    start_all()
+    machine1.wait_for_unit("foo.service")
+    machine1.succeed("hello | foo-send")
+  '';
+}
+```
+
+### Result
+
+A derivation that runs the VM test.
+
+Notable attributes:
+
+ * `nodes`: the evaluated NixOS configurations. Useful for debugging and exploring the configuration.
+
+ * `driverInteractive`: a script that launches an interactive Python session in the context of the `testScript`.
diff --git a/pkgs/build-support/testers/default.nix b/pkgs/build-support/testers/default.nix
index d983e43c0bf1..3ab97760e725 100644
--- a/pkgs/build-support/testers/default.nix
+++ b/pkgs/build-support/testers/default.nix
@@ -1,4 +1,4 @@
-{ pkgs, lib, callPackage, runCommand }:
+{ pkgs, lib, callPackage, runCommand, stdenv }:
 # Documentation is in doc/builders/testers.chapter.md
 {
   testEqualDerivation = callPackage ./test-equal-derivation.nix { };
@@ -33,4 +33,31 @@
         else salted;
     in checked;
 
+  # See doc/builders/testers.chapter.md or
+  # https://nixos.org/manual/nixpkgs/unstable/#tester-invalidateFetcherByDrvHash
+  nixosTest =
+    let
+      /* The nixos/lib/testing-python.nix module, preapplied with arguments that
+       * make sense for this evaluation of Nixpkgs.
+       */
+      nixosTesting =
+        (import ../../../nixos/lib/testing-python.nix {
+          inherit (stdenv.hostPlatform) system;
+          inherit pkgs;
+          extraConfigurations = [(
+            { lib, ... }: {
+              config.nixpkgs.pkgs = lib.mkDefault pkgs;
+            }
+          )];
+        });
+    in
+      test:
+        let
+          loadedTest = if builtins.typeOf test == "path"
+            then import test
+            else test;
+          calledTest = lib.toFunction loadedTest pkgs;
+        in
+          nixosTesting.makeTest calledTest;
+
 }
diff --git a/pkgs/test/nixos-functions/default.nix b/pkgs/test/nixos-functions/default.nix
index f2914455246c..0c4869871e56 100644
--- a/pkgs/test/nixos-functions/default.nix
+++ b/pkgs/test/nixos-functions/default.nix
@@ -26,7 +26,7 @@ in lib.optionalAttrs stdenv.hostPlatform.isLinux (
       fileSystems."/".device = "/dev/null";
     }).toplevel;
 
-    nixosTest-test = pkgs.nixosTest ({ lib, pkgs, figlet, ... }: {
+    nixosTest-test = pkgs.testers.nixosTest ({ lib, pkgs, figlet, ... }: {
       name = "nixosTest-test";
       nodes.machine = { pkgs, ... }: {
         system.nixos = dummyVersioning;
diff --git a/pkgs/top-level/aliases.nix b/pkgs/top-level/aliases.nix
index 4c3c44ddc3f3..694d2c734873 100644
--- a/pkgs/top-level/aliases.nix
+++ b/pkgs/top-level/aliases.nix
@@ -872,6 +872,7 @@ mapAliases ({
   nix_2_5 = nixVersions.nix_2_5;
   nix_2_6 = nixVersions.nix_2_6;
   nixopsUnstable = nixops_unstable; # Added 2022-03-03
+  nixosTest = testers.nixosTest; # Added 2022-05-05
   nmap-unfree = nmap; # Added 2021-04-06
   nmap-graphical = throw "nmap graphical support has been removed due to its python2 dependency"; # Added 2022-04-26
   nmap_graphical = throw "nmap graphical support has been removed due to its python2 dependency"; # Modified 2022-04-26
diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix
index 45bf4c6bf0b3..822d01ad79b5 100644
--- a/pkgs/top-level/all-packages.nix
+++ b/pkgs/top-level/all-packages.nix
@@ -34123,58 +34123,6 @@ with pkgs;
       };
   };
 
-  /*
-   * Run a NixOS VM network test using this evaluation of Nixpkgs.
-   *
-   * It is mostly equivalent to `import ./make-test-python.nix` from the
-   * NixOS manual[1], except that your `pkgs` will be used instead of
-   * letting NixOS invoke Nixpkgs again. If a test machine needs to
-   * set NixOS options under `nixpkgs`, it must set only the
-   * `nixpkgs.pkgs` option. For the details, see the Nixpkgs
-   * `pkgs.nixos` documentation.
-   *
-   * Parameter:
-   *   A NixOS VM test network, or path to it. Example:
-   *
-   *      { lib, ... }:
-   *      { name = "my-test";
-   *        nodes = {
-   *          machine-1 = someNixOSConfiguration;
-   *          machine-2 = ...;
-   *        }
-   *      }
-   *
-   * Result:
-   *   A derivation that runs the VM test.
-   *
-   * [1]: For writing NixOS tests, see
-   *      https://nixos.org/nixos/manual/index.html#sec-nixos-tests
-   */
-  nixosTest =
-    let
-      /* The nixos/lib/testing-python.nix module, preapplied with arguments that
-       * make sense for this evaluation of Nixpkgs.
-       */
-      nixosTesting =
-        (import ../../nixos/lib/testing-python.nix {
-          inherit (stdenv.hostPlatform) system;
-          inherit pkgs;
-          extraConfigurations = [(
-            { lib, ... }: {
-              config.nixpkgs.pkgs = lib.mkDefault pkgs;
-            }
-          )];
-        });
-    in
-      test:
-        let
-          loadedTest = if builtins.typeOf test == "path"
-            then import test
-            else test;
-          calledTest = lib.toFunction loadedTest pkgs;
-        in
-          nixosTesting.makeTest calledTest;
-
   nixosOptionsDoc = attrs:
     (import ../../nixos/lib/make-options-doc)
     ({ inherit pkgs lib; } // attrs);