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:

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

import * as path from "path"
import * as url from "url"

const __dirname = url.fileURLToPath(new URL(".", import.meta.url))
const foo_path = path.join(__dirname, "bin", "foo")
// console.log(`calling "foo" in the documentation now runs ${foo_path}`)

export default {
  globals: {
    "foo": foo_path
  }
}

shell/command

The shell/command action runs a shell command and waits until it finishes. The shell/command-output action verifies the output of the most recently executed shell command.

As an example, here is a hypothetical tutorial for how to use the Linux shell:

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

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

Some tutorials print a dollar sign at the beginning of the command to execute, indicating an interactive command prompt. These dollar signs are ignored.

allow-error attribute

By default, this step fails if the subshell command exits with a non-zero exit code. To allow errors, add the allow-error attribute, like so:

<pre type="shell/command" allow-error>
echo Hello world!
</pre>

command attribute

You can provide the command to run via an HTML attribute:

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

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

shell/command-output

The shell/command-output action verifies the output of the most recently executed shell command.

Here is the next paragraph of our hypothetical tutorial for the Linux shell:

It welcomes us with a nice greeting:

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

Some tutorials print a dollar sign at the beginning of the command to execute, indicating an interactive command prompt. These dollar signs are ignored.

shell/command-with-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.

command attribute

You can provide the command to run via the command HTML attribute. As an example, if you run the previous script with this other input:

Then it prints:

shell/server

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 write a tutorial about developing a web server, have just created an implementation in file server.js:

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

Our tutorial instructs the user to start this long-running server to run in parallel with Text-Runner with the shell/server action:

Start the server:

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

command attribute

You can also provide the command to start the server via the command attribute.

shell/server-output

After we started a long-running server through shell/server above, we can await specific output from it using the shell/server-output action.

Here is the next paragraph of our hypothetic server tutorial:

Wait until the server is fully booted up:

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

shell/stop-server

Stop a long-running process with the shell/stop-server action.

Here is the final part of our hypothetical server tutorial:

When you are done, stop the server:

<pre type="shell/stop-server">
killall node
</pre>