Files
knowledge-governance/docs/DEVELOPMENT_AND_TESTING.md
T
姚章浩 5d00715c3a
build / build (push) Failing after 7m7s
test(qa): 加入目录规则浏览器回归和暂存门禁
在 QA 虚拟机通过 Chromium 复跑和本地提交检查,并验证必填校验失效会触发失败。Gitea 将浏览器回归纳入必需检查。
2026-11-22 19:57:24 +08:00

147 lines
10 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.
# 知识治理平台开发与测试
以下命令从仓库根目录运行。日常开发可在 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` 直接运行。