# Commands and Hooks

> Name the commands you run in every workspace, like your dev server and your tests, hook your own scripts into a workspace's life, and merge them with a repository's .testlane.toml.

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](#from-the-repository) explains.

## Named commands

Each table under `[commands]` becomes something `run` and `start` can run, by its name:

```toml [~/.testlane/my-project.toml]
[commands.dev]
run = "pnpm dev"
cwd = "packages/app"

[commands.dev.env]
NODE_OPTIONS = "--max-old-space-size=8192"

[commands.test]
run = "pnpm test"
```

```bash
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](https://testlane.dev/docs/configuration/environment-and-templates), 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:

```toml [~/.testlane/my-project.toml]
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:

```toml [~/.testlane/my-project.toml]
[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:

```toml [~/.testlane/my-project.toml]
[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](https://testlane.dev/docs/guides/ship-a-config-with-your-repo#approve-it) 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:

::steps{level="3"}

### 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

::accordion
  :::accordion-item{label="Do hooks get the command's env?"}
  No. Hooks and setup get the project's `[env]` and the `TESTLANE_*` variables, while a command's own `env` and `--env` flags reach only that command.
  :::

  :::accordion-item{label="Can I see what run would do without running it?"}
  Partly. `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](https://testlane.dev/docs/configuration/environment-and-templates#check-the-result) shows what it prints.
  :::
::
