Introduction
Testlane lets you run any branch, pull request or commit of your project on your own machine with one command, in a workspace of its own. Agents and teammates open pull requests faster than anyone can read them, and a diff tells you what changed, not whether the app still works. Trying a change locally usually means a clone, a fetch, an install and a copied .env first. Think of stashing your own work to check out a PR, two dev servers fighting over port 3000, or a fresh clone that won't start because its .env.local is missing.
Testlane turns a ref, like a PR number, a branch, a commit, a URL or a path, into a git worktree that's ready to run. Its dependencies are installed, its seed files are copied and it has ports of its own, so you can start the app, click through it and try the change, while your own checkout stays as it was:
testlane my-project 42 code # PR #42, opened in your editor
testlane my-project 42 run dev # the same workspace, its dev server running
testlane my-project clean --merged # remove the workspaces whose PRs merged
This page covers:
- The pipeline: the three steps that open every workspace.
- What you get: what each workspace comes with.
- FAQ: what Testlane needs, and what it leaves alone.
At a glance
| Aspect | Testlane |
|---|---|
| What it is | A command-line tool, testlane, published to npm as @uxfront/testlane |
| Needs | Node.js 18 or later and git 2.38 or later, with gh optional |
| Refs | A PR number, a branch, a full commit SHA, a URL, a path or - for the last one |
| Workspaces | One git worktree per ref, off one bare clone per project |
| Ports | A block of its own for each workspace, in $TESTLANE_PORT and {port} |
| Setup | Your install command, skipped while the files in cache_key haven't changed |
| Config | One TOML file per project, in ~/.testlane |
| Scripting | A path on stdout from checkout, --json on verbs like list and an exit code per error |
The pipeline
Let's start with the one idea the whole CLI rests on. Opening a workspace always takes the same three steps:
1Resolve
resolve(ref)Turns the ref you typed into a git target and a slug.
2Materialize
materialize(workspace)Makes a worktree with its dependencies, seed files and ports, or reuses it.
3Act
act(command)Opens an editor, runs a command or starts a shell.
Resolve turns the ref you typed into a git target, like a pull request or a branch. Materialize makes sure a worktree exists for that target, with its dependencies installed, its seed files copied and its ports allocated. It's cheap to run again, since a workspace that's already there is reused. Act does what you asked for: it opens an editor, runs a configured command, runs any command you give it or starts a shell.
checkout is the pipeline with nothing to do in the last step, and verbs like code, run and shell swap in a step of their own. So once you know the pipeline, you can tell what a verb will do before you run it. How it works shows each step in detail, down to the clone, the ports and the cached install.
What you get
Now let's look at what each workspace comes with:
Workspaces of their own
Ports that don't collide
$TESTLANE_PORT and {port} in your config, so two dev servers run side by side.Setup that runs itself
.env.local, so a new workspace is ready to run.Plain git underneath
gh, you also get each PR's state, its title and its own diff. Without it, every ref still works over plain git.FAQ
gh, Testlane still fetches a pull request from refs/pull/<n>/head, and diff uses git diff. With it, list shows each PR's state and info its title, diff shows the PR's own diff, and git push in a PR's workspace goes back to the PR's branch.refs/pull/<n>/head, which GitHub and GitHub Enterprise publish, so PR numbers need one of those.checkout prints only the workspace's path, verbs like list, info and doctor take --json, and testlane mcp serves its tools to an MCP client. Agents shows how to connect yours, with a prompt you can paste.Where to go next
Pick the page that matches what you came to do:
- New here? Install Testlane, then follow the quick start, or hand it to your agent.
- Want the model in your head? Read how it works and refs.
- Have a task in mind? Start with the guides.
- Looking up a flag? Go straight to the CLI reference.