Run Dev Servers in Parallel
By the end of this guide, two branches of the same project run their dev servers at the same time, each on a port of its own. Testlane gives every workspace its own block of ports and keeps it for the workspace's life, so all you do is tell your app which variable to read.
Before you start
You'll need a configured project with a [commands.dev] entry whose server reads its port from an environment variable, like PORT. We'll call the project my-project.
Run two branches at once
Hand the port to your app
Map the workspace's port onto the variable your app reads, with the {port} template variable in [env]:
[env]
PORT = "{port}"
[commands.dev]
run = "pnpm dev"
Testlane also exports the port as $TESTLANE_PORT to every command, whether or not your config uses it. [env] is how you give it the name your app expects.
Start the first branch
testlane my-project feat/login run dev
→ fetching origin/feat/login
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-login
→ running setup
…
listening on 4153
run keeps your terminal while the server runs, so open a second one for the next step.
Start the second branch
testlane my-project feat/search run dev
→ fetching origin/feat/search
→ worktree ready: /home/you/dev/testlane/my-project/trees/feat-search
→ running setup
…
listening on 4160
Each workspace got its own port, so both servers are up at once.
See which port each one holds
testlane my-project list
SLUG KIND BRANCH STATUS PORT AGE LAST USED
feat-search branch feat/search clean 4160 0m 0m
feat-login branch feat/login clean 4153 0m 0m
For one workspace in a script, testlane my-project feat/login info --json prints its ports as an array.
Give a workspace several ports
An app with a web server, an API and a database needs a port for each. Set ports to the size of the block, and refer to the others as {port+1}, {port+2} and so on:
base_port = 5700
ports = 3
[env]
PORT = "{port}"
API_PORT = "{port+1}"
DB_PORT = "{port+2}"
VITE_API_URL = "http://localhost:{port+1}"
ports takes 1 to 10, and {port+N} works for any N below ports. Your commands also get the block as $TESTLANE_PORT, $TESTLANE_PORT_1 and $TESTLANE_PORT_2.
Keep in mind that testlane config validate checks the value of ports, but not your template variables. A {port+3} with ports = 3 fails when a command runs, with E_CONFIG (exit 3):
error(E_CONFIG): env.DB_PORT: unknown template variable '{port+3}'
hint: known variables: branch, data_dir, path, port, port+1, port+2, project, ref, repo_path, slug
When you raise ports, we recommend setting base_port too, as above. Without it, Testlane picks a base port for each project from its name, 100 apart, which fits one port per workspace but lets bigger blocks run into the next project's ports.
Keep in mind that a workspace keeps the block it got when it was created, so new ports and base_port values apply to new workspaces only. A workspace that already exists fails with unknown template variable '{port+1}' until you create it again:
testlane my-project feat/login sync --fresh
Pin the base port
base_port is where a project's ports start. Pin it when you want the same ranges on every machine of a team, or to keep two projects apart:
base_port = 5700
ports = 2
It takes 1024 to 65000. Each workspace starts from a port worked out from its slug, within 100 blocks above base_port, and moves up a block only when that one is taken by another workspace or something already listens on it. So a branch gets the same port every time you open it, and bookmarks and OAuth callback URLs keep working.
Change the port for one run
When something else holds a workspace's port for a while, or you want to try another one, you can override it for a single run:
testlane my-project feat/login run dev --port 6000
--port changes the first port for this run only. Nothing is saved, and the workspace keeps its block. Note that start doesn't take --port, since the process it leaves running always serves the workspace's own port, so ps and your hooks agree on it.
See what your app gets
To see the environment a command would get, without running anything, add --dry-run:
testlane my-project feat/login run dev --dry-run
…
export TESTLANE_PATH=/home/you/dev/testlane/my-project/trees/feat-login
export TESTLANE_REPO_PATH=/home/you/dev/testlane/my-project/repo
export TESTLANE_DATA_DIR=/home/you/dev/testlane/my-project/trees/.data/feat-login
export TESTLANE_PROJECT=my-project
export TESTLANE_REF=feat/login
export TESTLANE_BRANCH=feat/login
export TESTLANE_SLUG=feat-login
export TESTLANE_PORT=4153
export PORT=4153
bash -c 'pnpm dev "$@"' testlane
It prints the git commands it would run, every variable as an export line and then the command itself. Note that the port it shows is the one worked out from the slug, which is the workspace's own port unless that one was taken when the workspace was created, so list is where to check a port. The lines left out above are the git plan.
Where to go next
Here's where to go from here:
- Environment and templates lists every template variable and
TESTLANE_*variable. - Project file has
ports,base_portand[env]with the rest of the keys. - Use Testlane from an agent shows how
startleaves a server running on its port and hands back its URL.