lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
6908b9653be03966447863fd38bd5313524a5056
nex/openspec/specs/ci-test-gate/spec.md
lanyuanxiaoyao 6908b9653b feat: CI check job 扩展为三平台 matrix 并行 lint/test 
将 test.yml 的 check job 从单平台 ubuntu 改为 ubuntu/macos/windows 三平台并行，
Linux 额外安装 libayatana-appindicator3-dev 以支持 systray CGo 编译。
2026-05-07 17:07:55 +08:00

7.5 KiB
Raw Blame History

CI Test Gate

Purpose

定义 CI 全流程测试门禁，作为 release 和未来其他 CI 流程的前序质量检查，覆盖 lint、默认测试、MySQL 测试和 E2E 测试。

Requirements

Requirement: 独立可复用测试 workflow

系统 SHALL 提供独立的全流程测试 workflow（test.yml），使用 workflow_call 触发器，通过 full 布尔参数控制测试分层执行。

Scenario: workflow_call 触发器

  • WHEN 查看 .github/workflows/test.yml 的触发器配置
  • THEN SHALL 使用 on: workflow_call 触发器
  • THEN SHALL 声明 inputs.full 布尔参数，默认值为 false
  • THEN SHALL NOT 使用 push、pull_request 等其他触发器

Scenario: 被其他 workflow 引用（快速模式）

  • WHEN 其他 workflow 的 job 通过 uses: ./.github/workflows/test.yml 引用此 workflow 且未传 full 或传 full: false
  • THEN test workflow SHALL 仅执行 check job（lint + 全量测试）
  • THEN test workflow SHALL NOT 执行 MySQL 测试和 E2E 测试

Scenario: 被其他 workflow 引用（完整模式）

  • WHEN 其他 workflow 的 job 引用此 workflow 且传 full: true
  • THEN test workflow SHALL 执行 check、mysql、e2e 三个 job
  • THEN mysql 和 e2e job SHALL 在 check job 成功后并行执行

Requirement: 全流程测试步骤编排

测试 workflow SHALL 将测试步骤拆分为 check、mysql、e2e 三个独立 job，通过 full 参数和 needs 依赖控制执行。

Scenario: check job（始终执行，三平台 matrix）

  • WHEN 测试 workflow 被调用（无论 full 值）
  • THEN check job SHALL 始终执行
  • THEN check job SHALL 使用 strategy.matrix.os 在 ubuntu-latest、macos-latest、windows-latest 三个平台并行运行
  • THEN 每个平台 SHALL 按顺序执行：checkout（含 LFS）→ setup Go → setup Bun → make lint → make test
  • THEN 在 Linux 平台上，lint/test 之前 SHALL 执行 sudo apt-get install -y libayatana-appindicator3-dev 安装系统依赖
  • THEN macOS 和 Windows 平台 SHALL NOT 安装额外系统依赖
  • THEN make lint SHALL 覆盖 backend golangci-lint、frontend typecheck + eslint + prettier、versionctl golangci-lint
  • THEN make test SHALL 覆盖 backend 核心测试、frontend Vitest 单元/组件测试、desktop 测试和 versionctl 测试
  • THEN make test SHALL NOT 覆盖 MySQL 专项测试或 frontend E2E 测试
  • THEN lint 或测试失败时 SHALL 阻止后续步骤执行
  • THEN 任一平台失败 SHALL 导致 check job 整体失败

Scenario: check job 平台特定依赖安装

  • WHEN check job 在 Linux 平台运行
  • THEN SHALL 在 lint 步骤之前执行系统依赖安装步骤
  • THEN 该步骤 SHALL 使用 if: runner.os == 'Linux' 条件控制
  • THEN 该步骤 SHALL 安装 libayatana-appindicator3-dev

Scenario: check job macOS 平台

  • WHEN check job 在 macOS 平台运行
  • THEN SHALL NOT 安装额外系统依赖
  • THEN make lint 和 make test SHALL 正常执行

Scenario: check job Windows 平台

  • WHEN check job 在 Windows 平台运行
  • THEN SHALL NOT 安装额外系统依赖
  • THEN make lint 和 make test SHALL 正常执行

Scenario: mysql job（仅 full=true）

  • WHEN 测试 workflow 被调用且 full=true，且 check job 成功
  • THEN mysql job SHALL 执行
  • THEN SHALL checkout 仓库代码
  • THEN SHALL 安装 Go 工具链（使用 go.work 文件指定版本，缓存覆盖 backend/go.sum 和 versionctl/go.sum）
  • THEN SHALL 使用 GitHub Actions services: 声明 MySQL 8.0 容器
  • THEN MySQL 容器 SHALL 映射端口 13306:3306
  • THEN MySQL 容器 SHALL 配置 MYSQL_DATABASE=nex_test、MYSQL_USER=nex_test、MYSQL_PASSWORD=testpass
  • THEN SHALL 执行 cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1

Scenario: mysql job 跳过

  • WHEN 测试 workflow 被调用且 full=false
  • THEN mysql job SHALL NOT 执行

Scenario: e2e job（仅 full=true）

  • WHEN 测试 workflow 被调用且 full=true，且 check job 成功
  • THEN e2e job SHALL 执行
  • THEN SHALL checkout 仓库代码（含 LFS）
  • THEN SHALL 安装 Go 工具链（使用 go.work 文件指定版本，缓存覆盖 backend/go.sum 和 versionctl/go.sum）
  • THEN SHALL 安装 Bun 运行时
  • THEN SHALL 安装 Playwright Chromium 浏览器：cd frontend && bunx playwright install --with-deps chromium
  • THEN SHALL 执行 cd frontend && bun run test:e2e
  • THEN Playwright SHALL 使用 CI 模式（forbidOnly: true、retries: 2）

Scenario: e2e job 跳过

  • WHEN 测试 workflow 被调用且 full=false
  • THEN e2e job SHALL NOT 执行

Scenario: mysql 和 e2e 并行执行

  • WHEN full=true 且 check job 成功
  • THEN mysql job 和 e2e job SHALL 并行执行
  • THEN 两个 job 之间 SHALL NOT 有 needs 依赖关系

Scenario: check 失败阻止后续 job

  • WHEN check job 中 lint 或测试任一失败
  • THEN mysql 和 e2e job SHALL NOT 执行

Requirement: 开发 CI 自动触发

系统 SHALL 在 push（dev 和 main 分支）和所有 pull_request 事件时自动触发快速质量检查。

Scenario: push 到 dev 分支触发 CI

  • WHEN 代码推送到 dev 分支
  • THEN SHALL 触发 CI workflow
  • THEN CI workflow SHALL 调用 test.yml（full=false）
  • THEN SHALL 仅执行 lint 和全量单元/集成测试

Scenario: push 到 main 分支触发 CI

  • WHEN 代码推送到 main 分支
  • THEN SHALL 触发 CI workflow
  • THEN CI workflow SHALL 调用 test.yml（full=false）

Scenario: Pull Request 触发 CI

  • WHEN 创建或更新 Pull Request
  • THEN SHALL 触发 CI workflow
  • THEN CI workflow SHALL 调用 test.yml（full=false）

Scenario: CI workflow 极简设计

  • WHEN 查看 .github/workflows/ci.yml
  • THEN SHALL 仅包含触发器配置和一个 job 引用 test.yml
  • THEN SHALL NOT 定义任何直接执行的步骤
  • THEN SHALL NOT 传递 full: true

Requirement: 发布流水线使用完整测试模式

release.yml 调用 test.yml 时 SHALL 显式传递 full: true，确保发布流程执行完整测试。

Scenario: release 调用 test.yml 传 full: true

  • WHEN 发布流水线的 test-gate job 引用 test.yml
  • THEN SHALL 传递 with: full: true
  • THEN 发布流水线 SHALL 执行 check、mysql、e2e 三个 job
  • THEN 测试行为 SHALL 与重构前一致

Requirement: 测试 workflow 工具链依赖

测试 workflow SHALL 在各平台 runner 上准备完整的工具链环境。

Scenario: 工具链安装（三平台）

  • WHEN 测试 workflow 开始执行
  • THEN 每个平台 SHALL checkout 仓库代码并拉取 Git LFS 文件
  • THEN 每个平台 SHALL 安装 Go 工具链（使用 go.work 文件指定版本）
  • THEN 每个平台 SHALL 安装 Bun 运行时
  • THEN Go 模块缓存 SHALL 覆盖 backend/go.sum 和 versionctl/go.sum

Requirement: 测试 workflow 资源隔离

测试 workflow 中的各测试步骤 SHALL 使用隔离的资源，不干扰主环境。

Scenario: E2E 临时资源隔离

  • WHEN E2E 测试运行
  • THEN Go 后端 SHALL 使用临时目录的独立数据库文件（/tmp/nex-e2e/test.db）
  • THEN Go 后端 SHALL 使用临时目录的日志目录（/tmp/nex-e2e/log/）
  • THEN 临时资源 SHALL 在测试结束后自动清理
View Git Blame Copy Permalink