Tertestrial Server

Runs the currently relevant test while coding.

Tertestrial runs configurable tasks on files or parts of files. Tasks are triggered by hotkeys from within your code editor, or automatically on file save. A common application for this is running a particular unit test that is currently driving your development, i.e. which you want to make green, as part of test-driven development. With Tertestrial you can do this with an absolute minimum of key presses, noise and slowdown from unnecessary test runs, and without having to leave your text editor.

[screencast coming soon]

Tertestrial works with all test frameworks (a lot are built-in) and any text editor with a Tertestrial plugin.

Installation

install Node.js
install the Tertestrial server:
```
npm i -g tertestrial
```
install the Tertestrial plugin for your editor
add .tertestrial.tmp to your global gitignore.

Creating a configuration file

To use Tertestrial with a code base, run tertestrial --setup in the root directory of that code base. This generates a configuration file that tells Tertestrial what to do with the different types of files in your project.

The setup script asks whether you want to use one of the built-in configurations or make your own. If you select a built-in configuration, you are done with the setup and can start using Tertestrial.

If you want to make your own custom configuration, the setup script scaffolds a config file for you that you have to finish yourself. Make it look similar to the example configuration file below, which is for running unit tests using Mocha and end-to-end tests using Cucumber-JS:

tertestrial.yml

mappings:
  js:
    testFile: "mocha {{filename}}"
    testLine: "mocha {{filename}} -l {{line}}"
  feature:
    testFile: "cucumber-js {{filename}}"
    testLine: "cucumber-js {{filename}}:{{line}}"

In this example, js and feature are the filename extensions for which we provide test commands. testFile means the user wants to run all tests in the current file, testLine means to run only the test at the current line of the current file. The commands to run are specified via Mustache templates.

If you have created a good config file that you think should ship with Tertestrial, please submit a PR that adds a file with your mapping to the mappings folder, matching the structure of the other files there.

Multiple mapping sets

Tertestrial allows to define several sets of mappings and switch between them at runtime. An example is to have one mapping for running end-to-end tests using a real browser and another mapping to run them using a faster headless browser.

tertestrial.yml

mappings:

  - headless:
      feature:
        testFile: "TEST_PLATFORM=headless cucumber-js {{filename}}"
        testLine: "TEST_PLATFORM=headless cucumber-js {{filename}}:{{line}}"

  - firefox:
      feature:
        testFile: "TEST_PLATFORM=firefox cucumber-js {{filename}}"
        testLine: "TEST_PLATFORM=firefox cucumber-js {{filename}}:{{line}}"

Running tertestrial

align your text editor and terminal so that you see both at the same time (for example side by side)
in the terminal, start tertestrial in the base directory of your code base
in the text editor, send some commands using the tertestrial editor plugin
watch your tests run in your terminal

To end the server, press ctrl-c in the terminal.

Pro tip: if you start tertestrial in the background by running tertestrial &, you can see all test output, and your terminal remains interactive, i.e. you can keep running other commands there as well. Just start typing in the terminal to see your command prompt. To exit the Tertestrial server in this case, run fg to bring tertestrial back into the foreground, then press ctrl-c.

How it works

Tertestrial consists of a server (in this repository) and a number of editor plugins. The editor plugins send commands to the server via a named pipe .tertestrial.tmp in the directory where you start the server (typically the base directory of the code base you are working on). Tertestrial removes this pipe when stopping.

Editor plugins

Create your own editor plugin

Making your own editor plugin is super easy. All your plugin has to do is be triggered somehow (ideally via hotkeys) and write the command to execute as a JSON string into the file .tertestrial.tmp:

to test a whole file:

{"operation": "testFile", "filename": "test/foo.rb"}

to test just the current line of a file:

{"operation": "testLine", "filename": "test/foo.rb", "line": 12}

to repeat the last run test
```
{"operation": "repeatLastTest"}
```

to switch to a different mapping:

{"operation": "setMapping", "mapping": 2}

Credits

This software is based on an idea described by Gary Bernhard in his excellent Destroy All Software screencasts. If you find this software useful, subscribe to Gary's talks and presentations for more of his cool ideas!

Development

see our developer documentation.

alexdavid / tertestrial-server