DEPRECATED, PLEASE USE THE NEW IMPLEMENTATION AT https://github.com/tertestrial/server
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, and run in a separate terminal window outside of your editor. 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, distractions, slowdown from unnecessary test runs, and without having to leave your text editor.
Tertestrial works with all test frameworks and any text editor with a Tertestrial plugin. It comes with a set of built-in configurations for common frameworks that allow you to get started using it right away.
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.
-
install Node.js version 4 or above
-
install the Tertestrial server:
npm i -g tertestrial # or yarn global add tertestrial -
install the Tertestrial plugin for your editor
-
add
.tertestrial.tmpto your global gitignore.
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.
Editor plugins send simple JSON-encoded messages that define what the user wants Tertestrial to do. What keys and values they contain depends on your use case, and how your editor plugin works. As an example, here are the messages sent by Tertestrial-Vim:
-
when the user wants to run the current action on the whole code base
{} -
when the user wants to run the current action on the given file
{ "filename": "foo.js" } -
when the user wants to run the current action on the given line at the given file:
{ "filename": "foo.js", "line": 3 }
Tertestrial's configuration file (tertestrial.yml)
defines how Tertestrial should handle these messages.
To do that, it defines a number of actions.
These actions consist of:
- a
matchblock that has a structure comparable to commands, but with regular expressions as placeholders. An action must match an incoming message precisely in order to be run. Only the most specifically matching action is executed. - a
commandblock that contains the console command that this action performs
Below is an example configuration file for JavaScript developers who use Mocha for unit testing and Cucumber-JS for end-to-end tests:
tertestrial.yml
actions:
# Here we define what to do with files that have the extension ".feature"
- match:
filename: '\.feature$'
command: "cucumber-js {{filename}}"
# Here we define how to run just a test at the given line
# in files with the extension ".feature"
- match:
filename: '\.feature$'
line: '\d+'
command: "cucumber-js {{filename}}:{{line}}"
# Here we define what to do with files that have the extension ".js"
- match:
filename: '\.js$'
command: "mocha {{filename}}"The commands to run are specified via Mustache templates.
When you tell the setup wizard that you want to create your own custom configuration, it sets up the config file pre-populated with a built-in configuration of your choice as a starting point for your customizations.
The default format for configuration files is YAML.
Tertestrial accepts configuration files in any format
that transpiles into JavaScript or JSON,
for example JSON, CSON,
CoffeeScript, or LiveScript.
You need to have the respective transpiler installed on your system.
Please keep in mind that if you write the configuration file in a programming language,
you need to export the configuration setting via module.exports.
See the feature specs for some readable examples.
Tertestrial allows to define several sets of actions and switch between them at runtime. An example is to have one action set for running tests using a real browser and another action set to run them using a faster headless browser.
tertestrial.yml
actions:
headless:
- match:
filename: '\.feature$'
command: "TEST_PLATFORM=headless cucumber-js {{filename}}"
- match:
filename: '\.feature$'
line: '\d+'
command: "TEST_PLATFORM=headless cucumber-js {{filename}}:{{line}}"
firefox:
- match:
filename: '\.feature$'
command: "TEST_PLATFORM=firefox cucumber-js {{filename}}"
- match:
filename: '\.feature$'
line: '\d+'
command: "TEST_PLATFORM=firefox cucumber-js {{filename}}:{{line}}"When Tertestrial starts, in activates the first action set. In this example, it means if you tell it to test a file, it will do so using the headless browser. When you switch to the second action set, it well test files using Firefox as the browser.
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 configuration to the "actions" folder, matching the structure of the other files there.
- align your text editor and terminal so that you see both at the same time (for example side by side)
- in the terminal, start
tertestrialin 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.
MacOS features sophisticated power saving features. One of them is app nap, which pauses processes that run in the background and don't interact with the screen. Once paused, Tertestrial is unable to pick up and execute command from your editor.
One possible solution would be to disable app nap completely,
but that affects your battery life.
Instead, you can also set the environment variable TERTESTRIAL_PREVENT_APP_NAP
to 1.
When it is present,
Tertestrial occasionally prints and deletes a space character to your terminal,
thereby preventing the app from being suspended.
-
Fish shell users: in
~/.config/fish/config.fish:set -x TERTESTRIAL_PREVENT_APP_NAP 1 -
Bash users: in
~/.bashrc:export TERTESTRIAL_PREVENT_APP_NAP=1
Making your own editor plugin is super easy.
All your plugin has to do is be triggered somehow (ideally via hotkeys)
and write (append) the command to execute
as a JSON string into the existing file .tertestrial.tmp:
In addition to your application-specific commands, your editor plugin needs to support these built-in infrastructure messages:
-
switching to a different action set:
-
by index (1 based)
{ "actionSet": 2 } -
by name
{ "actionSet": "headless" } -
cycle through action sets
{ "cycleActionSet": "next" }
-
-
re-run the last test:
{ "repeatLastTest": true }
Ideally your editor plugin should also implement "auto-test". A mode the user can toggle on and off, which triggers a re-run of the last test when any file is saved.
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!
see our developer documentation.