Integrations

Vercel

View as Markdown

GitHub remains the event source for Vercel PR testing, but you now need to install the TesterArmy Vercel integration and choose which single Vercel project this TesterArmy project should care about.

Setup

  1. Install the GitHub App
  2. Authorize for your org or user account and select the target repositories.
  3. In your TesterArmy project, choose the installation and repository.
  4. Open Integrations → Vercel.
  5. Click Connect Vercel. This opens the TesterArmy Vercel integration page on Vercel.
  6. Install the integration for the personal account or Vercel team that owns the target project.
  7. Back in TesterArmy, refresh the Vercel project list and select the Vercel project that matches this repository.
  8. Optional: in Integrations → GitHub, choose the PR target branch to allow if you only want automatic runs for one base branch.

TesterArmy detects Vercel preview deployments via GitHub deployment_status events, then verifies that the deployment belongs to the selected Vercel project before any tests are queued.

Why selection is required

One GitHub repository can be connected to multiple Vercel projects.

TesterArmy needs one explicit choice so it can safely ignore deployments from the wrong Vercel project instead of running tests against the wrong preview.

Only deployments from the selected Vercel project will trigger tests.

If a GitHub target branch is configured, the deployment must also belong to a PR targeting that base branch.

Deployment protection bypass

If Vercel deployment protection blocks preview URLs, add a bypass token after you select the Vercel project:

  1. In Vercel: Project Settings → Deployment Protection → Protection Bypass for Automation - create and copy the token.

Vercel Protection Bypass for Automation

  1. In TesterArmy: Project Settings → Integrations → Vercel → paste the token.

The token is applied automatically at the browser-navigation layer for web tests. Navigations to the exact deployment host (the host of the test target URL, whether a *.vercel.app URL or a custom domain attached to the deployment) are rewritten to carry the bypass parameters, and Vercel’s bypass cookie is installed on the first request — so subsequent navigations stay authenticated even when the test agent constructs new URLs. Foreign hosts (third-party scripts, OAuth providers, other Vercel projects) pass through unchanged so the token never leaks off-host.

The saved token is used for any run targeting a deployment URL as long as the token row exists, even if the Vercel OAuth connection is later disconnected — disconnect the integration and clear the bypass token if you want to fully stop using it.

Note: bypass tokens only apply to web tests against Vercel-hosted deployments. Native mobile app testing does not load from a Vercel deployment and ignores the token.

Bypass token missing

If a test opens a Vercel authentication or deployment protection page, add a bypass token under Project Settings → Integrations → Vercel.

Bypass token invalid

If the bypass was added but protection still appears:

  1. Confirm the token is active in Vercel Project Settings → Deployment Protection.
  2. Confirm it belongs to the same Vercel project selected in TesterArmy.
  3. If the token was regenerated, paste the new value into TesterArmy.
  4. Retry the run.

Custom domain bypass

TesterArmy applies the bypass to the exact host of the run target URL. If you test a custom domain, make sure that domain is attached to the protected Vercel deployment and is the URL used by the run.

Native mobile bypass not supported

Vercel bypass tokens only apply to browser-based web tests. Native mobile tests do not load the Vercel deployment URL, so this setting is ignored for mobile app runs.

Status states

  • Connected, no project selected - connect succeeded, but you still need to choose the Vercel project.
  • Active - the selected Vercel project is accessible and used for verification.
  • Requires reconnect - Vercel auth expired or was revoked.
  • Missing access - the selected Vercel project is no longer accessible to the connected Vercel account.

Troubleshooting

No PR comment appears

  1. GitHub App not connected - verify installation in Project Settings.
  2. Permissions - the GitHub App needs Pull requests: Read & Write.
  3. Vercel not selected - connect Vercel and choose the single Vercel project this project should test.
  4. Wrong Vercel project - if the repo is linked to multiple Vercel projects, only the selected one is allowed to trigger tests.