nixos.runTest: Add extendNixOS

nixos/doc/manual/development/writing-nixos-tests.section.md

@@ -289,9 +289,42 @@ The NixOS test framework returns tests with multiple overriding methods.
         Just as with `overrideAttrs`, an abbreviated form can be used, e.g. `prevAttrs: { /* … */ }` or even `{ /* … */ }`.
         See [`lib.extends`](https://nixos.org/manual/nixpkgs/stable/#function-library-lib.fixedPoints.extends).
 
+`extendNixOS { module = ` *module* `; specialArgs = ` *specialArgs* `; }`
+:   Evaluates the test with additional NixOS modules and/or arguments.
+
+    `module`
+    :   A NixOS module to add to all the nodes in the test. Sets test option [`extraBaseModules`](#test-opt-extraBaseModules).
+
+    `specialArgs`
+    :   An attribute set of arguments to pass to all NixOS modules. These override the existing arguments, as well as any `_module.args.<name>` that the modules may define. Sets test option [`node.specialArgs`](#test-opt-node.specialArgs).
+
+    This is a convenience function for `extend` that overrides the aforementioned test options.
+
+    :::{.example #ex-nixos-test-extendNixOS}
+
+    # Using extendNixOS in `passthru.tests` to make `(openssh.tests.overrideAttrs f).tests.nixos` coherent
+
+    ```nix
+    mkDerivation (finalAttrs: {
+      # …
+      passthru = {
+        tests = {
+          nixos = nixosTests.openssh.extendNixOS {
+            module = {
+              services.openssh.package = finalAttrs.finalPackage;
+            };
+          };
+        };
+      };
+    })
+    ```
+    :::
+
 `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.
 

nixos/doc/manual/redirects.json

@@ -5,6 +5,9 @@
   "test-opt-rawTestDerivationArg": [
     "index.html#test-opt-rawTestDerivationArg"
   ],
+  "ex-nixos-test-extendNixOS": [
+    "index.html#ex-nixos-test-extendNixOS"
+  ],
   "book-nixos-manual": [
     "index.html#book-nixos-manual"
   ],

nixos/lib/testing/nodes.nix

@@ -3,6 +3,7 @@ testModuleArgs@{
   lib,
   hostPkgs,
   nodes,
+  options,
   ...
 }:
 
@@ -73,6 +74,9 @@ let
     ];
   };
 
+  # TODO (lib): Dedup with run.nix, add to lib/options.nix
+  mkOneUp = opt: f: lib.mkOverride (opt.highestPrio - 1) (f opt.value);
+
 in
 
 {
@@ -233,5 +237,23 @@ in
       ))
     ];
 
+    # Docs: nixos/doc/manual/development/writing-nixos-tests.section.md
+    /**
+      See https://nixos.org/manual/nixos/unstable#sec-override-nixos-test
+    */
+    passthru.extendNixOS =
+      {
+        module,
+        specialArgs ? { },
+      }:
+      config.passthru.extend {
+        modules = [
+          {
+            extraBaseModules = module;
+            node.specialArgs = mkOneUp options.node.specialArgs (_: specialArgs);
+          }
+        ];
+      };
+
   };
 }

pkgs/build-support/testers/test/default.nix

@@ -30,6 +30,24 @@ let
         __structuredAttrs = enable;
       });
     });
+  runNixOSTest-example = pkgs-with-overlay.testers.runNixOSTest (
+    { lib, ... }:
+    {
+      name = "runNixOSTest-test";
+      nodes.machine =
+        { pkgs, ... }:
+        {
+          system.nixos = dummyVersioning;
+          environment.systemPackages = [
+            pkgs.proof-of-overlay-hello
+            pkgs.figlet
+          ];
+        };
+      testScript = ''
+        machine.succeed("hello | figlet >/dev/console")
+      '';
+    }
+  );
 
 in
 lib.recurseIntoAttrs {
@@ -64,24 +82,27 @@ lib.recurseIntoAttrs {
     };
   };
 
-  runNixOSTest-example = pkgs-with-overlay.testers.runNixOSTest (
+  inherit runNixOSTest-example;
-    { lib, ... }:
+
+  runNixOSTest-extendNixOS =
+    let
+      t = runNixOSTest-example.extendNixOS {
+        module =
+          { hi, lib, ... }:
           {
-      name = "runNixOSTest-test";
+            config = {
-      nodes.machine =
+              assertions = [ { assertion = hi; } ];
-        { pkgs, ... }:
-        {
-          system.nixos = dummyVersioning;
-          environment.systemPackages = [
-            pkgs.proof-of-overlay-hello
-            pkgs.figlet
-          ];
             };
-      testScript = ''
+            options = {
-        machine.succeed("hello | figlet >/dev/console")
+              itsProofYay = lib.mkOption { };
-      '';
+            };
-    }
+          };
-  );
+        specialArgs.hi = true;
+      };
+    in
+    assert lib.isDerivation t;
+    assert t.nodes.machine ? itsProofYay;
+    t;
 
   # Check that the wiring of nixosTest is correct.
   # Correct operation of the NixOS test driver should be asserted elsewhere.