From c9251e72a1ccd8c9d325427417c55e0698672428 Mon Sep 17 00:00:00 2001
From: Erik Arvstedt <erik.arvstedt@gmail.com>
Date: Sun, 27 Sep 2020 12:43:32 +0200
Subject: [PATCH] README: add run-tests.sh to examples

---
 README.md         | 26 ++++++++++++++++++++++++--
 test/run-tests.sh |  3 +++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 04e4f36..b505016 100644
--- a/README.md
+++ b/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:
diff --git a/test/run-tests.sh b/test/run-tests.sh
index d360419..8608318 100755
--- a/test/run-tests.sh
+++ b/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
 #