# 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:

```bash
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:

::pipeline-diagram
::

**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](https://testlane.dev/docs/concepts/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:

::card-group

::card
---
title: Workspaces of their own
icon: i-lucide-folder-tree
---
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.
::

::card
---
title: Ports that don't collide
icon: i-lucide-plug
---
Each workspace gets its own ports, in `$TESTLANE_PORT` and `{port}` in your config, so two dev servers run side by side.
::

::card
---
title: Setup that runs itself
icon: i-lucide-package
---
Testlane installs the dependencies and copies the seed files, like `.env.local`, so a new workspace is ready to run.
::

::card
---
title: Plain git underneath
icon: i-lucide-git-pull-request
---
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

::accordion
  :::accordion-item{label="Does Testlane touch my own checkout?"}
  No. Testlane clones each project once, as a bare clone of its own, and makes every workspace a worktree off that clone. Your own checkout only comes in when you pass its path as the ref, and even then Testlane never removes it, since it didn't create it.
  :::

  :::accordion-item{label="Do I need the GitHub CLI?"}
  No, but we recommend it. Without `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.
  :::

  :::accordion-item{label="Does it work with hosts other than GitHub?"}
  Branches, commits and paths work with any git remote. A pull request ref fetches `refs/pull/<n>/head`, which GitHub and GitHub Enterprise publish, so PR numbers need one of those.
  :::

  :::accordion-item{label="Can agents use it too?"}
  Yes. `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](https://testlane.dev/docs/getting-started/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](https://testlane.dev/docs/getting-started/installation), then follow the [quick start](https://testlane.dev/docs/getting-started/quick-start), or [hand it to your agent](https://testlane.dev/docs/getting-started/agents).
- **Want the model in your head?** Read [how it works](https://testlane.dev/docs/concepts/how-it-works) and [refs](https://testlane.dev/docs/concepts/refs).
- **Have a task in mind?** Start with the [guides](https://testlane.dev/docs/guides/review-a-pull-request).
- **Looking up a flag?** Go straight to the [CLI reference](https://testlane.dev/docs/cli/overview).
