Unverified Commit 7777dadc authored by Zack Tanner's avatar Zack Tanner Committed by GitHub

docs: add deploy tests documentation to contributing guide (#92388)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## What?

Adds documentation to the contributing guide explaining how deploy tests
work and how to run them.

## Why?

Deploy tests are an important part of the Next.js CI pipeline that
verify the framework works correctly when deployed to Vercel. However,
there was no documentation explaining:
- How deploy tests are triggered on PRs
- How to run deploy tests locally

This came up in a Slack discussion where team members were debugging
deploy test failures and sharing knowledge about how to trigger and run
these tests.

## How?

Added a new "Deploy Tests" section to `contributing/core/testing.md`
that explains:

1. **Triggering Deploy Tests on PRs**: Deploy tests don't run on every
PR by default. To trigger them, you can modify a test file in the deploy
test suite, which causes CI to run deploy tests for that file.

2. **Running Deploy Tests Locally**: You can run deploy tests locally
using:
- `NEXT_TEST_VERSION` to test against a specific commit's pre-built
tarball
- `NEXT_TEST_DEPLOY_URL` to skip the deploy step and test against an
existing deployment

<!-- NEXT_JS_LLM_PR -->
<!-- CURSOR_AGENT_PR_BODY_END -->

[Slack
Thread](https://vercel.slack.com/archives/C04KC8A53T7/p1775265710012189?thread_ts=1775265710.012189&cid=C04KC8A53T7)

<div><a
href="https://cursor.com/agents/bc-014a1052-4dfe-5db4-931d-86efa411016e"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-014a1052-4dfe-5db4-931d-86efa411016e"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------
Co-authored-by: 's avatarCursor Agent <cursoragent@cursor.com>
parent 81d5e070
......@@ -136,6 +136,43 @@ If you want to run a test again both Turbopack and Webpack, use Jest's `--projec
pnpm test-dev test/e2e/app-dir/app/ --projects jest.config.*
```
### Deploy Tests
Deploy tests verify that Next.js works correctly when deployed to Vercel.
These tests are part of the e2e test suite and run against real Vercel deployments.
#### Triggering Deploy Tests on PRs
Deploy tests run automatically on `canary` but are not triggered by default on every PR.
Test files that are modified or created in your PR will have their deploy tests run in CI.
Alternatively, you can manually trigger the deploy test workflow via the
[GitHub Actions UI](https://github.com/vercel/next.js/actions/workflows/test_e2e_deploy_release.yml)
and point it at your branch (this requires passing a custom tarball).
#### Running Deploy Tests Locally
You can run deploy tests locally against a specific commit using the `NEXT_TEST_VERSION` environment variable:
```sh
NEXT_TEST_VERSION=https://vercel-packages.vercel.app/next/commits/<commitSha>/next pnpm test-deploy <path-to-test>
```
For example, to test against commit `abc123`:
```sh
NEXT_TEST_VERSION=https://vercel-packages.vercel.app/next/commits/abc123/next pnpm test-deploy test/e2e/app-dir/actions/
```
This downloads a pre-built Next.js tarball from the specified commit and runs the deploy tests against it.
If you already have a deployment URL and want to skip the Vercel deploy step,
use `NEXT_TEST_DEPLOY_URL` instead:
```sh
NEXT_TEST_DEPLOY_URL=https://your-deployment.vercel.app pnpm test-deploy test/e2e/app-dir/actions/
```
## Integration testing outside the repository with local builds
You can locally generate builds for each package in this repository with:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment