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.
-
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.
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.
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}}"
- 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.
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.
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}
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.