NNext.js 中文网 GitHub

测试适配器

使用 Next.js 兼容性测试工具和自定义生命周期脚本来验证适配器。

Next.js 提供了一个用于验证适配器的测试框架,用于运行部署的端到端测试。

GitHub Actions 工作流示例:

.github/workflows/test-e2e-deploy.yml
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 或服务端日志)都应持久化到工作目录内的文件中。

部署脚本示例:

scripts/e2e-deploy.sh
#!/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:

在这些标记之后,日志脚本可以打印任何有助于调试故障的其他构建或服务端日志。

scripts/e2e-logs.sh
#!/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 作为环境变量。

清理脚本可用于清理部署脚本创建的任何资源。它在测试完成后运行。

Next.js 中文网