diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index abe0b4f..069e3c1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -37,9 +37,14 @@ jobs: go run ./versionctl verify-tag "${GITHUB_REF_NAME}" printf 'version=%s\n' "$version" >> "$GITHUB_OUTPUT" + test-gate: + name: Test Gate + needs: prepare + uses: ./.github/workflows/test.yml + build-web: name: Build Web Asset - needs: prepare + needs: [prepare, test-gate] runs-on: ubuntu-latest permissions: contents: read @@ -81,7 +86,7 @@ jobs: build-linux: name: Build Linux ${{ matrix.arch }} Assets - needs: prepare + needs: [prepare, test-gate] strategy: fail-fast: false matrix: @@ -147,7 +152,7 @@ jobs: build-windows: name: Build Windows ${{ matrix.arch }} Assets - needs: prepare + needs: [prepare, test-gate] runs-on: ${{ matrix.runner }} strategy: fail-fast: false @@ -231,7 +236,7 @@ jobs: build-macos: name: Build macOS Assets - needs: prepare + needs: [prepare, test-gate] runs-on: macos-15 permissions: contents: read diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml new file mode 100644 index 0000000..acb3cde --- /dev/null +++ b/.github/workflows/test.yml @@ -0,0 +1,60 @@ +name: Test (Full) + +on: + workflow_call: + +permissions: + contents: read + +jobs: + test-gate: + name: Test Gate + runs-on: ubuntu-latest + + services: + mysql: + image: mysql:8.0 + env: + MYSQL_ROOT_PASSWORD: testpass + MYSQL_DATABASE: nex_test + MYSQL_USER: nex_test + MYSQL_PASSWORD: testpass + ports: + - 13306:3306 + options: >- + --health-cmd="mysqladmin ping -h localhost -u root -ptestpass" + --health-interval=3s + --health-timeout=5s + --health-retries=10 + + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + lfs: true + + - name: Setup Go + uses: actions/setup-go@v6 + with: + go-version-file: go.work + cache-dependency-path: | + backend/go.sum + versionctl/go.sum + + - name: Setup Bun + uses: oven-sh/setup-bun@v2 + + - name: Lint + run: make lint + + - name: Test + run: make test + + - name: MySQL tests + run: cd backend && go test -tags=mysql ./tests/mysql/... -v -count=1 + + - name: Install Playwright browsers + run: cd frontend && bunx playwright install --with-deps chromium + + - name: E2E tests + run: cd frontend && bun run test:e2e diff --git a/README.md b/README.md index 6ca7f46..9d063ad 100644 --- a/README.md +++ b/README.md @@ -159,7 +159,7 @@ make server-build ### Release 产物 -发布流程由 Git tag `vX.Y.Z` 触发,GitHub Actions 会创建 Draft Release 并上传 server、web 和 desktop 三类产物,同时生成 `SHA256SUMS`。 +发布流程由 Git tag `vX.Y.Z` 触发,GitHub Actions 会先通过全流程测试门禁,再构建并创建 Draft Release,上传 server、web 和 desktop 三类产物,同时生成 `SHA256SUMS`。 **server 产物**(不内置 Web 管理界面): @@ -418,9 +418,10 @@ make release-assets-macos ### GitHub Draft Release - 推送 `vX.Y.Z` tag 后,`.github/workflows/release.yml` 会自动执行发布流水线 -- 三个平台 job 会在正式构建前先检查 `go`、`bun` 和各自的平台打包工具链,缺失时快速失败并在日志中输出诊断信息 +- 流水线会先校验 tag 与 `VERSION` 一致,再执行全流程测试门禁(lint、默认测试、MySQL 测试、E2E 测试),测试不通过则阻止构建 +- 测试通过后,三个平台 job 并行构建,各 job 会在正式构建前先检查 `go`、`bun` 和各自的平台打包工具链,缺失时快速失败并在日志中输出诊断信息 - Windows 发布 job 在 `MSYS2 / MINGW64` shell 中执行,并继承 `setup-go` / `setup-bun` 准备好的工具链路径 -- 流水线会先校验 tag 与 `VERSION` 一致,再构建以下资产并上传到 GitHub Draft Release: +- 构建以下资产并上传到 GitHub Draft Release: - Linux server - Windows server - darwin-amd64 server diff --git a/openspec/specs/ci-test-gate/spec.md b/openspec/specs/ci-test-gate/spec.md new file mode 100644 index 0000000..a5c4eca --- /dev/null +++ b/openspec/specs/ci-test-gate/spec.md @@ -0,0 +1,84 @@ +# 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 在测试结束后自动清理 diff --git a/openspec/specs/release-pipeline/spec.md b/openspec/specs/release-pipeline/spec.md index f7674d7..363bdd6 100644 --- a/openspec/specs/release-pipeline/spec.md +++ b/openspec/specs/release-pipeline/spec.md @@ -8,12 +8,12 @@ ### Requirement: Tag 驱动发布流水线 -系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线,普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。 +系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线,普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。发布流水线 SHALL 在进入构建阶段前完成全流程测试验证,测试未通过 SHALL NOT 执行任何构建。 #### Scenario: 有效发布 tag - **WHEN** 仓库收到 `v1.2.3` tag push -- **THEN** 发布流水线 SHALL 启动版本校验、构建和 Release 组装步骤 +- **THEN** 发布流水线 SHALL 启动版本校验、全流程测试、构建和 Release 组装步骤 - **AND** 版本校验步骤 SHALL 使用 `go run ./versionctl print` 和 `go run ./versionctl verify-tag` 获取并验证版本 #### Scenario: 普通分支推送 @@ -21,6 +21,19 @@ - **WHEN** 仓库收到非 tag 的分支 push - **THEN** 系统 SHALL NOT 创建 GitHub Release +#### Scenario: 测试门禁阻止构建 + +- **WHEN** 发布流水线中全流程测试步骤(lint、默认测试、MySQL 测试、E2E 测试)任一失败 +- **THEN** 发布流水线 SHALL NOT 执行任何平台构建 +- **THEN** 发布流水线 SHALL NOT 创建 Draft Release +- **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果 + +#### Scenario: 测试通过后并行构建 + +- **WHEN** 全流程测试全部通过 +- **THEN** web、Linux、Windows、macOS 构建 SHALL 并行执行 +- **AND** 所有构建 job SHALL 依赖 `prepare` 和 `test-gate` + ### Requirement: 发布流水线 Go 模块缓存覆盖 发布流水线 SHALL 在所有 Go module 的 go.sum 文件存在时正确设置 Go 模块缓存路径,确保新增的 `versionctl` module 依赖也被缓存。 @@ -198,7 +211,7 @@ #### Scenario: 发布成功时创建 Draft Release -- **WHEN** 版本校验通过且 server、web、desktop 的全部目标发布资产构建完成 +- **WHEN** 版本校验通过、全流程测试通过且 server、web、desktop 的全部目标发布资产构建完成 - **THEN** 系统 SHALL 创建或更新与该 tag 对应的 GitHub Draft Release - **AND** 系统 SHALL 上传 server、web 与 desktop 的全部发布资产 - **AND** 系统 SHALL 上传 `SHA256SUMS` @@ -211,7 +224,7 @@ #### Scenario: 构建失败时阻止完成发布 -- **WHEN** 任一目标发布资产构建失败、打包失败、校验失败、artifact 上传为空或版本校验失败 +- **WHEN** 任一目标发布资产构建失败、打包失败、校验失败、artifact 上传为空、版本校验失败或全流程测试失败 - **THEN** 发布流水线 SHALL 失败 - **AND** 系统 SHALL NOT 产生可直接公开的成功发布结果