History

Erik Arvstedt 6bc5747951 run-tests: fix `tmpDir` being deleted before it's used In `buildTests`, `nixInstantiate` is called in a subshell. When `tmpDir` is unset before the call, the tmpdir is created in the subshell and gets deleted before subshell exit (via `trap`). But subsequent code accesses the tmpdir, which has now been deleted, leading to an error. This bug has been undetected for a long time because bash 5.2 has a bug [1] where `trap` is not always executed, causing the tmpdir to never be deleted. Bash 5.3 (introduced in NixOS 25.05) now works correctly and exposes the bug. Fix it by creating the tmpdir before the subshell call. [1] https://mail.gnu.org/archive/html/help-bash/2024-07/msg00007.html		2025-08-18 13:28:00 +02:00
..
ci	ci: group job output, print eval results	2025-08-11 22:15:48 +02:00
lib	flake: update extra-container	2024-12-14 10:52:27 +01:00
nixos-search	update nixpkgs	2025-08-10 19:06:23 +02:00
clightning-replication.nix	modules: update to NixOS 24.11	2024-12-14 10:52:26 +01:00
README.md	test/README: mention Flakes requirement	2025-01-22 20:48:12 +01:00
run-tests.sh	run-tests: fix `tmpDir` being deleted before it's used	2025-08-18 13:28:00 +02:00
shellcheck.sh	tests: add `shellcheckServices`	2022-09-12 21:00:00 +02:00
tests.nix	tests: extract fn `instantiateTestsFromStr`	2025-06-26 23:23:51 +02:00
tests.py	update nixpkgs	2025-03-11 19:36:26 +00:00
wireguard-lndconnect.nix	lndconnect: add clnrest	2024-11-27 21:35:46 +01:00

README.md

The run-tests.sh command is the most convenient and versatile way to run tests.
It leave no traces (outside of /nix/store) on the host system.

run-tests.sh requires Nix with Flakes.

Summary

./run-tests.sh [--scenario|-s <scenario>] [build|vm|debug|container]

See the top of run-tests.sh for a complete documentation.
Test scenarios are defined in tests.nix and tests.py.

Tutorial

Running tests

# Run the basic set of tests. These tests are also run on the GitHub CI server.
./run-tests.sh

# Run the test for scenario `regtest`.
# The test is run via the Nix build system. Successful runs are cached.
./run-tests.sh -s regtest build
./run-tests.sh -s regtest # Shorthand, equivalent

# To test a single service, use its name as a scenario.
./run-tests.sh -s clightning

# When no scenario is specified, scenario `default` is used.
./run-tests.sh build

Debugging

# Start a shell inside a test VM. No tests are executed.
./run-tests.sh -s bitcoind vm
systemctl status bitcoind

# Run a Python NixOS test shell inside a VM.
# See https://nixos.org/manual/nixos/stable/#ssec-machine-objects for available commands.
./run-tests.sh debug
print(succeed("systemctl status bitcoind"))
run_test("bitcoind")

# Start a shell in a container node. Requires systemd and root privileges.
./run-tests.sh container

# In the container shell: Run command in container (with prefix `c`)
c systemctl status bitcoind

# Explore a single feature
./run-tests.sh -s electrs container

# Run a command in a container.
# The container is deleted afterwards.
./run-tests.sh -s clightning container --run c lightning-cli getinfo

# Define a custom scenario
./run-tests.sh --scenario '{
  services.clightning.enable = true;
  nix-bitcoin.nodeinfo.enable = true;
}' container --run c nodeinfo

Running tests with Flakes

Tests can also be accessed via the nix-bitcoin flake:

# Build test
nix build --no-link ..#tests.default

# Run a node in a VM. No tests are executed.
nix run ..#tests.default.vm

# Run a Python test shell inside a VM node
nix run ..#tests.default.run -- --debug

# Run a node in a container. Requires extra-container, systemd and root privileges
nix run ..#tests.default.container
nix run ..#tests.default.containerLegacy # For NixOS with `system.stateVersion` <22.05

# Run a command in a container
nix run ..#tests.default.container -- --run c nodeinfo
nix run ..#tests.default.containerLegacy -- --run c nodeinfo # For NixOS with `system.stateVersion` <22.05