jigUser Guide
Overview
Jig is a better Fantom build and test tool.
Jig wraps fan build.fan and fant with output you can scan: a line per pod or test class as each one finishes, a live status bar pinned to the bottom of the terminal, and errors and failures collected at the end with only the lines that matter.
jig build # compile every pod under your root build script jig test # test every pod in your workenv jig build -f # clean, compile, then test
Install
Install from Eggbox with fanr:
fanr install jig
If your etc/fanr/config.props doesn't default to Eggbox, pass the repo:
fanr install -r https://eggbox.fantomfactory.org/fanr/ jig
Run this from outside any workenv (a directory with no fan.props above it). fanr installs into the current env's lib/fan/, so outside a workenv jig lands in your Fantom home and fan jig works from any workenv.
To build from source instead, copy the pod into your Fantom home (fan -version prints the fan.home path):
fan src/jig/build.fan cp lib/fan/jig.pod <fan.home>/lib/fan/
Run as jig
On macOS or Linux, save this script as jig in the bin/ directory of the Fantom install you want it to use, next to fan and fant (fan -version prints the fan.home path), and make it executable with chmod +x:
#!/bin/sh
. "${0%/*}/fanlaunch"
fanlaunch Fan jig "$@"Now jig test acme works the same as fan jig test acme. Like fant and fanr, it runs with the Fantom install it lives in, not whichever fan is first on your PATH. Don't symlink it elsewhere, since it finds fanlaunch next to itself.
Build
jig build [<pod> | <file.fan>]* [options]
For example:
jig build # ./build.fan, else <workDir>/src/build.fan jig build acme # pod acme under the root build script jig build src/acme/build.fan # a build script by path jig build -c # clean only jig build -f # clean, compile, then test jig build -t dist # run another build script target
A BuildGroup builds all of its children, including nested groups. jig build compiles by default; -c, -f, and -t each pick what runs instead, so use only one. Options:
-c,--clean: clean only, without compiling-f,--full: clean and compile, then test every built pod that has tests; tests are skipped if any pod fails to compile-t,--target <name>: run this build script target instead of compile-q,--quiet: only print errors, status bar, and summary
Output. One line per pod and target as each finishes, with ok / fail and elapsed time:
$ jig build acme ······· [compile] ok (54ms) acmeData ··· [compile] ok (62ms) acmeApi ···· [compile] ok (21ms) acmeWeb ···· [compile] ok (1462ms) acmeCli ···· [compile] ok (7ms) ✓ Built 5 pods to lib/fan/ in 1.9sec
A group runs each target across all of its pods before the next, so -f shows every [clean] row, then every [compile] row. The pod being built sits above the status bar with its current build step in dim text.
Compiler warnings are printed dim under their pod and counted in the summary. Errors are printed together above the summary, which ends with where the pods were written.
Indented output from custom build steps is hidden. Rows come from top level <target> [<pod>] lines, so a custom target that doesn't log one shows only in the status bar, and -t test mixes fant output in with the build; use jig test for that.
Test
jig test <targets>* [options]
Test targets use the same syntax as fant:
jig test # all pods in workDir lib/fan/ jig test acme # all tests in pod jig test acme::FooTest # all tests in a type jig test acme::FooTest.testBar # a single test method
Options:
-q,--quiet: only print failures, status bar, and summary-es: test new ECMA JavaScript environment (passthrough)-js: test legacy JavaScript environment (passthrough)
fant -all runs every pod the env can resolve, including Fantom core and any fan.props path dependencies. jig test with no targets only runs pods built into your workenv's own lib/fan/, and refuses to run outside a workenv.
Output. One line per test class, grouped by pod:
$ jig test acme AddrTest ········ [ 7/ 7] pass (3ms) CsvReaderTest ··· [10/10] pass (1ms) InvoiceTest ····· [12/12] pass (1277ms) ScheduleTest ···· [ 6/ 6] pass (43ms) SyncTest ········ [ 3/ 3] pass (6.0sec) UserTest ········ [ 5/ 5] pass (3ms) [✓ 43 passed (7.4sec)] acmeWeb AssetTest ······· [ 4/ 4] pass (60ms) RenderTest ······ [16/16] pass (3475ms) RouteTest ······· [22/22] pass (5ms) SessionTest ····· [ 8/ 8] pass (408ms) [✓ 50 passed (3966ms)] ✓ All 93 tests passed [601 verifies] in 11.5sec
[passed/total]counts, with columns aligned across all podspass/failwith elapsed time for the class (4900msunder 5sec,7.2secunder a minute, then1min 2sec)- A
FAIL: <method>line under the class for each failed test - A summary line after each pod when the run covers more than one pod
Output from passing tests is hidden. The run ends with the details for every failure together, so you don't have to hunt through scrollback: anything the test printed (prefixed with |) and the stack trace with test harness frames (reflection, TestRunner, verify internals) removed. Then a one-line summary, plus one line per failure showing how many tests in that class failed.
Terminal Output
Options may come before or after targets. Exit code is 0 on success, 1 otherwise.
Status bar. When stdout is a terminal, the bottom line shows BUILD or TEST, percent complete, pods or tests done, ok/fail counts, and total elapsed time; for tests it also shows the current pod and its progress, so you know where you are after the pod header scrolls away. The pod or test class currently running sits above it with a live timer.
Quiet (-q) drops the per-pod and per-class lines: only failures, the status bar, and the summary are printed.
Colors and the status bar are disabled when output is piped, CI is set, or TERM=dumb.
Platform Support
Jig is built for macOS and Linux terminals. It runs on Windows, but the terminal output has rough edges:
- Colors and status bar. Jig uses ANSI escape codes, which Windows Terminal supports but the legacy console does not. Use Windows Terminal, or set
TERM=dumbto get plain output. - Symbols.
✓ ✗ █ ░need a UTF-8 console. Runchcp 65001first if they show as garbled characters. - Terminal width. Width detection uses
stty, which Windows lacks, so jig assumes 80 columns. SetCOLUMNSto your window width if long lines wrap.
Build Scripts
You don't need to change your build scripts: jig build --full cleans, compiles, and tests every pod, and jig test tests every pod in your workenv.
To have fan build.fan test use jig too, override test in your BuildPod. Failing tests fail the build:
class Build : BuildPod
{
...
@Target { help = "Run the pod unit tests via jig" }
override Void test()
{
fan := devHomeDir + (Env.cur.os == "win32" ? `bin/fan.bat` : `bin/fan`)
Exec(this, [fan.osPath, "jig", "test", podName]).run
}
}Exec captures jig's output, so in build scripts jig prints plain output without colors or the status bar.
How it Works
Jig resolves targets up front, so typos fail fast and the status bar knows the total. jig test spawns a single fant process and parses its output as tests run. jig build loads your build scripts to find their pods, then runs fan <build.fan> <target> and parses the build log.