Environment and Templates
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:
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'senvvalues.commands.<name>.runandcommands.<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:
- The environment you ran Testlane in, so your
PATHand its version manager shims come along. - The
TESTLANE_*variables. - The project's
[env]. - The command's own
env, forrunandstart. --env K=Vflags.
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.
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.
Editors
Choose what testlane code opens a workspace in, from a preset like zed or nvim to a command of your own.