Running e2e in GitLab CI/CD

A Next.js App Router greeting app whose e2e tests run in every merge request and on every push to main. It has three locator tests and two agent tests.

The pipeline

.gitlab-ci.yml was written by npx e2e init --ci gitlab. Its e2e job runs in the node:24 image. On each run it:

1. Installs dependencies with npm ci.
2. Restores the npm cache and Chromium from the GitLab cache, or installs Chromium with npx e2e-web install chromium --with-deps.
3. Runs npx e2e run --reporter list,junit. The app starts on its own.
4. Keeps .e2e/report.json, .e2e/junit.xml, and .e2e/results/ as job artifacts, even when tests fail. They are kept for 7 days.

The JUnit report shows the results in the merge request and on the pipeline's Tests tab. A new push to a merge request cancels the job still running for it.

Agent tests in CI

Add a Vercel AI Gateway key as a CI/CD variable named AI_GATEWAY_API_KEY (Settings → CI/CD → Variables), with the visibility Masked and hidden. Clear Protect variable, so merge request pipelines get it too. Or use glab:

glab variable set AI_GATEWAY_API_KEY --masked --hidden --raw

Without the variable, the agent tests skip and the locator tests still run. Merge requests from forks run in the fork's project, without your variables.

Run locally

Use Node 22.22.3+, 24.8+, or 26+. From this folder:

npm install
AI_GATEWAY_API_KEY="your-key" npm run test:e2e

The runner starts the app at http://localhost:3100 and downloads Chromium on the first run if needed. Leave out the key to run only the locator tests. Add -- --no-cache to use fresh model calls. Results are in .e2e/report.json.

See e2e.config.ts and tests/ for the setup. For your own project, follow the CI guide.

License

MIT

Last checked with e2e 0.23.0, @e2e-dev/web 0.15.5, Next.js 16.4, and Node 24.