Testing Adapters

Core Idea

Next.js ships a compatibility test harness that runs the framework's own end-to-end test suite against a deployment built through your adapter, driven by three shell script contracts (deploy, logs, cleanup).

Key Concepts

• NEXT_TEST_DEPLOY_SCRIPT_PATH: env var pointing to the executable that builds and deploys the isolated test app; must print the deployment URL to stdout and exit non-zero on failure.
• NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH: env var pointing to the executable that returns build/runtime logs; output must include BUILD_ID:, DEPLOYMENT_ID:, NEXT_SUPPORTS_IMMUTABLE_ASSETS: marker lines.
• NEXT_TEST_CLEANUP_SCRIPT_PATH: optional executable that tears the deployment down after tests; receives NEXT_TEST_DIR and NEXT_TEST_DEPLOY_URL.
• NEXT_TEST_MODE=deploy: env var that switches the Next.js test runner (run-tests.js) into adapter/deploy testing mode.

Code Examples

- name: Run deploy tests
  working-directory: nextjs
  env:
    NEXT_TEST_MODE: deploy
    NEXT_E2E_TEST_TIMEOUT: 240000
    NEXT_EXTERNAL_TESTS_FILTERS: test/deploy-tests-manifest.json
    ADAPTER_DIR: ${{ github.workspace }}/adapter
    NEXT_TEST_DEPLOY_SCRIPT_PATH: ${{ github.workspace }}/adapter/scripts/e2e-deploy.sh
    NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH: ${{ github.workspace }}/adapter/scripts/e2e-logs.sh
    NEXT_TEST_CLEANUP_SCRIPT_PATH: ${{ github.workspace }}/adapter/scripts/e2e-cleanup.sh
  run: node run-tests.js --timings -g ${{ matrix.group }} -c 2 --type e2e

#!/usr/bin/env bash
set -euo pipefail
export NEXT_ADAPTER_PATH="${ADAPTER_DIR}/dist/index.js"
pnpm build

BUILD_ID="$(cat .next/BUILD_ID)"
DEPLOYMENT_ID="my-adapter-local"
NEXT_SUPPORTS_IMMUTABLE_ASSETS="0"
{
  echo "BUILD_ID: $BUILD_ID"
  echo "DEPLOYMENT_ID: $DEPLOYMENT_ID"
  echo "NEXT_SUPPORTS_IMMUTABLE_ASSETS: $NEXT_SUPPORTS_IMMUTABLE_ASSETS"
} >> .adapter-build.log

provider-cli-to-deploy
# echo "http://127.0.0.1:3000"   # deployment URL to stdout

#!/usr/bin/env bash
set -euo pipefail
if [ -f ".adapter-build.log" ]; then cat ".adapter-build.log"; fi
if [ -f ".adapter-server.log" ]; then echo "=== .adapter-server.log ==="; cat ".adapter-server.log"; fi

• O que demonstra: contrato completo de deploy/log/cleanup scripts usados pelo harness de teste oficial do Next.js, incluindo o padrão de persistir metadados em arquivo entre processos separados.

Reference Tables

Script	Required behavior
Deploy	cwd = isolated test app; non-zero exit on failure; deployment URL on stdout only; diagnostics to stderr/files
Logs	Must emit BUILD_ID:, DEPLOYMENT_ID:, NEXT_SUPPORTS_IMMUTABLE_ASSETS: lines, optionally followed by extra logs
Cleanup	Tears down deployment; runs after tests complete

Anti-patterns

• Writing extra output to stdout in the deploy script: the harness treats stdout as the deployment URL only; anything else must go to stderr or files.
• Not persisting build metadata to files: deploy and logs scripts run as separate processes, so in-memory state (build ID, etc.) is lost unless written to disk.

Key Takeaways

1. Three env-var-driven scripts (deploy/logs/cleanup) are the entire integration surface for running Next.js's official e2e suite against a custom adapter.
2. The deploy script's only contract on stdout is the deployment URL; everything else is diagnostic noise that must be redirected.
3. A common pattern: deploy script writes .adapter-build.log/.adapter-server.log, logs script just replays them.

Connects To

• ch282 supporting-immutable-static-assets: the NEXT_SUPPORTS_IMMUTABLE_ASSETS marker referenced by the logs script.