Text-Runner actions for the Text-Runner workspace
npm install textrun-workspaceSome 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.
``
npm i -D textrun-workspace
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.
Create file _apples.txt_ with the content Fuji apples are the best.
`
Create file apples.txt with the content:
`
Fuji apples are the best
``
When executing the documentation, Text-Runner will create a file with name
_apples.txt_ and content
Fuji apples are the best in the workspace.
You can override in which directory Text-Runner looks for the file to append
content to with the dir attribute:
Create file _apples.txt_ with the content Fuji apples are the best.
`
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.
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.
`html`
Gala aren't that bad either!
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.
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:
Now append sun to file _greeting/hello.txt_.
.
`
Now file _greeting/hello.txt_ has content hello sun.
You can override in which directory Text-Runner looks for the file to append
content to with the dir attribute:
Now append and moon to file _hello.txt_.
.
`
Now file _greeting/hello.txt_ has content hello sun and moon.
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.
`html`light
Now file _greeting/hello.txt_ has content hello sun and moonlight.
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:
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:
Now your workspace contains a new file _new.txt_ with content hello.
The workspace/empty-file action creates an empty
file. An example is this documentation:
`html`
Please a file .gitkeep. It's okay to leave it empty.
When executing the documentation, Text-Runner will create a file with name
.gitkeep in the workspace.
You can override in which directory to create the empty file by providing a
dir attribute:
`html`
Please create an empty file .gitkeep.
When executing the documentation, Text-Runner will create a file with name
subdir/.gitkeep in the workspace.
You can provide the filename invisibly through the filename attribute.
`html`
When executing the documentation, Text-Runner will create a file with name
otherdir/.gitkeep in the workspace.
The workspace/existing-directory action verifies
that the workspace contains a directory with the given name. As an example,
consider this documentation snippet:
`html
Please run the command mkdir images.
If everything goes well, your computer will now have a new directory
images.
`
You can override in which subdirectory of the workspace to look for the
directory by providing a dir attribute:
`html
Please run the command mkdir subdir/images.
If everything goes well, your computer will now have a new directory
images.
`
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:
`markdown`hello.txt
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:
`markdown`hello.txt
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:
The file _hello.txt_ now contains hello world.
`
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:
`markdown`
The file apples.txt now contains Boskoop.
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.
`markdown`
hello world
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
finding 2
`
We can verify the caption like this:
The file _findings.txt_ now contains # Additional findings.`
The workspace/new-directory action creates a
directory with the given name in the workspace. Here is a usage example:
`html`
Create a directory named utils.
When executing this Markdown snippet, Text-Runner will create a
utils directory in the workspace,
just as the user would.
You can override in which directory the new directory gets created by providing
a dir attribute:
`html`
Create a directory named utils.
When executing this Markdown snippet, Text-Runner will create a
subdir/utils directory in the
workspace.
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:
`html``
Please change into theutils
folder.