1 files changed, 78 insertions, 0 deletions
diff --git a/subplot/vendored/daemon.md b/subplot/vendored/daemon.md
index 131dcb1..9484926 100644
--- a/subplot/vendored/daemon.md
+++ b/subplot/vendored/daemon.md
@@ -25,6 +25,84 @@ then there is no "/bin/sleep 12765" process
 ~~~
 
 
+# Daemon takes a while to open its port
+
+[netcat]: https://en.wikipedia.org/wiki/Netcat
+
+This scenario verifies that if the background process never starts
+listening on its port, the daemon library handles that correctly. We
+do this by using [netcat][] to start a dummy daemon, after a short
+delay. The lib/daemon code will wait for netcat to open its port, by
+connecting to the port. It then closes the port, which causes netcat
+to terminate.
+
+~~~scenario
+given a daemon helper shell script slow-start-daemon.sh
+given there is no "slow-start-daemon.sh" process
+when I try to start "./slow-start-daemon.sh" as slow-daemon, on port 8888
+when I stop background process slow-daemon
+then there is no "slow-start-daemon.sh" process
+~~~
+
+~~~{#slow-start-daemon.sh .file .sh .numberLines}
+#!/bin/bash
+
+set -euo pipefail
+
+sleep 2
+netcat -l 8888 > /dev/null
+echo OK
+~~~
+
+# Daemon never opens the intended port
+
+This scenario verifies that if the background process never starts
+listening on its port, the daemon library handles that correctly.
+
+~~~scenario
+given there is no "/bin/sleep 12765" process
+when I try to start "/bin/sleep 12765" as sleepyhead, on port 8888
+then starting daemon fails with "ConnectionRefusedError"
+then a process "/bin/sleep 12765" is running
+when I stop background process sleepyhead
+then there is no "/bin/sleep 12765" process
+~~~
+
+
+# Daemon stdout and stderr are retrievable
+
+Sometimes it's useful for the step functions to be able to retrieve
+the stdout or stderr of of the daemon, after it's started, or even
+after it's terminated. This scenario verifies that `lib/daemon` can do
+that.
+
+~~~scenario
+given a daemon helper shell script chatty-daemon.sh
+given there is no "chatty-daemon" process
+when I start "./chatty-daemon.sh" as a background process as chatty-daemon
+when daemon chatty-daemon has produced output
+when I stop background process chatty-daemon
+then there is no "chatty-daemon" process
+then daemon chatty-daemon stdout is "hi there\n"
+then daemon chatty-daemon stderr is "hola\n"
+~~~
+
+We make for the daemon to exit, to work around a race condition: if
+the test program retrieves the daemon's output too fast, it may not
+have had time to produce it yet.
+
+
+~~~{#chatty-daemon.sh .file .sh .numberLines}
+#!/bin/bash
+
+set -euo pipefail
+
+trap 'exit 0' TERM
+
+echo hola 1>&2
+echo hi there
+~~~
+
 
 ---
 title: Acceptance criteria for the lib/daemon Subplot library