测试适配器
使用 Next.js 兼容性测试框架和自定义生命周期脚本来验证适配器。
Next.js 提供了一个用于验证适配器的测试框架,用于运行部署的端到端测试。
GitHub Actions 工作流示例:
name: test-e2e-deploy
on:
workflow_dispatch:
inputs:
nextjsRef:
description: 'Next.js repo ref (branch/tag/SHA)'
default: 'canary'
type: string
# schedule:
# - cron: '0 2 * * *'
jobs:
build:
name: Build Next.js + adapter
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
with:
path: adapter
- uses: actions/checkout@v4
with:
repository: vercel/next.js
ref: ${{ inputs.nextjsRef || 'canary' }}
path: nextjs
fetch-depth: 25
- uses: actions/setup-node@v4
with: { node-version: '20' }
- name: Setup pnpm
run: npm i -g corepack@0.31 && corepack enable
- name: Install & build Next.js
working-directory: nextjs
run: pnpm install && pnpm build && pnpm install
- name: Install Playwright
working-directory: nextjs
run: pnpm playwright install --with-deps chromium
- name: Build adapter
working-directory: adapter
run: pnpm install && pnpm build
- uses: actions/cache/save@v4
with:
path: |
nextjs
adapter
~/.cache/ms-playwright
key: build-${{ github.sha }}-${{ github.run_id }}
test:
name: Tests (${{ matrix.group }})
needs: build
runs-on: ubuntu-latest
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
group:
[
1/16,
2/16,
3/16,
4/16,
5/16,
6/16,
7/16,
8/16,
9/16,
10/16,
11/16,
12/16,
13/16,
14/16,
15/16,
16/16,
]
steps:
- uses: actions/cache/restore@v4
with:
path: |
nextjs
adapter
~/.cache/ms-playwright
key: build-${{ github.sha }}-${{ github.run_id }}
- uses: actions/setup-node@v4
with: { node-version: '20' }
- name: Setup pnpm
run: npm i -g corepack@0.31 && corepack enable
- name: Ensure Playwright browser
working-directory: nextjs
run: pnpm playwright install chromium
- name: Make scripts executable
run: chmod +x adapter/scripts/e2e-deploy.sh
adapter/scripts/e2e-logs.sh
adapter/scripts/e2e-cleanup.sh
- 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
IS_TURBOPACK_TEST: 1
NEXT_TEST_JOB: 1
NEXT_TELEMETRY_DISABLED: 1
# 将这些更改为你的适配器脚本
# 如果脚本位于适配器仓库的 `scripts` 目录中,则保持原样
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
- name: Save test results
if: always()
uses: actions/upload-artifact@v4
with:
name: adapter-test-results-${{ strategy.job-index }}
path: '**/*.results.json'
retention-days: 1
upload-results:
name: Report results to nextjs.org
needs: test
if: always()
runs-on: ubuntu-latest
permissions:
contents: read
# 生成 GitHub OIDC 令牌以对结果上传进行身份验证。
id-token: write
steps:
- uses: actions/checkout@v4
with:
repository: vercel/next.js
ref: ${{ inputs.nextjsRef || 'canary' }}
path: nextjs
- uses: actions/setup-node@v4
with: { node-version: '20' }
- uses: actions/download-artifact@v4
with:
pattern: adapter-test-results-*
path: adapter-test-results
merge-multiple: true
- name: Upload adapter test results
working-directory: nextjs
run: node scripts/upload-adapter-test-results.mjs --results-root ../adapter-test-results将结果上报到 nextjs.org#
上面的 upload-results 作业会将你的结果发送到适配器测试结果端点,该端点为按提供商划分的适配器支持矩阵提供数据。
上传过程使用 GitHub Actions OIDC 令牌进行身份验证,因此需要上面所示的 id-token: write 权限。不会签发或存储任何密钥:提供商名称和提交 SHA 均从令牌声明中派生,这意味着结果只能归属于生成它们的代码仓库和工作流。
上榜方式: 该矩阵对 Ecosystem Working Group 中的适配器开放。有关已验证适配器和工作组如何运作,请参阅部署到平台。你的仓库和工作流会在该过程中完成注册。你的结果将在下一次工作流运行后出现在矩阵中。在此之前,上传会返回 403 Forbidden。
测试框架会查找以下环境变量:
NEXT_TEST_DEPLOY_SCRIPT_PATH:用于构建和部署隔离测试应用的可执行文件路径NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH:用于返回该部署的构建和运行时日志的可执行文件路径NEXT_TEST_CLEANUP_SCRIPT_PATH:可选的可执行文件路径,用于在测试运行后拆除部署
自定义部署脚本契约#
部署脚本 NEXT_TEST_DEPLOY_SCRIPT_PATH 执行时,cwd 会被设置为 Next.js 测试框架创建的隔离临时应用目录。
部署脚本必须遵循以下契约:
- 失败时以非零退出码退出。
- 将部署 URL 打印到
stdout。该 URL 将用于验证部署。请勿向stdout写入其他任何内容。 - 将诊断输出写入
stderr或工作目录内的文件中。
由于部署脚本和日志脚本作为独立进程运行,任何你之后要使用的数据(如构建 ID 或服务端日志)都应持久化到工作目录内的文件中。
部署脚本示例:
#!/usr/bin/env bash
set -euo pipefail
# 安装适配器、构建应用,然后部署或启动它。
node -e "
const pkg=JSON.parse(require('fs').readFileSync('package.json','utf8'));
pkg.dependencies=pkg.dependencies||{};
pkg.dependencies['adapter']='file:${ADAPTER_DIR}';
require('fs').writeFileSync('package.json',JSON.stringify(pkg,null,2));
" >&2
# 设置适配器路径,以便应用使用它。
export NEXT_ADAPTER_PATH="${ADAPTER_DIR}/dist/index.js"
# 构建应用
pnpm build
# 将之后需要的任何元数据写入工作目录中的文件。
BUILD_ID="$(cat .next/BUILD_ID)"
DEPLOYMENT_ID="my-adapter-local"
# 如果你的适配器启用了不可变静态资源,请将其设置为 "1"。
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
# 启动或部署应用。此时捕获 URL,或让脚本将 URL 输出到 stdout。
provider-cli-to-deploy
# URL 输出示例:
# echo "http://127.0.0.1:3000"自定义日志脚本契约#
日志脚本 NEXT_TEST_DEPLOY_LOGS_SCRIPT_PATH 执行时,cwd 会被设置为 Next.js 测试框架创建的隔离临时应用目录。
此外,它还会接收 NEXT_TEST_DIR 和 NEXT_TEST_DEPLOY_URL 作为环境变量。
其输出必须包含以下列开头的行:
BUILD_ID:DEPLOYMENT_ID:NEXT_SUPPORTS_IMMUTABLE_ASSETS:
在这些标记之后,日志脚本可以打印任何有助于调试故障的其他构建或服务端日志。
#!/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一种模式是让部署脚本写入 .adapter-build.log 和 .adapter-server.log,然后让日志脚本重放这些文件,以便测试框架提取所需的标记。这只是一种方案,每个平台获取日志的方式各不相同。
自定义清理脚本契约#
清理脚本 NEXT_TEST_CLEANUP_SCRIPT_PATH 执行时,cwd 会被设置为 Next.js 测试框架创建的隔离临时应用目录。
此外,它还会接收 NEXT_TEST_DIR 和 NEXT_TEST_DEPLOY_URL 作为环境变量。
清理脚本可用于清理部署脚本创建的任何资源。它在测试完成后运行。