Text-Runner Actions for the Text-Runner test workspace

Some Text-Runner actions create files and folders on disk. These files and folders get created in a temporary directory called the workspace so that they don't interfere with the codebase that you document. This package provides Text-Runner actions for interacting with this Text-Runner workspace.

installation

npm i -D textrun-workspace

new-file

The workspace/new-file action creates a file in the workspace. This action assumes that the documentation writes the filename in emphasized or bold text, or inside a filename attribute, and the file content is a code block with one or three backticks. Here are a few examples that all do the same thing. See if you can figure out what it does.

<a type="workspace/new-file">

Create file _apples.txt_ with the content `Fuji apples are the best`.

</a>

<a type="workspace/new-file">

Create file **apples.txt** with the content:

```
Fuji apples are the best
```

</a>

When executing the documentation, Text-Runner will create a file with name apples.txt and content Fuji apples are the best in the workspace.

"dir" attribute

You can override in which directory Text-Runner looks for the file to append content to with the dir attribute:

<a type="workspace/new-file" dir="subdir">

Create file _apples.txt_ with the content `Fuji apples are the best`.

</a>

When executing the documentation, Text-Runner will create a file with name subdir/apples.txt and content Fuji apples are the best in the workspace.

"filename" attribute

If you don't want to repeat the filename in the text too often, you can also provide it invisibly through the filename attribute. In that case, the file content is the entire content of the active region.

<pre type="workspace/new-file" filename="apples.txt">
Gala aren't that bad either!
</pre>

When executing the documentation, Text-Runner will create a file with name apples.txt and content Gala aren't that bad either! in the workspace.

append-file

The workspace/append-file action appends the given text to the given file.

Assume the workspace contains file greeting/hello.txt with content hello. Then you execute this documentation:

<a type="workspace/append-file">

Now append ` sun` to file _greeting/hello.txt_.

</a>.

Now file greeting/hello.txt has content hello sun.

"dir" attribute

You can override in which directory Text-Runner looks for the file to append content to with the dir attribute:

<a type="workspace/append-file" dir="greeting">

Now append ` and moon` to file _hello.txt_.

</a>.

Now file greeting/hello.txt has content hello sun and moon.

"filename" attribute

If you don't want to repeat the filename in the text too often, you can also provide it invisibly through the filename attribute. In that case, the file content is the entire content of the active region.

<code type="workspace/append-file" filename="greeting/hello.txt">light</code>

Now file greeting/hello.txt has content hello sun and moonlight.

compare-files

The workspace/compare-files action compares the content of the given files.

Assume the workspace contains file one.txt, with content hello, and file two.txt, also with content hello. Then this documentation passes:

<a type="workspace/compare-files" have="one.txt" want="two.txt"></a>.

copy-file

The workspace/copy-file action copies the given file.

Assume the workspace contains file greeting/hello.txt with content hello. Then you execute this documentation:

<a type="workspace/copy-file" src="greeting/hello.txt" dst="new.txt"></a>.

Now your workspace contains a new file new.txt with content hello.

empty-file

The workspace/empty-file action creates an empty file. An example is this documentation:

Please a file <b type="workspace/empty-file">.gitkeep</b>. It's okay to leave it empty.

When executing the documentation, Text-Runner will create a file with name .gitkeep in the workspace.

"dir" attribute

You can override in which directory to create the empty file by providing a dir attribute:

Please create an empty file <b type="workspace/empty-file" dir="subdir">.gitkeep</b>.

When executing the documentation, Text-Runner will create a file with name subdir/.gitkeep in the workspace.

"filename" attribute

You can provide the filename invisibly through the filename attribute.

<code type="workspace/empty-file" filename="otherdir/.gitkeep"></code>

When executing the documentation, Text-Runner will create a file with name otherdir/.gitkeep in the workspace.

existing-directory

The workspace/existing-directory action verifies that the workspace contains a directory with the given name. As an example, consider this documentation snippet:

Please run the command <code type="shell/command">mkdir images</code>.

If everything goes well, your computer will now have a new directory
<i type="workspace/existing-directory">images</i>.

"dir" attribute

You can override in which subdirectory of the workspace to look for the directory by providing a dir attribute:

Please run the command <code type="shell/command">mkdir subdir/images</code>.

If everything goes well, your computer will now have a new directory
<i type="workspace/existing-directory" dir="subdir">images</i>.

existing-file

The workspace/existing-file action verifies that a file with the given name exists. As an example, assuming the workspace contains a file hello.txt, we can verify it's existence via this action:

<code type="workspace/existing-file">hello.txt</code>

"dir" attribute

By default, this action looks for files in the workspace. You can tell it to look in a different directory inside the workspace by providing a dir attribute. Assuming the workspace contains a file subdir/hello.txt, we can verify it's existence via this action:

<code type="workspace/existing-file" dir="subdir">hello.txt</code>

existing-file-with-content

The workspace/existing-file-with-content action verifies that a file with the given name exists in the workspace and has the given content. This action assumes that the documentation contains the filename as emphasized or strong text and the file content as a code block with single or triple backticks.

Assuming the workspace contains a file hello.txt with content hello world, we can verify it via this action:

<a type="workspace/existing-file-with-content">

The file _hello.txt_ now contains `hello world`.

</a>

"dir" attribute

By default, this action creates the file in the workspace. To create it in a different directory, provide a name of the directory using the dir attribute.

As an example, if the workspace contains file subdir/apples.txt with the content Boskoop, we can verify it like this:

<a type="workspace/existing-file-with-content" dir="subdir">
  The file <em>apples.txt</em> now contains <code>Boskoop</code>.
</a>

"filename" attribute

If you don't want to repeat the filename in the text too often, you can also provide it invisibly through the filename attribute. In that case, the file content is the entire content of the active region.

<a type="workspace/existing-file-with-content" filename="hello.txt">
hello world
</a>

"partial-match" attribute

By default, this action matches the entire file content. If you want to verify only a part of the file content, like a single line, provide the partial-match attribute.

Consider the workspace contains file findings.txt with content:

finding 1

# Additional findings

finding 2

We can verify the caption like this:

<a type="workspace/existing-file-with-content" partial-match>

The file _findings.txt_ now contains `# Additional findings`.
</a>

new-directory

The workspace/new-directory action creates a directory with the given name in the workspace. Here is a usage example:

Create a directory named <b type="workspace/new-directory">utils</b>.

When executing this Markdown snippet, Text-Runner will create a utils directory in the workspace, just as the user would.

"dir" attribute

You can override in which directory the new directory gets created by providing a dir attribute:

Create a directory named <code type="workspace/new-directory" dir="subdir">utils</code>.

When executing this Markdown snippet, Text-Runner will create a subdir/utils directory in the workspace.

working-dir

Each Text-Runner test starts in the workspace directory. The workspace/working-dir action changes the working directory of the test runner to another directory inside the workspace. To change into the directory the reader created above:

Please change into the
<code type="workspace/working-dir">utils</code>
folder.