nex/openspec/specs/ci-test-gate/spec.md

CI Test Gate

Purpose

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

Requirements

Requirement: 独立可复用测试 workflow

系统 SHALL 提供独立的全流程测试 workflow（test.yml），使用 workflow_call 触发器，可在 release 和其他 CI 场景中被引用。

Scenario: workflow_call 触发器

• WHEN 查看 .github/workflows/test.yml 的触发器配置
• THEN SHALL 使用 on: workflow_call 触发器
• THEN SHALL NOT 使用 push、pull_request 等其他触发器

Scenario: 被其他 workflow 引用

• WHEN 其他 workflow 的 job 通过 uses: ./.github/workflows/test.yml 引用此 workflow
• THEN test workflow SHALL 正常执行所有测试步骤
• THEN 引用方可通过 job 的 needs 依赖等待测试结果

Requirement: 全流程测试步骤编排

测试 workflow SHALL 在单个 ubuntu runner 上按顺序执行完整的测试链：lint → 默认测试 → MySQL 测试 → E2E 测试。

Scenario: Lint 步骤

• WHEN 测试 workflow 执行 lint 步骤
• THEN SHALL 执行 make lint
• THEN lint SHALL 覆盖 backend golangci-lint、frontend typecheck + eslint + prettier、versionctl golangci-lint
• THEN lint 失败时 SHALL 阻止后续步骤执行

Scenario: 默认测试步骤

• WHEN 测试 workflow 执行默认测试步骤
• THEN SHALL 执行 make test
• THEN SHALL 覆盖 backend 核心测试、frontend Vitest 单元/组件测试、desktop 测试和 versionctl 测试
• THEN 默认测试 SHALL NOT 覆盖 MySQL 专项测试或 frontend E2E 测试
• THEN 测试失败时 SHALL 阻止后续步骤执行

Scenario: MySQL 测试步骤

• WHEN 测试 workflow 执行 MySQL 测试步骤
• 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
• THEN MySQL 测试 SHALL 使用默认连接配置（localhost:13306），与 testhelper.go 中的默认值匹配
• THEN 测试失败时 SHALL 阻止后续步骤执行

Scenario: E2E 测试步骤

• WHEN 测试 workflow 执行 E2E 测试步骤
• THEN SHALL 先安装 Playwright Chromium 浏览器：cd frontend && bunx playwright install --with-deps chromium
• THEN SHALL 执行 cd frontend && bun run test:e2e
• THEN E2E 测试 SHALL 自动启动 Go 后端（端口 19026）和 Vite dev server（端口 5173）
• THEN Playwright SHALL 使用 CI 模式（forbidOnly: true、retries: 2）
• 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 在测试结束后自动清理