README: add run-tests.sh to examples

README.md

@@ -24,11 +24,11 @@ The goal is to make it easy to deploy a reasonably secure Bitcoin node with a us
 It should allow managing bitcoin (the currency) effectively and providing public infrastructure.
 It should be a reproducible and extensible platform for applications building on Bitcoin.
 
-Example
+Examples
 ---
 The easiest way to try out nix-bitcoin is to use one of the provided examples.
 
-```
+```bash
 git clone https://github.com/fort-nix/nix-bitcoin
 cd nix-bitcoin/examples/
 nix-shell
@@ -48,6 +48,28 @@ shut down immediately. They leave no traces (outside of `/nix/store`) on the hos
   NixOps can be used to deploy to various other backends like cloud providers.\
   Requires: [Nix](https://nixos.org/nix/), [VirtualBox](https://www.virtualbox.org)
 
+#### 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.
+
+```bash
+git clone https://github.com/fort-nix/nix-bitcoin
+cd nix-bitcoin/test
+
+# Run a Python test shell inside a VM node
+./run-tests.sh debug
+print(succeed("systemctl status 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
+```
+See [`run-tests.sh`](test/run-tests.sh) for a complete documentation.
+
 Available modules
 ---
 By default the `configuration.nix` provides:

test/run-tests.sh

@@ -13,6 +13,9 @@
 #     When <scenario> is undefined, the test is run with an adhoc scenario
 #     where services.<scenario> is enabled.
 #
+#     Example:
+#     ./run-tests.sh -s electrs
+#
 #   Run test and link results to avoid garbage collection
 #   ./run-tests.sh [--scenario <scenario>] --out-link-prefix /tmp/nix-bitcoin-test build
 #