Testing Adapters

Core Idea

Next.js provides an end-to-end test harness for validating deployment adapters, driven by three custom scripts (deploy, logs, cleanup) invoked from a GitHub Actions workflow against a real (or local) deployment.

Key Concepts

• NEXT_TEST_DEPLOY_SCRIPT_PATH: executable that builds and deploys the isolated test app; must print the deployment URL to stdout (nothing else) and exit non-zero on failure.
• NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH: executable returning build/runtime logs; output must include lines starting with BUILD_ID:, DEPLOYMENT_ID:, NEXT_SUPPORTS_IMMUTABLE_ASSETS:.
• NEXT_TEST_CLEANUP_SCRIPT_PATH: optional executable to tear down the deployment after tests.
• Env passed to logs/cleanup scripts: NEXT_TEST_DIR, NEXT_TEST_DEPLOY_URL.
• Test runner invocation: node run-tests.js --timings -g <group> -c 2 --type e2e with NEXT_TEST_MODE: deploy and NEXT_EXTERNAL_TESTS_FILTERS: test/deploy-tests-manifest.json.

Code Examples

#!/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"

• O que demonstra: contrato do script de deploy: builda com o adapter apontado via NEXT_ADAPTER_PATH, persiste metadata em arquivo (porque deploy/logs rodam em processos separados), e imprime só a URL no 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: padrão de replay dos arquivos de log gravados pelo script de deploy.

Anti-patterns

• Escrever qualquer coisa além da URL no stdout do script de deploy: quebra a extração da URL pelo harness.
• Passar dados entre deploy script e logs script via variáveis de processo: eles rodam como processos separados; persista em arquivos no working directory.

Key Takeaways

1. O harness roda testes em paralelo via matriz de grupos (ex. 1/16 até 16/16).
2. Deploy script deve setar NEXT_ADAPTER_PATH apontando pro build do próprio adapter (file: dependency).
3. Testes usam Playwright + Chromium, cacheados entre jobs de build e teste.

Connects To

• Configuration (ch434): NEXT_ADAPTER_PATH é o mesmo mecanismo usado no script de deploy de teste.