dotfiles/skills/test-nixos-service/SKILL.md

name, description

name	description
test-nixos-service	Add or extend a non-activating NixOS VM or container test for service startup, sockets, timers, permissions, firewall behavior, reboot state, and inter-service dependencies. Use when evaluation and a system build cannot prove the requested runtime behavior.

Test NixOS Runtime Behavior

Prefer pkgs.testers.runNixOSTest for reusable NixOS behavior that can be proved without the user's physical machine. Do not activate the host configuration and do not substitute a live nh os switch for a deterministic test.

Define the observable contract

List the runtime facts that must hold, such as:

• a systemd unit reaches active;
• a socket or port is listening;
• a timer triggers its service;
• a user can or cannot read a file;
• a group membership grants access;
• a firewall permits one path and blocks another;
• state survives a reboot;
• one service waits for another dependency.

Exclude behavior that requires physical GPU, fingerprint, audio, display, Secure Boot, TPM, private credentials, or an external provider unless the test can model it explicitly.

Implement the smallest useful machine

Create a test under tests/ and expose it through checks.<system>. Import the owning module or Registry selection instead of copying its implementation into the test. Use only the packages, users, files, and network peers required by the contract.

Typical shape:

pkgs.testers.runNixOSTest {
  name = "service-name";

  nodes.machine = {
    # Enable the owning unit or import the module under test.
  };

  testScript = ''
    machine.start()
    machine.wait_for_unit("service-name.service")
    machine.succeed("systemctl is-active service-name.service")
  '';
}

Use wait_for_unit, wait_for_open_port, succeed, fail, and explicit reboots to express outcomes. Avoid arbitrary sleeps when a readiness condition exists.

Validate and report

Run the targeted test through its flake check, then run the repository validation app for the task paths. Report the test attribute and assertions that passed. State clearly which hardware or external behavior remains outside the VM/container model.