textrun-npm

Text-Runner Actions for npm

This package provides Text-Runner actions for verifying the documentation of npm packages.

Installation

To use these actions, add this package as a development dependency by running npm i -D textrun-npm.

Verify installation instructions

The npm/install action verifies installation instructions for an npm package. As an example, let's assume we are testing the documentation of an npm package called foobar. Its package.json file would contain amongst other things:

{
  "name": "foobar"
}

In the documentation of this npm package, we want to document how to install this package. It would contain a section that looks something like this:

Install the foobar package by running:

<pre type="npm/install">
npm install foobar
</pre>

or with Yarn:

<pre type="npm/install">
yarn add foobar
</pre>

Text-Runner verifies that the installation instructions contain the correct name of the npm package.

Verify exported binaries

The npm/exported-executable action verifies documentation of exported binaries of npm packages. Let's say our foobar package provides an executable file bin/foo, which is listed as a binary in the package.json file:

{
  "name": "foobar",
  "bin": {
    "foo": "bin/foo"
  }
}

The documentation for the "foobar" package would document this binary like this:

After you install the "foobar" package, you can run the
<code type="npm/exported-executable">foo</code> command in the terminal.

Verify installed binaries

The npm/installed-executable action verifies binaries installed by other npm packages. Let's say you develop technical documentation for a codebase that uses the cucumber command provided by the npm cucumber package:

To run the end-to-end tests, run
<code type="npm/installed-executable">cucumber</code> in the terminal.

Verify script names defined in package.json

The npm/script-name action verifies that you document scripts that your package.json file defines correctly.

Let's say your npm package has this package.json file:

{
  "name": "foobar",
  "scripts": {
    "lint": "echo linting"
  }
}

And your documentation says:

To run the linters, please run the
<code type="npm/script-name">lint</code> script.

Verify calls of scripts defined in package.json

The npm/script-call action verifies that you document calls of scripts defined in your package.json file correctly.

Let's say your npm package has this package.json file:

{
  "name": "foobar",
  "scripts": {
    "lint": "echo linting"
  }
}

And your documentation says:

To run the linters, please execute
<code type="npm/script-call">npm run lint</code>.