Commands and Hooks
Named commands let you start the same thing in any workspace with one word, like run dev for your dev server or run test for your tests, with the right directory and environment every time. Hooks run your own scripts at four points in a workspace's life, so you can start a database before a command or stop a container before a removal. A repository can ship both in its .testlane.toml, and yours win over its.
At a glance
| Key | Type | Default | What it's for |
|---|---|---|---|
commands.<name>.run | string | Required | The command run <name> and start <name> run |
commands.<name>.cwd | string | The workspace | The directory to run it in, relative to the workspace |
commands.<name>.env | table | {} | Environment variables for this command only, over the project's [env] |
default_command | string | code | What testlane <project> <ref> does with no verb |
hooks.post_checkout | string | None | Runs once, after Testlane creates a workspace |
hooks.pre_run | string | None | Runs after setup, before run, exec, shell and start |
hooks.post_sync | string | None | Runs after sync resets a workspace |
hooks.pre_clean | string | None | Runs before rm or clean removes a workspace, and can stop the removal |
A repository's .testlane.toml may set every key in this table, as From the repository explains.
Named commands
Each table under [commands] becomes something run and start can run, by its name:
[commands.dev]
run = "pnpm dev"
cwd = "packages/app"
[commands.dev.env]
NODE_OPTIONS = "--max-old-space-size=8192"
[commands.test]
run = "pnpm test"
testlane my-project 42 run dev
testlane my-project 42 run test -- --watch
A command's name also works in place of a verb, so testlane my-project 42 dev does what run dev does.
| Key | What it does | Default |
|---|---|---|
run | The command, run with bash -c. It's required | None |
cwd | The directory to run it in, relative to the workspace unless it's absolute | The workspace |
env | Variables merged over the project's [env] for this command only | {} |
A command's name is lower-case letters, digits, :, _ and -, starting with a letter or a digit, like dev, test:e2e or storybook. run, cwd and the values in env can use template variables, like {port}.
Arguments after -- go on the end of the command, quoted as you typed them. run test -- --watch runs this:
bash -c 'pnpm test "$@"' testlane --watch
When you name a command after a workspace verb, like start or sync, the verb wins, so testlane my-project 42 start runs the verb. Your command is still there as testlane my-project 42 run start, and testlane doctor warns about the clash.
Default command
default_command says what Testlane does when you give it a project and a ref with no verb. It's code unless defaults.toml or the project file says otherwise:
default_command = "dev"
With that, testlane my-project 42 does what testlane my-project 42 run dev does. It takes one of the verbs checkout, code, shell, diff and info, or the name of one of the project's commands, and config validate rejects anything else:
my-project.toml: default_command: unknown command 'run'; expected a verb or one of [dev]
Hooks
Hooks are scripts of your own that Testlane runs at four points in a workspace's life. Each is a string, run with bash -c in the workspace, with the project's environment, TESTLANE_* variables included, and with template variables filled in:
[hooks]
post_checkout = "echo 'workspace ready: {path}'"
pre_run = "docker compose up -d"
post_sync = "pnpm install --frozen-lockfile"
pre_clean = "docker compose down"
| Hook | When it runs | If it exits non-zero |
|---|---|---|
post_checkout | Once, after Testlane creates a workspace and before setup | The command fails with E_SETUP, exit 6 |
pre_run | After setup, before run, exec, shell and start | The command fails with E_SETUP, exit 6 |
post_sync | After sync resets a workspace | Testlane warns and carries on |
pre_clean | Before rm or clean removes a workspace | Testlane warns and keeps that workspace |
We recommend keeping hooks fast and safe to run twice, since pre_run runs before every run, exec, shell and start. There are two exceptions: --no-setup skips it along with setup, and so does a start that finds its command already running.
When post_checkout fails, Testlane keeps the workspace but doesn't run the hook for it again. To run it again once you've fixed it, remove the workspace with rm and open it again.
pre_clean is the place to let go of what a workspace held, like a container or a scratch database, since its directory is gone after the removal. A failing pre_clean keeps that workspace, so you can also use it to stop a removal:
warning: pre_clean hook failed for feat-login — skipping
--dry-run on rm and clean prints pre_clean as the bash -c line it would run, and runs nothing.
From the repository
A repository's .testlane.toml can define [commands] and [hooks] too, so its maintainers set them up once for everyone. They join your own, and your project file wins:
| Table | How the two files merge |
|---|---|
[commands] | By name. A command of yours replaces the whole repository command of that name, cwd and env included |
[hooks] | By hook name. Your pre_run replaces the repository's pre_run, and its other hooks still run |
[env] | By key |
So to change how the repository's dev runs on your machine, define your own [commands.dev]. It's best to copy the repository command's cwd and env into yours if you still need them, since none of the repository's command is kept:
[commands.dev]
run = "pnpm dev --port {port} --open"
testlane config show my-project marks each key with where it came from. Here's an excerpt:
default_command = "dev" # repo
commands.dev.run = "pnpm dev --port {port} --open" # user
commands.test.run = "pnpm test" # repo
hooks.post_checkout = "echo ready: {path}" # repo
Trust them first
A repository's file can run anything your shell can, so its commands, hooks and setup run only after you approve that exact content. The first time, Testlane prints what the file would run, then the whole file:
my-project:.testlane.toml on origin/main would run:
setup.run pnpm install --frozen-lockfile
commands.dev.run pnpm dev --port {port}
commands.test.run pnpm test
hooks.post_checkout echo ready: {path}
--- my-project:.testlane.toml (origin/main) ---
…
---
Trust my-project:.testlane.toml? [y/N]
After a change upstream, it prints the diff from the version you approved and asks again. --yes approves without asking. With no terminal to ask on and no --yes, the command stops with exit 3:
error(E_CONFIG): my-project:.testlane.toml is not trusted
hint: testlane config trust my-project
Until you approve, your project file works on its own, and the repository's commands don't exist yet, so testlane my-project 42 run dev fails with unknown command 'dev'. Run testlane config trust my-project first. Ship a config with your repo covers trust in full.
The order things run in
Here's what testlane my-project 42 run dev does on a ref with no workspace yet:
Create the workspace
Testlane resolves the ref and fetches it, checks the repository's .testlane.toml against your approval, then adds the worktree, ports and data directory.
Run post_checkout
It runs only this once, for a new workspace.
Run setup
Testlane copies the seed files in, then runs setup.run when the files in cache_key have changed. --no-setup skips this step and the next one.
Run pre_run
It runs before every command, as long as setup ran.
Run the command
Last, Testlane runs commands.dev.run.
On a workspace that's already there, Testlane starts at setup, which is usually a cache hit:
→ worktree ready (reused)
→ setup up to date (cache hit)
→ hook pre_run
FAQ
[env] and the TESTLANE_* variables, while a command's own env and --env flags reach only that command.run dev --dry-run prints the worktree it would create, the environment and the command, but it doesn't show setup or the hooks. Environment and Templates shows what it prints.