Exit Codes
Exit codes let a script tell what went wrong without reading the message: a typo in a flag, a project that isn't set up, a branch that doesn't exist or a server that didn't start. Every error also prints a name, like E_RESOLVE, so you can find it here and in Troubleshooting.
At a glance
| Code | Name | What it means | For example |
|---|---|---|---|
0 | None | Success | The command did what you asked |
1 | E_INTERNAL | Something failed that Testlane didn't expect, or a doctor check failed | A bug, or FAIL in doctor |
2 | E_USAGE | The command doesn't make sense | An unknown flag, a missing --yes, a command start can't run next to another |
3 | E_CONFIG | The config is missing or wrong | An unknown project, a file that doesn't validate, no config directory, a repository's .testlane.toml you haven't approved |
4 | E_RESOLVE | The ref or the workspace can't be found | A branch that isn't on origin, a ref with no workspace for sync or info |
5 | E_GIT | A git or gh command failed, or git would lose work | sync on a workspace with changes, a lock that times out |
6 | E_SETUP | [setup], a hook that can block or start failed | An install that fails, a server that never opens its port, a program exec can't find |
Error output
Let's start with what an error looks like. It's one line on stderr with the name and the message, often followed by a hint that says what to do:
error(E_CONFIG): unknown project 'nope'
hint: known projects: my-project
error(E_RESOLVE): branch 'nope' does not exist on origin
hint: check the name, or push the ref first
error(E_USAGE): unsupported shell 'ksh'
hint: one of: bash, zsh, fish
The error goes to stderr only, so it never ends up in what a script captures from stdout. With -v or TESTLANE_DEBUG=1, the stack trace follows the hint.
Codes from your own commands
Now let's look at the codes Testlane passes on. run, exec, shell and code with a terminal editor like vim exit with the exit code of what they ran, so a failing test run fails the same way under Testlane:
testlane my-project feat/login exec -- sh -c 'exit 7'
echo $?
7
Keep in mind that such a code can match one in the table above, so a test runner that exits 2 looks like a usage error. When you need to tell them apart, check stderr for a line that starts with error(, which is how Testlane prints its own errors.
Branching on the code
Finally, let's look at scripts. We recommend branching on the exit code rather than the message, since the wording of a message can change between versions while the codes don't:
testlane my-project feat/login checkout -q
case $? in
0) echo "ready" ;;
4) echo "no such branch, push it first" ;;
*) echo "something else went wrong" ;;
esac
Note that a failing outside tool other than git, like gh, can print the name E_EXTERNAL, with the same code 5 as E_GIT. Script with Testlane has more patterns, and Troubleshooting has a fix for each error.
Global Flags
The flags every Testlane command takes, for the config directory, the kind of ref, dry runs, JSON output, how much it logs and prompts.
Overview
Where Testlane keeps your project files, what goes in the config directory, what a repository's own .testlane.toml adds, and how to create, edit and check a project.