Project File
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:
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
| Key | Type | Default | What it's for |
|---|---|---|---|
repo | string | Required | The repository's clone URL, over SSH or HTTPS |
repo_path | path | {root}/{project}/repo | Where Testlane keeps the project's clone |
worktrees_path | path | {root}/{project}/trees | Where the workspaces go |
default_branch | string | Detected from origin on the first clone | The branch diff compares against and clean --merged checks |
editor | string | defaults.editor, then code | What code opens a workspace in |
default_command | string | defaults.default_command, then code | What testlane <project> <ref> does with no verb |
ports | integer, 1 to 10 | 1 | How many ports each workspace gets |
base_port | integer, 1024 to 65000 | Derived from the project's name | Where the project's ports start |
setup.run | string | None | The install command for a workspace |
setup.cache_key | list of globs | [] | The files whose changes make setup run again |
setup.seed_files | list of paths | [] | Files to copy into a new workspace |
setup.seed_from | path | None | A second place to copy seed files from |
env | table of strings | {} | Environment variables for commands, setup and hooks |
commands.<name> | table | None | Named commands for run and start |
hooks.<name> | string | None | Scripts 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.
| Key | Type | Default | In .testlane.toml |
|---|---|---|---|
repo | string | Required | User-only |
repo_path | path | {root}/{project}/repo | User-only |
worktrees_path | path | {root}/{project}/trees | User-only |
default_branch | string | Detected from origin on the first clone | User-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.
| Key | Type | Default | In .testlane.toml |
|---|---|---|---|
editor | string | defaults.editor, then code | User-only |
default_command | string | defaults.default_command, then code | Allowed |
ports | integer, 1 to 10 | 1 | Allowed |
base_port | integer, 1024 to 65000 | 3000 + (hash of the name % 40) × 100 | User-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.
[setup]
run = "pnpm install --frozen-lockfile"
cache_key = ["pnpm-lock.yaml", "**/package.json"]
seed_files = [".env.local"]
seed_from = "~/dev/my-project"
| Key | Type | What it does | In .testlane.toml |
|---|---|---|---|
run | string | The install command, run with bash -c in the workspace, with template variables | Allowed |
cache_key | list of globs | The files Testlane hashes, relative to the workspace, to decide whether run needs to run again | Allowed |
seed_files | list of paths | Paths relative to the workspace, with no .., to copy in when they aren't there yet | Allowed |
seed_from | path | A directory to copy seed files from when seeds/<project>/ doesn't have them | User-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>]givesrunandstartsomething to run, with acwdand anenvof its own. See Commands and Hooks.[hooks]runs your scripts after checkout, before a command, aftersyncand 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.
Overview
Where Testlane keeps your project files, what goes in the config directory, what a repository's own .testlane.toml adds, and how to create, edit and check a project.
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.