This package provides [Text-Runner](https://github.com/kevgo/text-runner) actions for documenting console commands to be executed by the reader.
npm install textrun-shellThis package provides Text-Runner
actions for documenting console commands to be executed by the reader.
To add this package as a Text-Runner plugin:
npm i -D textrun-shell
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:
``js
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
}
}
`
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:
`html
The "echo" command prints text on the command line. For example, let's run:
echo Hello world!
Some tutorials print a dollar sign at the beginning of the command to execute,
indicating an interactive command prompt. These dollar signs are ignored.
$3
By default, this step fails if the subshell command exits with a non-zero exit
code. To allow errors, add the
attribute, like so:`html
echo Hello world!
`$3
You can provide the command to run via an HTML attribute:
html
The "echo" command prints text on the command line. For example, let's run:
`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:
md
It welcomes us with a nice greeting:
Hello world!
`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:
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:
Output to wait for
input
your name
Text-Runner
which day is today
Monday
It prints:
Hello Text-Runner, happy Monday!
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.
elements are considered
descriptions and are also ignored.$3
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:
Output to wait for
input
your name
Text-Runner
which day is today
Tuesday
Then it prints:
Hello Text-Runner, happy Tuesday!
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:
`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:
html
Start the server:
node server.js
`$3
You can also provide the command to start the server via the
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:
html
Wait until the server is fully booted up:
server is running
`shell/stop-server
Stop a long-running process with the
shell/stop-server action.
Here is the final part of our hypothetical server tutorial:
html
When you are done, stop the server:
killall node
``