Text-Runner Shell Actions

This package provides Text-Runner actions for documenting console commands to be executed by the reader.

Setup

To add this package as a Text-Runner plugin, run npm i -D textrun-shell or yarn i -D textrun-shell.

You can define the absolute path of documented binaries in a textrun-shell.js file in the root directory of your documentation. Here is an example:

export default {
  binaries: {
    "text-run": path.join(__dirname, "node_modules", ".bin", "text-run"),
  },
}

Run shell commands

The shell/command action runs a shell command and waits until it finishes. As an example, here is a little hypothetical Shell tutorial:

The "echo" command prints text on the command line. For example, let's run:

$ echo Hello world!

It welcomes us with a nice greeting:

Hello world!

The source code of this Shell tutorial when executed and verified by Text-Runner looks like this:

The "echo" command prints text on the command line. For example, let's run:

<pre type="shell/command">
$ echo Hello world!
</pre>

It welcomes us with a nice greeting:

<pre type="shell/command-output">
Hello world!
</pre>

Dollar signs at the beginning of lines indicate a shell prompt and are ignored. The shell/command-output action documents output of the last shell command run.

User input

You can run a shell command and enter text into it with the shell/command-with-input action.

As an example, let's say we have a command-line tool written in JavaScript called greeter.js:

import * as readline from "readline"
var rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  terminal: false,
})

rl.question("your name\n", name => {
  rl.question("which day is today\n", day => {
    console.log(`Hello ${name}, happy ${day}!`)
    rl.close()
    process.exit()
  })
})

Run this tool on the command line

$ node greeter.js

and provide user input with an HTML table:

It prints:

If the table contains multiple columns, the first column contains output to wait for, and the last one text to enter once the output from the first column has appeared. Middle columns are ignored. <th> elements are considered descriptions and are also ignored.

Long-running processes

Long-running processes, for example web or database servers, keep running while Text-Runner continues executing other actions.

As an example, let's say we have a server called server.js:

console.log("server is running")
setTimeout(() => {}, 100_000)

Start this long-running server to run in parallel with Text-Runner with the shell/server action. Wait for output using the shell/server-output action. Stop the server with the shell/stop-server action. Here is an example that shows them in action:

Start the server:

<pre type="shell/server">
$ node server.js
</pre>

Wait until it is fully booted up:

<pre type="shell/server-output">
server is running
</pre>

Now you can interact with the server. When you are done, stop the server:
<a type="shell/stop-server">shell/stop-server</a>