5d00715c3a
build / build (push) Failing after 7m7s
在 QA 虚拟机通过 Chromium 复跑和本地提交检查,并验证必填校验失效会触发失败。Gitea 将浏览器回归纳入必需检查。
147 lines
10 KiB
Markdown
147 lines
10 KiB
Markdown
# 知识治理平台开发与测试
|
||
|
||
以下命令从仓库根目录运行。日常开发可在 Ubuntu 宿主进行,指定提交的回归在 `hifox-qa` 的独立检出中运行。部署到阿里云测试服后的验收按 [操作 Runbook](OPERATIONS_RUNBOOK.md) 和 [用户流程验收](USER_FLOWS_ACCEPTANCE.md) 执行。
|
||
|
||
## QA 虚拟机一键回归
|
||
|
||
在 `hifox-qa` 检出提测提交后,运行下列入口。将 SHA 占位值换成提测记录里的完整提交 SHA。
|
||
|
||
```bash
|
||
make qa-doctor
|
||
KG_QA_SHA='<完整提交 SHA>' make qa
|
||
```
|
||
|
||
`make qa-doctor` 检查工具链、HiFox 机器在线状态、OMP 模型调用、测试库身份和已安装的迁移。`make qa` 安装锁定依赖,在专用测试库上通过 API 初始化和迁移,随后核对完整迁移序列、API 就绪状态、Web 首页及 Vite 健康代理。通过后执行 Go、Vitest 和 Chromium 浏览器测试,结束时关闭本次启动的服务。每次运行的服务日志保存在 `~/.local/state/knowledge-governance/qa/`。需要提交前完整门禁时执行 `make verify`。
|
||
|
||
初次配置由负责人在 QA 虚拟机准备 `~/.config/knowledge-governance/`。以下示例使用虚构的 RDS 主机名。
|
||
|
||
| 文件 | 内容 |
|
||
| --- | --- |
|
||
| `qa.json` | 当前用户所有、权限 `0600`,字段 `host`、`port`、`database`、`user` |
|
||
| `qa.pgpass` | 当前用户所有、权限 `0600`,填写与 `qa.json` 匹配的口令条目 |
|
||
| `rds-ca.pem` | 对应实例的 CA 证书,用于校验 RDS 主机名 |
|
||
|
||
```json
|
||
{"host":"rds.example.test","port":5432,"database":"kg_qa_app","user":"kg_qa_app"}
|
||
```
|
||
|
||
专用非生产 RDS 库和角色以 `kg_qa_` 开头,权限和网络准备见第 2 节。首次运行接受空库,后续运行接受与当前提交兼容的迁移序列。缺库、认证失败、迁移不兼容和端口冲突均会使命令非零退出。浏览器业务 E2E 和专用集成库的 Go 测试按第 4 节执行。
|
||
|
||
## 1. 检出代码与安装依赖
|
||
|
||
准备 Git、Make、Python 3、Go 1.26(含同一工具链的 `gofmt`)、Node.js 22 和 npm。数据库检查另需 PostgreSQL 客户端 `psql`。首次安装依赖需要能访问 Go 和 npm 的依赖源。
|
||
|
||
```bash
|
||
# QA 在独立克隆中拉取提测分支,使用提测记录里的完整提交 SHA
|
||
export KG_TARGET_BRANCH='<提测分支名>' KG_TARGET_SHA='<完整提交 SHA>'
|
||
git fetch origin "$KG_TARGET_BRANCH" && git switch --detach "$KG_TARGET_SHA" &&
|
||
test "$(git rev-parse HEAD)" = "$KG_TARGET_SHA" && test -z "$(git status --porcelain)"
|
||
# 上面的命令链若失败,先解决检出或工作区问题再继续
|
||
|
||
# 检查当前 shell 的工具链,非交互任务也应设置相同的 PATH
|
||
export PATH="$(go env GOROOT)/bin:$PATH"
|
||
go version
|
||
command -v gofmt
|
||
node --version
|
||
npm --version
|
||
python3 --version
|
||
make deps-install
|
||
```
|
||
|
||
`make deps-install` 通过 `go mod download` 和 `npm ci` 安装依赖。Go 依赖由 `go.mod` / `go.sum` 约束,前端由 `web/package-lock.json` 锁定。依赖安装失败时先检查工具链、依赖源和锁文件,避免临时改写清单来绕过问题。
|
||
|
||
## 2. 准备开发和测试数据库
|
||
|
||
无库检查可直接跳到第 4 节。启动 API 或执行真库测试前,由数据库管理员在**非生产 PostgreSQL RDS** 上预建专用空库和登录角色。建议分配 `kg_qa_app` 给应用冒烟,`kg_qa_it` 给 Go 集成测试,各用独立角色。开发宿主另用开发专用库,避免与 QA 共享数据。库未分配时先申请,启动流程以库已存在为前提。
|
||
|
||
| 用途 | 所需权限 | 数据初始化 |
|
||
| --- | --- | --- |
|
||
| 应用启动与 UI 冒烟 | `CONNECT`,以及目标 schema 内的 `USAGE`、`CREATE` 和对应用对象的读写权限。迁移角色须能修改自己创建的对象。 | 首次 API 启动执行仓库内嵌迁移。用户表为空时创建初始管理员,首次登录必须修改密码。初始口令通过测试环境负责人交接。 |
|
||
| Go PostgreSQL 集成测试 | `CONNECT` 和目标测试库的 `CREATE` 权限,用于建立各用例自己的 schema。 | 用例创建隔离 schema、执行迁移、写入测试数据并清理。相同测试不要并发指向同一个库,避免固定 schema 名冲突。 |
|
||
|
||
两类角色均只授予对应非生产库所需的权限。使用空库和合成数据。密码由操作者在目标机配置到权限为 `0600` 的 PostgreSQL passfile,条目按 `host:port:database:user:password` 填写。使用 RDS CA 校验证书。以下命令先读回实际数据库、角色与 TLS 状态,核对三者再启动 API 或运行真库测试。
|
||
|
||
```bash
|
||
# 用获准的 RDS 主机名、端口、库名、角色和文件路径替换示例值
|
||
export PGHOST='<非生产 RDS 主机名>' PGPORT=5432
|
||
export PGDATABASE=kg_qa_app PGUSER=kg_qa_app
|
||
export PGPASSFILE="$HOME/.config/knowledge-governance/qa.pgpass"
|
||
export PGSSLROOTCERT="$HOME/.config/knowledge-governance/rds-ca.pem"
|
||
export PGSSLMODE=verify-full PGCONNECT_TIMEOUT=5
|
||
psql -X -v ON_ERROR_STOP=1 -c \
|
||
'SELECT current_database(), current_user, ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid();'
|
||
```
|
||
|
||
如果是云厂商提供的私网地址,先确认执行机通过获准的网络路径可访问 RDS。库名、角色、TLS、连接权限或迁移权限有问题时,先交由环境负责人核对配置。实例上已有数据的库不能当作空库初始化。
|
||
|
||
## 3. 启动后端和前端
|
||
|
||
**终端 A,启动 API。** 在干净 shell 中执行第 2 节的应用库配置和连通性检查。使用独立测试配置,不加载现网 `.env`。
|
||
|
||
```bash
|
||
export DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5"
|
||
export APP_ADDR=127.0.0.1:8088
|
||
export TEST_WEKNORA_ENABLED=false PP_SCAN_ENABLED=false
|
||
export RELEASE_WORKER_ENABLED=false PRODUCTION_RELEASE_REQUESTS_ENABLED=false
|
||
export DOBOTAI_OPS_READ_ENABLED=false DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED=false
|
||
go run ./cmd/api
|
||
```
|
||
|
||
API 会在监听前连接 PostgreSQL、应用迁移并初始化管理员。Web 页面和同步 API 联调只需运行 API 与 Vite。需要验证后台队列时,另用相同的隔离应用库配置启动普通 worker(`go run ./cmd/worker`)。涉及取件或来源刷新的任务还依赖容器内 `/app/scripts` 及获准的来源接线,按部署说明准备。发布 worker 无需启动。
|
||
|
||
Vite 通过 `localhost:8088` 转发 `/api` 和健康检查。如果 `8088` 已被其他部署占用,使用端口空闲的 QA 虚拟机运行本节。仅改前端时,可复用一个获准联调的测试 API,但需要先确认 `localhost:8088/health` 可达,并核对该地址指向的环境。
|
||
|
||
**终端 B,启动 Web。**
|
||
|
||
```bash
|
||
npm --prefix web run dev -- --host 127.0.0.1 --port 5173 --strictPort
|
||
```
|
||
|
||
在运行服务的机器打开 `http://127.0.0.1:5173/`。另开终端检查 API 与前端代理,再复查迁移记录。最后一条命令需要第 2 节的应用库配置。
|
||
|
||
```bash
|
||
curl --fail --silent --show-error http://127.0.0.1:8088/health
|
||
curl --fail --silent --show-error http://127.0.0.1:5173/health
|
||
psql -X -v ON_ERROR_STOP=1 -c \
|
||
'SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1;'
|
||
```
|
||
|
||
空库首次启动后,用专用测试账号登录,按当次验收标准验证页面及接口。联调结束在两个终端按 `Ctrl+C` 停服务,数据库由环境管理员按测试数据保留规则管理。
|
||
|
||
## 4. 选择测试命令
|
||
|
||
| 目的 | 命令 |
|
||
| --- | --- |
|
||
| 查看检查及适用范围 | `make list` |
|
||
| 后端包测试 | `make tests-go` |
|
||
| 单个 Go 包及相关子包 | `go test -count=1 ./internal/httpapi/...` |
|
||
| 前端 Vitest 套件 | `make tests-web` |
|
||
| 单个前端测试文件 | `npm --prefix web test -- src/App.test.tsx` |
|
||
| 完整提交前检查,与 CI 共用入口 | `make verify` |
|
||
|
||
`make verify` 包含安装、格式、静态检查、构建、测试、版本和安全检查,并写出 `ci-report.json`。在未导入真库测试配置的 shell 中运行。若检出时用了 `--no-tags`,先执行 `git fetch --tags origin`,以便版本检查读取正式标签对应的提交。依赖安装与安全检查需要相应网络或缓存。允许跳过的外部依赖用例见 [test-scope.json](../scripts/test-scope.json),真库测试应单独执行并记录结果。
|
||
|
||
在应用冒烟之外验证真实 PostgreSQL 行为时,重新按第 2 节切换并核对 **集成测试库和角色**,然后执行目标用例。下面以 UI 设置版本切换用例为例。
|
||
|
||
```bash
|
||
TEST_DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslmode=verify-full&connect_timeout=5" \
|
||
go test -count=1 -v ./internal/platform/postgres -run '^TestUISettingsActivationRetiresPreviousRevisionIntegration$'
|
||
```
|
||
|
||
检查输出出现目标用例的 `PASS`。如果用例被跳过或没有匹配,补齐配置或修正用例名后重跑。提测记录包含完整提交 SHA、执行命令、退出码及失败证据。
|
||
|
||
## 5. 浏览器回归与提交前检查
|
||
|
||
浏览器用例、固定数据和独立 Vite 配置位于 `web/e2e/`,Playwright 版本由前端锁文件固定。第一次运行先执行 `make deps-install`,再在 QA 机的 `web/` 目录用 `npm exec -- playwright install chromium` 下载对应浏览器。已有浏览器缓存时测试本身可以离线运行。
|
||
|
||
```bash
|
||
make tests-e2e
|
||
make tests-e2e E2E=scope-rules.spec.ts
|
||
python3 scripts/test_changed.py --list
|
||
make test-changed
|
||
```
|
||
|
||
`make tests-e2e` 在 `127.0.0.1:4175` 启动夹具页并用 Chromium 检查目录规则。夹具页加载真实 React 编辑器并拦截 API 请求到固定的内存数据。覆盖保存和刷新读回、显示 HTTP 403、展示子目录与兄弟目录各自的继承来源。后端角色权限由 Go 测试覆盖,规则持久化和继承语义由 PostgreSQL 集成测试覆盖。失败截图与 trace 保存在 `web/test-results/`。
|
||
|
||
在独立克隆中可运行 `git config --local core.hooksPath .githooks` 启用仓内提交钩子。钩子先运行可用的全局提交检查,再运行 `make test-changed`。该入口读暂存差异,能定位时只跑修改的测试文件或 Go 包,遇到生产源码或公共依赖改动时扩大到相关套件。对已有仓库自定义钩子的克隆,应在现有钩子中调用 `make test-changed`。`make verify` 继续作为完整提交门禁,Gitea CI 将 Chromium 用例纳入必需检查。本地使用 `make tests-e2e` 直接运行。
|