To understand the architecture, let's follow the control flow when testing a set of documents.
File src/text-runner.ts contains the
JavaScript API for the Text-Runner's engine. It exposes a
number of commands. To run Text-Runner, you instantiate one of
these commands with configuration data and call
their execute method. Please note that the Text-Runner configuration file is
considered a part of the text-runner-cli wrapper. The
engine does not load it automatically.
The Text-Runner engine is headless. When testing documentation, all it does is emit events defined by the events.Name enum. Callers can subscribe to this event stream to follow test progress. For example, the text-runner-cli module displays test steps on the CLI. The end-to-end tests doesn't print anything but collects emitted events to verify them against the events expected by the test.
Commands like the run command have a functional architecture. It converts the configuration into test results over several steps:
- configuration --> list of Markdown files to test: this is done by the filesystem module
- list of filenames --> list of file ASTs: the parse module reads each file and parses it into the standard AST format. The standard AST is optimized for analyzing and testing,and identical for comparable Markdown and HTML input.
- list of ASTs --> list of tests activities to execute: the activities module finds active blocks in the ASTs and gathers all the related information. The output of this step is several lists: parallelizable tests like checking static file and image links and sequential tests that have to run one after the other.
- list of test activities --> list of test results: the run module executes the test steps given to it and emits test results via the event stream described earlier.