lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
0d30ed9a0fcabad39167865a944d150463386b5a
nex/openspec/specs/ci-test-gate/spec.md
lanyuanxiaoyao 0d30ed9a0f feat: 新增开发 CI 流程，重构 test.yml 支持分层测试 
新增 ci.yml，在 push（dev/main）和 PR 时触发快速检查（lint + 全量测试）
重构 test.yml，新增 full 参数控制是否运行 MySQL 和 E2E 测试
release.yml 调用 test.yml 时传 full: true，行为与重构前一致
同步更新 ci-test-gate spec
2026-05-07 12:43:08 +08:00

6.4 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（始终执行）

  • WHEN 测试 workflow 被调用（无论 full 值）
  • THEN check job SHALL 始终执行
  • THEN SHALL 在 check job 内按顺序执行：checkout（含 LFS）→ setup Go → setup Bun → make lint → make test
  • 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 阻止后续步骤执行

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 在单个 ubuntu 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