Running Tests

To run tests locally, use the following commands:

# Run the entire test suite
$ nix build '.#tests.all'

# List all available tests
$ nix run '.#tests.show'

# Run a single test
$ nix build '.#tests.<test-name>'

# Run a test interactively (useful for debugging or crafting new tests)
# This starts an interactive Python REPL with test framework symbols exposed
$ nix run '.#tests.<test-name>.driverInteractive'

Run without Flakes

While running tests without Flakes is possible, we do not recommend it as it is not as user-friendly as with Flakes.

If you still want to avoid using Flakes, here is how to do it:

# Run from the root repository directory
$ nix-build ./tests \
  -I nixpkgs=https://github.com/nixos/nixpkgs/archive/nixos-25.05.tar.gz \
  -A '<all|show|test-name>'

The nixpkgs lookup path must be in sync with the one expected by Home Manager (see here for further details).

Additionally, please note that show and interactive tests will need to be executed manually after building:

# List available tests
$ ./result/bin/show-tests

# Run interactive test
$ ./result/bin/nixos-test-driver

Set GitKraken Version

All tests, by default, are run against the latest GitKraken version supported by NixKraken.

If needed, tests can be run against a different version of GitKraken by providing the withVersion argument.

Since Flakes do not allow overriding derivation arguments, only classic Nix commands can be used to benefit from this feature:

$ nix-build ./tests \
  -I nixpkgs=https://github.com/nixos/nixpkgs/archive/nixos-25.05.tar.gz \
  -A '<test-name>' \
  --argstr withVersion <version>

INFO

This method of running tests is currently used to perform automated CI tests against all supported GitKraken versions.

See the e2e-tests.yml workflow for real-world usage.

Test Results

After a test completes and if screenshots were taken as part of it, they will be available in the result directory.

• for single runs: result/<screenshot-name>.png
• for the full suite: result/share/<test-name>/<screenshot-name>.png