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: Cursor Agent <[email protected]>

Author: ztanner

contributing/core/testing.md

@@ -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: