Configuration

Project File

Every key a Testlane project file takes, from the repository to setup, with its type, its default and what it's for.

A project file tells Testlane where a project's repository is and how to get a workspace of it running, so you can open any of its refs with one command. Reach for this page when you add a project or want to know what a key does. Each project has one file at <config-dir>/<project>.toml, and a repository can ship a .testlane.toml that sets some of the same keys for everyone. Only repo is required:

~/.testlane/my-project.toml
repo = "git@github.com:my-org/my-project.git"
default_branch = "main"
editor = "zed"
ports = 2
base_port = 5700

[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]

[env]
PORT = "{port}"
API_PORT = "{port+1}"

[commands.dev]
run = "pnpm dev"

At a glance

KeyTypeDefaultWhat it's for
repostringRequiredThe repository's clone URL, over SSH or HTTPS
repo_pathpath{root}/{project}/repoWhere Testlane keeps the project's clone
worktrees_pathpath{root}/{project}/treesWhere the workspaces go
default_branchstringDetected from origin on the first cloneThe branch diff compares against and clean --merged checks
editorstringdefaults.editor, then codeWhat code opens a workspace in
default_commandstringdefaults.default_command, then codeWhat testlane <project> <ref> does with no verb
portsinteger, 1 to 101How many ports each workspace gets
base_portinteger, 1024 to 65000Derived from the project's nameWhere the project's ports start
setup.runstringNoneThe install command for a workspace
setup.cache_keylist of globs[]The files whose changes make setup run again
setup.seed_fileslist of paths[]Files to copy into a new workspace
setup.seed_frompathNoneA second place to copy seed files from
envtable of strings{}Environment variables for commands, setup and hooks
commands.<name>tableNoneNamed commands for run and start
hooks.<name>stringNoneScripts that run at four points in a workspace's life

{root} is root from defaults.toml, and {project} is the project's name. A path may start with ~ for your home directory, and Testlane expands nothing else in it, like $HOME. We recommend absolute paths or paths that start with ~, since a relative one is read from the directory you run Testlane in.

A repository's .testlane.toml may set default_command, ports, setup.run, setup.cache_key, setup.seed_files, [env], [commands] and [hooks]. The other keys describe your machine, so they're user-only: they go in your project file, and Testlane rejects them in the repository's file. Where both files set a key, yours wins, as Ship a config with your repo explains. The tables below say which keys a repository may set.

Repository keys

These say where the project's code comes from and where its copies go on disk.

KeyTypeDefaultIn .testlane.toml
repostringRequiredUser-only
repo_pathpath{root}/{project}/repoUser-only
worktrees_pathpath{root}/{project}/treesUser-only
default_branchstringDetected from origin on the first cloneUser-only

repo is the URL Testlane clones, and it's also how it knows which project a pull request URL belongs to. Without root in defaults.toml, set repo_path and worktrees_path yourself, since there's nothing to put them under. worktrees_path can't be inside repo_path.

We recommend setting default_branch. Testlane only looks it up from origin in the run that first clones the repository, and it doesn't keep what it found, so later runs don't know it. Without it, diff falls back to a plain git diff of the working tree rather than showing everything since the ref left the default branch, and clean --merged checks for merged branches against main.

Behaviour keys

These shape what Testlane does with a workspace once it has one.

KeyTypeDefaultIn .testlane.toml
editorstringdefaults.editor, then codeUser-only
default_commandstringdefaults.default_command, then codeAllowed
portsinteger, 1 to 101Allowed
base_portinteger, 1024 to 650003000 + (hash of the name % 40) × 100User-only

editor is a preset name, like zed or nvim, or a template of your own, and Editors lists them. default_command is 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. Commands and Hooks shows it at work.

ports is how many ports in a row each workspace gets, from {port} to {port+N}. Each project picks its workspaces' ports from a window that starts at base_port and is 100 × ports wide. The derived base_port puts projects 100 apart, which fits the default of one port each, so if you raise ports, we recommend setting base_port too, to keep the project's window clear of the others. Run dev servers in parallel walks through a setup with two ports.

[setup]

[setup] gets a fresh workspace ready to run: it copies in your seed files, then runs your install command. It runs before run, exec, shell and start, unless you pass --no-setup, and checkout and code run it when you pass --setup. Leave the table out and nothing is copied or installed.

~/.testlane/my-project.toml
[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]
seed_from = "~/dev/my-project"
KeyTypeWhat it doesIn .testlane.toml
runstringThe install command, run with bash -c in the workspace, with template variablesAllowed
cache_keylist of globsThe files Testlane hashes, relative to the workspace, to decide whether run needs to run againAllowed
seed_fileslist of pathsPaths relative to the workspace, with no .., to copy in when they aren't there yetAllowed
seed_frompathA directory to copy seed files from when seeds/<project>/ doesn't have themUser-only

cache_key is what makes the second run in a workspace fast. Testlane hashes every file its globs match, leaving out node_modules/ and .git/, and skips run while the hash is the same as at the last install that worked. Without a cache_key, the hash never changes, so run installs once per workspace. A failed install keeps the old hash, so the next command tries again.

Seed files never overwrite a file that's already in the workspace, unless you pass --reseed. Seed local files walks through them.

[env], [commands] and [hooks]

These three tables have pages of their own, since each does a lot. A repository's .testlane.toml may set all three:

  • [env] sets environment variables for every command, setup and hook in a workspace, with template values like "{port}". See Environment and Templates.
  • [commands.<name>] gives run and start something to run, with a cwd and an env of its own. See Commands and Hooks.
  • [hooks] runs your scripts after checkout, before a command, after sync and before a removal. See Commands and Hooks.

How Testlane checks the file

Testlane reads a project file strictly: a key it doesn't know is an error, not something it skips. That way a typo, like worktree_path for worktrees_path, stops you straight away instead of quietly doing nothing. Check a file after you change it:

testlane config validate my-project
my-project.toml: ports: Number must be less than or equal to 10
my-project.toml: (root): Unrecognized key(s) in object: 'worktree_path'

Testlane lists every problem in the file in one run, then exits 3 (E_CONFIG). Any other command that loads a broken file stops with E_CONFIG too.

A repository's .testlane.toml is checked as strictly. Testlane checks it when it reads it from the default branch, in config trust, config add or a command that checks out a workspace, and it names a user-only key and the file to move it to:

error(E_CONFIG): my-project:.testlane.toml: editor: user-only key; set it in my-project.toml

Keep in mind that config validate doesn't read the default branch, so it checks only the copy of the repository's file you've approved.

Copyright © 2026