# Environment and Templates

> Give each workspace its own ports, paths and data directory in your config, with template variables like {port} and the TESTLANE_* environment.

Template variables and the `TESTLANE_*` environment let one config fit every workspace, since each one fills in its own ports, paths and data directory. Write `"{port}"` once in your project file, and every branch's dev server gets a port of its own. Reach for this page when you wire a port, a path or a database file into your config.

## At a glance

| Template variable | Environment variable          | Value                                                         |
| ----------------- | ----------------------------- | ------------------------------------------------------------- |
| `{path}`          | `TESTLANE_PATH`               | The workspace's absolute path                                 |
| `{repo_path}`     | `TESTLANE_REPO_PATH`          | The absolute path of the project's clone                      |
| `{data_dir}`      | `TESTLANE_DATA_DIR`           | The workspace's private data directory                        |
| `{project}`       | `TESTLANE_PROJECT`            | The project's name                                            |
| `{ref}`           | `TESTLANE_REF`                | The ref, like `feat/login`, or the number of a pull request   |
| `{branch}`        | `TESTLANE_BRANCH`             | The branch, like `feat/login`, or `pr/42` for a pull request  |
| `{slug}`          | `TESTLANE_SLUG`               | The workspace's slug, like `feat-login` or `pr-42`            |
| `{port}`          | `TESTLANE_PORT`               | The workspace's first port                                    |
| `{port+N}`        | `TESTLANE_PORT_1` and up      | The port `N` places after it, for `N` up to `ports - 1`       |

For a commit, which has no branch, `{branch}` and `TESTLANE_BRANCH` hold the slug, like `sha-1a2b3c4d5e`.

## Template variables

Template variables put a workspace's own values into your config. Write the name in braces, and Testlane fills it in, in one pass, when a command uses it:

```toml [~/.testlane/my-project.toml]
ports = 2

[env]
PORT = "{port}"
API_PORT = "{port+1}"
DATABASE_URL = "file:{data_dir}/dev.db"
VITE_BASE_URL = "http://localhost:{port}"
```

They work in these places:

- `[env]` values, and each command's `env` values.
- `commands.<name>.run` and `commands.<name>.cwd`.
- `setup.run`.
- `hooks.*`.
- Editor templates, where `{path}` is quoted for the shell.

Write `{{` for a literal `{`. A name Testlane doesn't know stops the command with `E_CONFIG` and exit `3`, and the hint lists the names it does know:

```
error(E_CONFIG): env.API_PORT: unknown template variable '{port+1}'
hint: known variables: branch, data_dir, path, port, project, ref, repo_path, slug
```

That's also what `{port+1}` gives you in a project with the default `ports = 1`, since `{port+N}` only exists while `N` is less than `ports`. Keep in mind that `config validate` doesn't fill in templates, so it won't catch this: the command that uses the template does. `--env K=V` values on the command line are used as they are, without templates.

## The exported environment

Every command, setup and hook a workspace runs gets the `TESTLANE_*` variables in the table above, whether your config uses them or not. A workspace with more than one port also gets `TESTLANE_PORT_1`, `TESTLANE_PORT_2` and so on, up to `ports - 1`.

Testlane builds the environment in layers, and a later layer wins over an earlier one:

1. The environment you ran Testlane in, so your `PATH` and its version manager shims come along.
2. The `TESTLANE_*` variables.
3. The project's `[env]`.
4. The command's own `env`, for `run` and `start`.
5. `--env K=V` flags.

Setup and hooks get the first three layers.

## Check the result

`--dry-run` on `run`, `exec` or `shell` shows what a command would get without starting it, which makes it the quickest way to check a template. It prints the steps that would create the workspace, the environment as `export` lines and the command, quoted for the shell:

```bash
testlane my-project feat/login run dev --dry-run
```

```
mkdir -p /home/you/dev/testlane/my-project/trees
git -C /home/you/dev/testlane/my-project/repo fetch --no-tags origin --end-of-options feat/login
git -C /home/you/dev/testlane/my-project/repo worktree add /home/you/dev/testlane/my-project/trees/feat-login -B feat/login --track origin/feat/login
mkdir -p /home/you/dev/testlane/my-project/trees/.data/feat-login
export TESTLANE_PATH=/home/you/dev/testlane/my-project/trees/feat-login
export TESTLANE_REPO_PATH=/home/you/dev/testlane/my-project/repo
export TESTLANE_DATA_DIR=/home/you/dev/testlane/my-project/trees/.data/feat-login
export TESTLANE_PROJECT=my-project
export TESTLANE_REF=feat/login
export TESTLANE_BRANCH=feat/login
export TESTLANE_SLUG=feat-login
export TESTLANE_PORT=4206
export TESTLANE_PORT_1=4207
export PORT=4206
export API_PORT=4207
export DATABASE_URL=file:/home/you/dev/testlane/my-project/trees/.data/feat-login/dev.db
export VITE_BASE_URL=http://localhost:4206
bash -c 'npm run dev "$@"' testlane
```

The `export` lines leave out the environment you ran Testlane in, so you only see what Testlane adds. A dry run doesn't probe the ports, so a workspace that had to move off a busy port can get a different one when it runs for real.

## The data directory

`{data_dir}`, or `$TESTLANE_DATA_DIR`, is a private directory for each workspace, at `{worktrees_path}/.data/<slug>`. It's outside the worktree, so we recommend it for anything that shouldn't show up in `git status`, like SQLite files, uploads and caches. Testlane creates it with the workspace, before setup runs, and removes it with the workspace.

[Workspaces and Worktrees](https://testlane.dev/docs/concepts/workspaces) shows how the ports and the data directory keep each workspace apart from the others.
