TextRunner is a tool that executes semantic rich-text. Rich text is text with basic formatting like bold, italic, links, headings, bullet points, embedded images, etc. Text-Runner supports rich text in the form of Markdown, optionally with embedded HTML. Knowing the semantics of text means understanding what the text is talking about. As an example, if you look at a restaurant receipt, you know which of the numbers is the net amount, the tax, the tip for the staff, and the total amount. You know the meaning of these numbers, i.e. their semantics. Semantic text is any text where we understand what various parts of the text talk about. Text-Runner executes semantic rich text. It understands what type of information the various parts of a rich text document contain and runs code for each identified document part.
Text-Runner can derive the semantics of some rich text elements on its own. For example, it knows that links are references to other documents or headings inside documents and that images reference image files. This allows Text-Runner to verify the basic link structure of documents and prevent broken links and images.
You can describe domain-specific semantics using the type attribute on HTML
tags. This attribute provides the type of content inside the HTML tag. As an
example, let's say we are creating an automated test for a tutorial that teaches
people how to use the command line of computers. Here is a paragraph from this
tutorial:
## The "echo" command
Use the _echo_ command to print to the console. Try it out by running:
```
$ echo Hello world!
```
The terminal prints the output right after the call. Our first Shell program
greets us with "Hello world!"At this point, a human reader of the tutorial will run echo Hello world! and
verify the output. To test this tutorial, all we have to do is point out which
part of the document contains the command to run and which part contains the
output to look for. We'll use <a> tags since they don't change the formatting
of the document.
## The "echo" command
Use the _echo_ command to print to the console. Try it out by running:
<a type="shell/command">
```
$ echo Hello world!
```
</a>
The terminal prints the output right after the call. Our first Shell program
greets us with <a type="shell/command-output">`Hello world!`</a>.We have created two active regions in the document. The first active region is
of type shell/command. It contains the shell command that the user should run.
When executing this tutorial, Text-Runner will run the command action from the
shell plugin. This action takes the textual content inside its active region
and executes it in a shell, exactly like a human user would. The second active
region (of type shell/command-output) contains the output expected when
running this command. It takes the output generated by the previous
shell/command call and compares it against the content inside its active
region. Ultimately, Text-Runner has performed the same steps a human reader of
the tutorial would do, using the actual document content. Text-Runner plays the
tutorial through. This makes sure that the tutorial still works after making
changes to either the tutorial or the product that the tutorial describes.
Pro tip: if you have basic familiarity with HTML, you could simplify the above paragraph to:
## The "echo" command
Use the _echo_ command to print to the console. Try it out by running:
<pre type="shell/command">
$ echo Hello world!
</pre>
The terminal prints the output right after the call. Our first Shell program
greets us with <code type="shell/command-output">Hello world!</code>.- the built-in actions
- writing your own custom actions