chore(test/makeTestClan): document all options, remove magic specialArgs

lib/default.nix

@@ -25,7 +25,7 @@ lib.fix (clanLib: {
   buildClanModule = clanLib.callLib ./build-clan { };
   inventory = clanLib.callLib ./inventory { };
   modules = clanLib.callLib ./inventory/frontmatter { };
-  test = clanLib.callLib ./tests { };
+  test = clanLib.callLib ./test { };
 
   # Plain imports.
   values = import ./introspection { inherit lib; };

lib/test/default.nix

@@ -7,6 +7,7 @@ let
 in
 {
   minifyModule = ./minify.nix;
+  sopsModule = ./sops.nix;
   # A function that returns an extension to runTest
   makeTestClan =
     {
@@ -54,38 +55,64 @@ in
           };
         };
         config = {
+          # Inherit all nodes from the clan
+          # i.e. nodes.jon <- clan.machines.jon
+          # clanInternals.nixosModules contains nixosModules per node
           nodes = clanFlakeResult.clanInternals.nixosModules;
+
           hostPkgs = pkgs;
-          # speed-up evaluation
+
+          # !WARNING: Write a detailed comment if adding new options here
+          # We should be very careful about adding new options here because it affects all tests
+          # Keep in mind:
+          # - tests should be close to the real world as possible
+          # - ensure stability: in clan-core and downstream
+          # - ensure that the tests are fast and reliable
           defaults = (
             { config, ... }:
             {
               imports = [
+                # Speed up evaluation
                 clanLib.test.minifyModule
-              ];
-              documentation.enable = lib.mkDefault false;
-              nix.settings.min-free = 0;
-              system.stateVersion = config.system.nixos.release;
-              boot.initrd.systemd.enable = false;
 
-              # setup for sops
-              sops.age.keyFile = "/run/age-key.txt";
-              system.activationScripts =
-                {
-                  setupSecrets.deps = [ "age-key" ];
-                  age-key.text = ''
-                    echo AGE-SECRET-KEY-1PL0M9CWRCG3PZ9DXRTTLMCVD57U6JDFE8K7DNVQ35F4JENZ6G3MQ0RQLRV > /run/age-key.txt
-                  '';
-                }
-                // lib.optionalAttrs (lib.filterAttrs (_: v: v.neededForUsers) config.sops.secrets != { }) {
-                  setupSecretsForUsers.deps = [ "age-key" ];
-                };
+                # Setup for sops during tests
+                # configures a static age-key to skip the age-key generation
+                clanLib.test.sopsModule
+              ];
+
+              # Disable documentation
+              # This is nice to speed up the evaluation
+              # And also suppresses any warnings or errors about the documentation
+              documentation.enable = lib.mkDefault false;
+
+              # Disable garbage collection during the test
+              # https://nix.dev/manual/nix/2.28/command-ref/conf-file.html?highlight=min-free#available-settings
+              nix.settings.min-free = 0;
+
+              # This is typically set once via vars generate for a machine
+              # Since we have ephemeral machines, we set it here for the test
+              system.stateVersion = config.system.nixos.release;
+
+              # Currently this is the default in NixOS, but we set it explicitly to avoid surprises
+              # Disable the initrd systemd service which has the following effect
+              #
+              # With the below on 'false' initrd runs a 'minimal shell script', called the stage-1 init.
+              # Benefits:
+              #     Simple and fast.
+              #     Easier to debug for very minimal or custom setups.
+              # Drawbacks:
+              #     Limited flexibility.
+              #     Harder to handle advanced setups (like TPM, LUKS, or LVM-on-LUKS) but not needed since we are in a test
+              #     No systemd journal logs from initrd.
+              boot.initrd.systemd.enable = false;
             }
           );
 
-          # to accept external dependencies such as disko
-          _module.args = { inherit self; };
-          node.specialArgs.self = self;
+          # TODO: figure out if we really need this
+          # I am proposing for less magic in the test-framework
+          # People may add this in their own tests
+          # _module.args = { inherit self; };
+          # node.specialArgs.self = self;
         };
       }
     )).config.result;

lib/test/sops.nix

@@ -0,0 +1,16 @@
+# nixosModule
+{ config, lib, ... }:
+{
+  # configures a static age-key to skip the age-key generation
+  sops.age.keyFile = "/run/age-key.txt";
+  system.activationScripts =
+    {
+      setupSecrets.deps = [ "age-key" ];
+      age-key.text = ''
+        echo AGE-SECRET-KEY-1PL0M9CWRCG3PZ9DXRTTLMCVD57U6JDFE8K7DNVQ35F4JENZ6G3MQ0RQLRV > /run/age-key.txt
+      '';
+    }
+    // lib.optionalAttrs (lib.filterAttrs (_: v: v.neededForUsers) config.sops.secrets != { }) {
+      setupSecretsForUsers.deps = [ "age-key" ];
+    };
+}