lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
d8e64ef0e97d89adc958d5483585364d63a6737a
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

152 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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