Skip to main content
The default mode for Node.js web apps that live in a single repository. QLane clones the PR branch, builds your app, runs it in an isolated sandbox, and connects the agent.

​
When to use this mode

  • Your app is one repository (Next.js, Remix, Express, Vite, etc.).
  • It runs with one command — npm run dev, npm start, or similar.
  • You want the agent to test the exact code in the PR, not a separate preview deployment.
If your app needs a database or other services to start, jump to Docker Compose. If you already build per-PR previews on Vercel, Netlify, or Cloudflare, Existing previews is usually a better fit — same coverage, no extra build time.

​
Set it up

From the project page, open Environments → New environment and choose Single repo.
  1. Repository and branch. The branch is the default to test against (typically main). On a PR, QLane uses the PR’s head commit automatically.
  2. Install command. Defaults to npm install. Swap in yarn, pnpm, or bun if needed.
  3. Start command. What boots your app — for example npm run dev or npm start.
  4. Port. The port your app listens on (3000 for most Next.js apps).
  5. Environment variables. Add anything the app needs to boot. Mark sensitive values as secret to redact them from logs.
Save.

​
Enable PR testing

Back on the project page:
  1. Click the PR testing card.
  2. Select the environment you just created as the target.
  3. Toggle it on.
From now on, every pull request triggers a session that uses this environment.

​
What QLane does on each PR

  1. Clones your repo at the PR’s head SHA.
  2. Provisions a fresh, isolated sandbox.
  3. Runs your install command, then the start command.
  4. Waits for the app to come up on the configured port.
  5. Connects the agent and runs your active test cases plus any drafts generated from the PR diff.
  6. Posts a GitHub check and, if anything broke, a structured review.
Typical end-to-end time: under two minutes.

​
What the agent can do in this mode

In addition to a real browser, the agent gets:
  • Shell access inside the sandbox (bash, readFile) — it can inspect logs, check files it wrote, and re-run commands.
  • Code awareness — it reads the repo to understand failures and write better repros.
  • Deep testing — when stuck, the agent can add temporary instrumentation, re-run, and observe. The sandbox is torn down after the session, so changes don’t escape.

​
Common gotchas

  • Native dependencies. Anything that needs a system library should be in your package’s install hooks. The sandbox is Linux-based; macOS-only build steps will fail.
  • Long-running builds. If your dev server takes more than a minute to be ready, set a custom ready check in the environment to a URL or HTTP code the agent should wait for.
  • Required env vars. Your app likely needs an auth secret, database URL, etc. Set them on the environment — without them the app won’t boot and the session will fail before the agent even connects.