Guides

Script with Testlane

Drive Testlane from shell scripts and CI, with data on stdout, JSON you can parse and exit codes you can branch on.

By the end of this guide, your scripts and CI jobs open workspaces with Testlane and act on the result without parsing a line meant for people. Testlane is built to be driven by other programs, and three rules make that safe: data goes to stdout and everything else to stderr, --json gives you a shape to parse and every failure has an exit code of its own.

Before you start

You'll need Testlane installed and a configured project, which we'll call my-project. The examples use jq to read JSON.

Script your first workspace

Check out a ref as JSON

testlane my-project feat/login checkout --json
{"project":"my-project","slug":"feat-login","ref":"feat/login","kind":"branch","branch":"feat/login","path":"/home/you/dev/testlane/my-project/trees/feat-login","ports":[4153],"created":true}

Each result is one line of JSON on stdout. path is the workspace's absolute path, and created is false when the workspace already existed, which tells you whether a first-time step still needs to run. The progress lines, and the output of any hook the checkout runs, go to stderr, so they reach your terminal without getting in the way.

Check the exit code and move into the workspace

json=$(testlane my-project "$REF" checkout --json) || {
  code=$?
  [ "$code" -eq 4 ] && echo "unknown ref: $REF" >&2
  exit "$code"
}
cd "$(echo "$json" | jq -r .path)"

When a command fails, it prints nothing on stdout and exits with a code that says why, so read the code rather than the error text. Here, 4 means Testlane couldn't find the ref. We name the variable code rather than status, since status is read-only in zsh.

Answer the prompts

testlane my-project clean --merged --yes

clean and rm ask before they remove anything. Without a terminal to ask in, they stop with E_USAGE (exit 2), so add --yes in every script.

Keep data and progress apart

Everything meant for people goes to stderr: progress lines (→ …), warnings (warning: …), errors and the commands -v prints (· …). Only the result goes to stdout, so $(testlane …) captures the data and nothing else.

There's one exception. The output of your project's [setup] and hooks goes to stdout too, unless you pass --json, which moves it to stderr. A plain checkout prints the path on stdout, but a post_checkout hook that prints something lands before it, so $(testlane my-project 42 checkout) can hold more than the path. So pass --json, or --no-setup where you don't need the install, whenever you capture the output of a command that can run them, like checkout, run, exec or start.

Read the JSON

checkout, list, info, start, ps, projects, doctor and config validate take --json. Here are the four you'll use most.

list --json prints an array with one object per workspace:

testlane my-project list --json
[{"slug":"feat-login","ref":"feat/login","kind":"branch","branch":"feat/login","path":"/home/you/dev/testlane/my-project/trees/feat-login","adopted":false,"ports":[4153],"createdAt":"2026-11-14T09:36:51.351Z","lastUsedAt":"2026-11-14T09:36:51.459Z","dirty":false,"missing":false}]

info --json prints one object of the same shape, for one workspace:

testlane my-project feat/login info --json

projects --json prints one object per project file:

testlane projects --json
[{"name":"my-project","repo":"git@github.com:my-org/my-project.git","workspaces":1,"pathExists":true}]

pathExists is false until the first checkout clones the repository. The JSON of start and ps is in Use Testlane from an agent.

Branch on the exit code

Every command exits 0 when it succeeds. Any other code tells you what went wrong:

CodeNameWhat it means
0It worked
1E_INTERNALSomething failed inside Testlane
2E_USAGEA flag or argument is wrong
3E_CONFIGA config is missing or invalid
4E_RESOLVETestlane couldn't find the ref
5E_GITA git or gh command failed
6E_SETUPA setup step, a hook that can block or start failed

A failure prints one error(E_…) line on stderr, often followed by a hint::

error(E_RESOLVE): branch 'does-not-exist' does not exist on origin
hint: check the name, or push the ref first

Exit codes has the full reference.

Examples

These are the patterns we reach for most.

Run a command in every workspace of a project:

testlane my-project list --json \
  | jq -r '.[].slug' \
  | while read -r slug; do
      testlane my-project "$slug" exec --no-setup -- git log -1 --oneline
    done

Run a first-time step only when the workspace is new:

created=$(testlane my-project "$REF" checkout --json | jq -r '.created')
[ "$created" = "true" ] && ./scripts/seed.sh

Remove every merged workspace in a nightly job:

testlane my-project clean --merged --yes

Where to go next

Here's where to go from here:

Copyright © 2026