Configuration

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 variableEnvironment variableValue
{path}TESTLANE_PATHThe workspace's absolute path
{repo_path}TESTLANE_REPO_PATHThe absolute path of the project's clone
{data_dir}TESTLANE_DATA_DIRThe workspace's private data directory
{project}TESTLANE_PROJECTThe project's name
{ref}TESTLANE_REFThe ref, like feat/login, or the number of a pull request
{branch}TESTLANE_BRANCHThe branch, like feat/login, or pr/42 for a pull request
{slug}TESTLANE_SLUGThe workspace's slug, like feat-login or pr-42
{port}TESTLANE_PORTThe workspace's first port
{port+N}TESTLANE_PORT_1 and upThe 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:

~/.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:

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 shows how the ports and the data directory keep each workspace apart from the others.

Copyright © 2026