4aaef5fdf4
Let A be a service that depends on another service B. When A can gracefully handle failures and restarts of B, use ``` wants = [ "B.service" ]; after = [ "B.service" ]; ``` instead of ``` requires = [ "B.service" ]; after = [ "B.service" ]; ``` in the definition of A. This way, A keeps running when B is stopped or restarted after a failure. With `requires`, A is instead stopped when B is stopped or restarted due to a failure. This brings two benefits: 1. Improved uptime Examples: - RTL keeps running when one lightning node has failed - btcpayserver keeps running and accepting on-chain payments when the lightning node has crashed 2. Avoids a systemd bug where depending units (`A.service` in the above example) are not restarted when their dependency fails (issue github/systemd#18856, no full link to avoid spamming the issue). In real world nix-bitcoin deployments, this issue was only likely to appear when clightning failed during activation, causing depending units (like `RTL`) to stop and not be restarted. All services depending on `clightning` have now been changed to use `wants`, thereby avoiding the bug. Services `electrs` and `lightning-loop` fail when their respective dependencies stop, so these services have not been changed. I also haven't changed services `joinmarket` and `joinmarket-yieldgenerator`. Further manual testing is needed to determine if they can be switched to `wants`. |
||
|---|---|---|
| .. | ||
| ci | ||
| lib | ||
| nixos-search | ||
| clightning-replication.nix | ||
| README.md | ||
| run-tests.sh | ||
| shellcheck.sh | ||
| tests.nix | ||
| tests.py | ||
| wireguard-lndconnect.nix | ||
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