nixos.runTest: Add extend, overrideTestDerivation

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

@@ -275,6 +275,29 @@ added using the parameter `extraPythonPackages`. For example, you could add
 
 In that case, `numpy` is chosen from the generic `python3Packages`.
 
+## Overriding a test {#sec-override-nixos-test}
+
+The NixOS test framework returns tests with multiple overriding methods.
+
+`overrideTestDerivation` *function*
+:   Like applying `overrideAttrs` on the [test](#test-opt-test) derivation.
+
+    This is a convenience for `extend` with an override on the [`rawTestDerivationArg`](#test-opt-rawTestDerivationArg) option.
+
+    *function*
+    :   An extension function, e.g. `finalAttrs: prevAttrs: { /* … */ }`, the result of which is passed to [`mkDerivation`](https://nixos.org/manual/nixpkgs/stable/#sec-using-stdenv).
+        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).
+
+`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).
+
+    `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.

nixos/doc/manual/redirects.json

@@ -1,4 +1,10 @@
 {
+  "sec-override-nixos-test": [
+    "index.html#sec-override-nixos-test"
+  ],
+  "test-opt-rawTestDerivationArg": [
+    "index.html#test-opt-rawTestDerivationArg"
+  ],
   "book-nixos-manual": [
     "index.html#book-nixos-manual"
   ],

nixos/lib/testing/call-test.nix

@@ -1,6 +1,19 @@
-{ config, lib, ... }:
+{
+  config,
+  extendModules,
+  lib,
+  ...
+}:
 let
   inherit (lib) mkOption types;
+
+  unsafeGetAttrPosStringOr =
+    default: name: value:
+    let
+      p = builtins.unsafeGetAttrPos name value;
+    in
+    if p == null then default else p.file + ":" + toString p.line + ":" + toString p.column;
+
 in
 {
   options = {
@@ -9,4 +22,21 @@ in
       default = config;
     };
   };
+  config = {
+    # Docs: nixos/doc/manual/development/writing-nixos-tests.section.md
+    /**
+      See https://nixos.org/manual/nixos/unstable#sec-override-nixos-test
+    */
+    passthru.extend =
+      args@{
+        modules,
+        specialArgs ? { },
+      }:
+      (extendModules {
+        inherit specialArgs;
+        modules = map (lib.setDefaultModuleLocation (
+          unsafeGetAttrPosStringOr "<test.extend module>" "modules" args
+        )) modules;
+      }).config.test;
+  };
 }

nixos/lib/testing/run.nix

@@ -2,10 +2,31 @@
   config,
   hostPkgs,
   lib,
+  options,
   ...
 }:
 let
   inherit (lib) types mkOption;
+
+  # TODO (lib): Also use lib equivalent in nodes.nix
+  /**
+    Create a module system definition that overrides an existing option from a different module evaluation.
+
+    Type: Option a -> (a -> a) -> Definition a
+  */
+  mkOneUp =
+    /**
+      Option from an existing module evaluation, e.g.
+      - `(lib.evalModules ...).options.x` when invoking `evalModules` again,
+      - or `{ options, ... }:` when invoking `extendModules`.
+    */
+    opt:
+    /**
+      Function from the old value to the new definition, which will be wrapped with `mkOverride`.
+    */
+    f:
+    lib.mkOverride (opt.highestPrio - 1) (f opt.value);
+
 in
 {
   options = {
@@ -30,6 +51,13 @@ in
       internal = true;
     };
 
+    rawTestDerivationArg = mkOption {
+      type = types.functionTo types.raw;
+      description = ''
+        Argument passed to `mkDerivation` to create the `rawTestDerivation`.
+      '';
+    };
+
     test = mkOption {
       type = types.package;
       # TODO: can the interactive driver be configured to access the network?
@@ -43,10 +71,12 @@ in
   };
 
   config = {
-    rawTestDerivation =
+    rawTestDerivation = hostPkgs.stdenv.mkDerivation config.rawTestDerivationArg;
+    rawTestDerivationArg =
+      finalAttrs:
       assert lib.assertMsg (!config.sshBackdoor.enable)
         "The SSH backdoor is currently not supported for non-interactive testing! Please make sure to only set `interactive.sshBackdoor.enable = true;`!";
-      hostPkgs.stdenv.mkDerivation {
+      {
         name = "vm-test-run-${config.name}";
 
         requiredSystemFeatures =
@@ -75,5 +105,19 @@ in
 
     # useful for inspection (debugging / exploration)
     passthru.config = config;
+
+    # Docs: nixos/doc/manual/development/writing-nixos-tests.section.md
+    /**
+      See https://nixos.org/manual/nixos/unstable#sec-override-nixos-test
+    */
+    passthru.overrideTestDerivation =
+      f:
+      config.passthru.extend {
+        modules = [
+          {
+            rawTestDerivationArg = mkOneUp options.rawTestDerivationArg (lib.extends (lib.toExtension f));
+          }
+        ];
+      };
   };
 }