Core API

lib.fixtures

inputs.tests.lib.fixtures { inherit pkgs; }

Resolves the complete built-in fixture set for advanced integrations. Most projects should use lib.mkTests or the flake-parts module instead.

lib.mkFixture

inputs.tests.lib.mkFixture ({ terminal, filesystem, ... }: {
  open = file: [
    (filesystem.writeFile file "")
    (terminal.open file)
  ];
})

Registers a fixture factory. The factory receives the recursive fixture set and returns the value exposed to test callbacks.

lib.mkLocator

inputs.tests.lib.mkLocator {
  type = "appStatus";
  inherit name;
}

Creates a typed locator for custom fixtures and matchers. The type identifies compatible matchers; all other attributes hold locator-specific data.

lib.mkMatcher

inputs.tests.lib.mkMatcher {
  accepts = [ "appStatus" ];
  run = { expect, ... }: target:
      (expect (inputs.tests.lib.mkLocator {
        type = "terminalText";
        text = target.status;
      })).toBeVisible;
}

Creates a fixture-aware matcher factory. accepts lists valid target types; omit it for a matcher that accepts any tagged action or locator. Invalid targets fail during Nix evaluation before a runner is built. Compose matchers from runtime-backed locators and matchers unless a runner explicitly supports the custom action type.

lib.mkTests

inputs.tests.lib.mkTests {
  inherit pkgs test;
  fixtures = { };
  matchers = { };
}

Converts an attribute set of fixture callbacks into derivations suitable for checks.${system}. Attribute names become check names. fixtures and matchers use the same plugin format as the flake-parts module and default to empty attribute sets. Each test must be a callback that receives only the fixtures it requests. Reserve test.configure for suite-wide defaults.

lib.test.step

Plain-flake callers use lib.test.step name actions to create named steps. Flake-parts users receive the same function as test.step.

test

test."shows greeting" = { terminal }: [
  (terminal.open pkgs.hello)
  (expect (terminal.getByText "Hello")).toBeVisible
];

test."shared machine" = { machine }: {
  test.step."service starts" = [
    (expect (machine.service "example.service")).toBeActive
  ];
};

A mergeable attribute set of integration-test fixture callbacks. Attribute names become check names. A test callback may return an action list or a test.step.<name> attribute set of named subtests. test and expect are module arguments; runtime fixtures are callback arguments. test.configure is reserved for suite-wide configuration.

test.configure

test.configure = {
  timeout = 30;
  terminal = {
    columns = 80;
    rows = 24;
  };
};

Configures every test declared in the current perSystem scope. timeout controls standalone terminal assertion retries and defaults to 15 seconds. Standalone terminal dimensions default to 140 columns by 42 rows.

test.step

Groups actions into a named step inside a test. The step appears as a nested subtest in the test log, making longer scenarios easier to read and debug.

A test callback can alternatively return a test.step.<name> = actions attribute set for declarative top-level steps. This function remains available inside action lists for nested steps.

Usage

test.step "service becomes usable" [
  (expect (machine.service "example.service")).toBeActive
  ((expect (machine.http.get "http://localhost/health")).toHaveStatus 200)
]

Arguments

• name: Name shown in the test log.
• actions: Ordered list of actions in the step.

Returns an action that can be placed in a test’s action list. Steps may contain other steps.

testing.fixtures

testing.fixtures.app = inputs.tests.lib.mkFixture ({ terminal, filesystem, ... }: {
  open = file: [
    (filesystem.writeFile file "")
    (terminal.open file)
  ];
});

A mergeable attribute set of fixtures created with lib.mkFixture. Each factory receives the complete fixture set and returns the value injected under its attribute name. Built-in fixture names cannot be replaced.

testing.matchers

testing.matchers.toBeReady = inputs.tests.lib.mkMatcher {
  accepts = [ "appStatus" ];
  run = { expect, ... }: target:
    (expect (inputs.tests.lib.mkLocator {
      type = "terminalText";
      text = target.status;
    })).toBeVisible;
};

A mergeable attribute set of custom matcher factories. Each factory receives the complete fixture set and returns a matcher function exposed on the value returned by expect target. Use lib.mkMatcher to validate targets. Built-in matcher names cannot be replaced.