From 740dd666ade668d19ffde2e729b4653335778b91 Mon Sep 17 00:00:00 2001 From: Erik Arvstedt Date: Sun, 15 Jan 2023 20:27:50 +0100 Subject: [PATCH] docs: move test docs from `examples/README` to `test/README` --- examples/README.md | 55 +----------------------------- test/README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++ test/run-tests.sh | 2 +- 3 files changed, 86 insertions(+), 55 deletions(-) create mode 100644 test/README.md diff --git a/examples/README.md b/examples/README.md index 0ede270..6997ad9 100644 --- a/examples/README.md +++ b/examples/README.md @@ -51,60 +51,7 @@ the node: ``` ### Tests -The internal test suite is also useful for exploring features.\ -The following `run-tests.sh` commands leave no traces (outside of `/nix/store`) on -the host system. - -`run-tests.sh` requires Nix >= 2.10. - -```bash -git clone https://github.com/fort-nix/nix-bitcoin -cd nix-bitcoin/test - -# Run a node in a VM. No tests are executed. -./run-tests.sh vm -systemctl status bitcoind - -# Run a Python test shell inside a VM node -./run-tests.sh debug -print(succeed("systemctl status bitcoind")) -run_test("bitcoind") - -# Run a node in a container. Requires systemd and root privileges. -./run-tests.sh container -c systemctl status bitcoind - -# Explore a single feature -./run-tests.sh --scenario electrs container - -# Run a command in a container -./run-tests.sh --scenario '{ - services.clightning.enable = true; - nix-bitcoin.nodeinfo.enable = true; -}' container --run c nodeinfo -``` -See [`run-tests.sh`](../test/run-tests.sh) for a complete documentation. - -#### Flakes -Tests can also be directly accessed via Flakes: -```bash -# 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 -``` +The [nix-bitcoin test suite](../test/README.md) is also useful for exploring features. ### Real-world example Check the [server repo](https://github.com/fort-nix/nixbitcoin.org) for https://nixbitcoin.org diff --git a/test/README.md b/test/README.md new file mode 100644 index 0000000..4cc4125 --- /dev/null +++ b/test/README.md @@ -0,0 +1,84 @@ +The [`run-tests.sh`](./run-tests.sh) command is 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 >= 2.10. + +### Summary +```bash +./run-tests.sh [--scenario|-s ] [build|vm|debug|container] +``` + +See the top of [run-tests.sh](../test/run-tests.sh) for a complete documentation.\ +Test scenarios are defined in [tests.nix](./tests.nix) and [tests.py](tests.py). + +### Tutorial +#### Running tests +```bash +# 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 +```bash +# Start a shell is 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: + +```bash +# 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 +``` diff --git a/test/run-tests.sh b/test/run-tests.sh index f6c75f3..57296de 100755 --- a/test/run-tests.sh +++ b/test/run-tests.sh @@ -4,7 +4,7 @@ # The tests (defined in ./tests.nix) use the NixOS testing framework and are executed in a VM. # # Usage: -# Run all tests +# Run the basic set of tests. These are also run on the CI server. # ./run-tests.sh # # Test specific scenario