Getting Started

Introduction

Run any branch, pull request or commit of your project locally with one command, in a workspace of its own that leaves your checkout alone.

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

AspectTestlane
What it isA command-line tool, testlane, published to npm as @uxfront/testlane
NeedsNode.js 18 or later and git 2.38 or later, with gh optional
RefsA PR number, a branch, a full commit SHA, a URL, a path or - for the last one
WorkspacesOne git worktree per ref, off one bare clone per project
PortsA block of its own for each workspace, in $TESTLANE_PORT and {port}
SetupYour install command, skipped while the files in cache_key haven't changed
ConfigOne TOML file per project, in ~/.testlane
ScriptingA 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:

  1. 1Resolve

    resolve(ref)

    Turns the ref you typed into a git target and a slug.

  2. 2Materialize

    materialize(workspace)

    Makes a worktree with its dependencies, seed files and ports, or reuses it.

  3. 3Act

    act(command)

    Opens an editor, runs a command or starts a shell.

Every command that opens a workspace runs these three steps, in order.

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

One git worktree per ref, all off one bare clone. You can keep several refs open at once, and none of them touches your own checkout.

Ports that don't collide

Each workspace gets its own ports, in $TESTLANE_PORT and {port} in your config, so two dev servers run side by side.

Setup that runs itself

Testlane installs the dependencies and copies the seed files, like .env.local, so a new workspace is ready to run.

Plain git underneath

With gh, you also get each PR's state, its title and its own diff. Without it, every ref still works over plain git.

FAQ

Where to go next

Pick the page that matches what you came to do:

Copyright © 2026