Reusable core architecture

TextRunner Go Core Architecture

This idea is similar to the PickleRunner idea for Cucumber and could be based on the same code base.

Why not use an outside Go binary like Gauge

• Installation is hard: people/CI Servers have to determine and download the correct binary for their system. Very often there is already a programming language used that has a package manager to bring dependencies and other test tools onto the developer machine. No point in reinventing this delivery mechanism.
• This would almost always result in a global installation of Text-Runner on the developer machine. It is better to use project-specific versions of all test tools including Text-Runner
• The Gauge workflow of installing the right binary first, then installing one or more language runtimes inside Gauge is cumbersome and complicated. There are already package managers for most languages. No point in reinventing them here.
• the Gauge architecture requires HTTP connections between the subprocesses. This can cause problems with firewalls.
• not all test environments want to run a CLI binary for testing. Some use cases might be better served with a JS or Java API, for example when building integrations into IDEs or larger build pipelines.

Architecture

The architecture consists of a language-specific wrapper, for example written in JavaScript or Java, and a reusable core written in Rust (core). The wrapper provides a CLI command that is called to run a test, i.e. node_modules/.bin/text-run

Markdown parsers for Go:

• BlackFriday: the most popular, does not give line numbers (source)

Installation

• TextRunner is installed by installing the language-specific wrapper via the package manager used by the code base, e.g. npm install -D text-runner
• the wrapper downloads the correct version of the core for its version and the platform it is running at. It could also contain all the possible binaries to make this step unnecessary.

Operation

To run a test, the user calls the binary provided by the wrapper:

text-run *.md

Inside Text-Runner, the following things happen:

• the wrapper finds and parses the step implementations for the code base (located in the text-run directory)
• the wrapper calls the core as a subprocess, forwarding the appropriate command-line options (in our example *.md)
• wrapper and core communicate via IO streams:
  • StdIn to core: command for core to execute
  • StdErr from core: command for wrapper to execute
  • StdOut from core: output to print to the terminal
• when starting up, the core finds the documentation files to test, parses them, and compiles the list of tests to run
• to executing each test in the test list, the core sends a runStep command to the parent process (via StdErr).
• when receiving the runStep command, the wrapper runs the step with the given name and returns the outcome to the core via a runResult command sent to the core's StdIn.
• the formatters run in core. Their output goes to StdOut. The wrapper simply forwards this output stream to the terminal.