Compare commits

..

4 Commits

Author SHA1 Message Date
姚章浩 ad86bf93be ci(qa): 用签名镜像安装浏览器依赖
build / build (push) Has started running
首轮 CI 在 Ubuntu 系统依赖下载和配置阶段超时。临时 CI 容器通过隔离的 APT 镜像配置完成安装并通过 Chromium DOM 冒烟。
2026-11-22 20:05:53 +08:00
姚章浩 5d00715c3a test(qa): 加入目录规则浏览器回归和暂存门禁
build / build (push) Failing after 7m7s
在 QA 虚拟机通过 Chromium 复跑和本地提交检查,并验证必填校验失效会触发失败。Gitea 将浏览器回归纳入必需检查。
2026-11-22 19:57:24 +08:00
zheromiku d7d636792d Merge pull request 'feat(qa): 自动准备知识治理测试环境' (#18) from feat/qa-environment-runner into main
build / build (push) Successful in 1m28s
2026-11-22 19:37:29 +08:00
姚章浩 89c484cdc4 feat(qa): 自动准备知识治理测试环境
build / build (push) Successful in 1m29s
为 HiFox QA 检出提供环境检查、锁定依赖、专用 RDS 迁移、服务探活、测试和进程清理。已在 QA 虚拟机通过 make verify,并验证缺少 RDS 配置、错误提交和端口冲突的阻断。
2026-11-22 19:30:49 +08:00
20 changed files with 935 additions and 3 deletions
+10
View File
@@ -0,0 +1,10 @@
#!/bin/sh
set -eu
# Keep the configured global checks when this checkout opts into repository hooks.
global_hooks=$(git config --global --path --get core.hooksPath || :)
if [ -n "$global_hooks" ] && [ -x "$global_hooks/pre-commit" ] &&
[ ! "$global_hooks/pre-commit" -ef "$0" ]; then
"$global_hooks/pre-commit"
fi
exec make test-changed
+2
View File
@@ -6,6 +6,8 @@
/web/node_modules/
/web/dist/
/web/tsconfig.tsbuildinfo
/web/test-results/
/web/playwright-report/
# Local runtime
.env
+21
View File
@@ -27,6 +27,27 @@ BUILD_TIME ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
verify:
$(PY) scripts/ci_checks.py
.PHONY: qa qa-doctor qa-self-test tests-e2e tests-e2e-ci test-changed test-tooling
tests-e2e:
npm --prefix web run test:e2e -- $(E2E)
# The hosted CI job container is disposable and starts without Chromium's system libraries.
tests-e2e-ci: export PLAYWRIGHT_BROWSERS_PATH ?= /opt/citools-cache/playwright
tests-e2e-ci:
sh scripts/ci_install_chromium.sh
$(MAKE) tests-e2e
test-changed:
$(PY) scripts/test_changed.py
test-tooling: qa-self-test
$(PY) -m unittest discover -s scripts -p test_test_changed.py -v
qa:
$(PY) scripts/qa_env.py run
qa-doctor:
$(PY) scripts/qa_env.py doctor
qa-self-test:
$(PY) -m unittest discover -s scripts -p test_qa_env.py -v
# 清单:哪些是必需项、在哪个档案(local / ci)下必需
list:
$(PY) scripts/ci_checks.py --list
+41 -1
View File
@@ -2,6 +2,31 @@
以下命令从仓库根目录运行。日常开发可在 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 的依赖源。
@@ -103,4 +128,19 @@ TEST_DATABASE_URL="postgresql://${PGUSER}@${PGHOST}:${PGPORT}/${PGDATABASE}?sslm
go test -count=1 -v ./internal/platform/postgres -run '^TestUISettingsActivationRetiresPreviousRevisionIntegration$'
```
检查输出出现目标用例的 `PASS`。用例被跳过或没有匹配时,应补齐配置或纠正用例名后重跑。前端 Vitest 负责组件与业务逻辑检查,浏览器 E2E 应单独执行并按 Feature 保存证据。提测记录至少包括完整提交 SHA、执行命令、退出码,以及失败用例的日志或浏览器截图。
检查输出出现目标用例的 `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` 直接运行。
+13
View File
@@ -241,6 +241,16 @@ func TestAuthRBACMatrix(t *testing.T) {
t.Fatalf("viewer write = %d", rec.Code)
}
for _, method := range []string{http.MethodPut, http.MethodDelete} {
result := httptest.NewRecorder()
request := httptest.NewRequest(method, "/api/v1/scope-rules", nil)
request.AddCookie(viewer)
handler.ServeHTTP(result, request)
if result.Code != http.StatusForbidden {
t.Fatalf("viewer %s scope rules = %d, want %d", method, result.Code, http.StatusForbidden)
}
}
// engineer may create batches but not authorize production
rec = httptest.NewRecorder()
req = httptest.NewRequest(http.MethodPost, "/api/v1/release-change-sets", strings.NewReader(`{"name":"x"}`))
@@ -417,6 +427,9 @@ func TestClassifyRoleMatrix(t *testing.T) {
http.MethodPost + " /api/v1/release-batches/rb-1/seal": roleEngineer,
http.MethodPost + " /api/v1/test-publications/start": roleEngineer,
http.MethodGet + " /api/v1/release-plan": roleViewer,
http.MethodGet + " /api/v1/scope-rules": roleViewer,
http.MethodPut + " /api/v1/scope-rules": roleEngineer,
http.MethodDelete + " /api/v1/scope-rules": roleEngineer,
}
for key, want := range cases {
fields := strings.Fields(key)
+14
View File
@@ -249,6 +249,8 @@ def checks() -> list[Check]:
[g, "test", "-count=1", "-json", "./..."], env=env, judge=judge_go_tests),
Check("tests-web", "前端测试(vitest,必须真跑)",
[py3, "scripts/ci_checks.py", "--internal-web-test"], env=env),
Check("tests-e2e", "Chromium 浏览器回归(CI 必需)", ["make", "tests-e2e-ci"],
env=env, required_in=("ci",), note="本地用 make tests-e2e,复用已安装的浏览器"),
Check("contracts", "版本与变更记录契约(不许 SKIP;开发构建不许自称正式版)",
[py3, "scripts/ci_checks.py", "--internal-contracts", g], env=env),
Check("version", "CHANGELOG 与版本记录(四类小节无空栏目 + 正式 tag 与提交内版本一致)",
@@ -356,6 +358,9 @@ def cmd_internal_web_test() -> int:
def cmd_internal_contracts(go: str) -> int:
"""版本契约:结构 + 注入身份必须**真 PASS**(SKIP 判红),
并且**开发构建不许自称正式版**(负例:标成 release ⇒ 必须红)。"""
qa_rc = subprocess.run(["make", "test-tooling"], cwd=ROOT).returncode
if qa_rc:
return qa_rc
snapshot_rc = subprocess.run(py("scripts/development_snapshot.py","--self-test"),cwd=ROOT).returncode
if snapshot_rc:
return 1
@@ -438,6 +443,7 @@ CHECK_MANIFEST: dict[str, tuple[str, ...]] = {
"build-web": ("local", "ci"),
"tests-go": ("local", "ci"),
"tests-web": ("local", "ci"),
"tests-e2e": ("ci",),
"contracts": ("local", "ci"),
"version": ("local", "ci"),
"security-secrets": ("local", "ci"),
@@ -631,6 +637,14 @@ def main(argv: list[str]) -> int:
print(f"\n── [{c.id}] {c.title} ──\n {'✅' if status == SUCCESS else ('⏭️' if status == SKIPPED else '❌')} {reason}")
continue
if args.profile not in c.required_in:
reason = f"{args.profile} 档案不要求此项。{c.note}".strip()
results.append({"id": c.id, "title": c.title, "required_in": list(c.required_in),
"status": SKIPPED, "reason": reason, "command": "",
"exit_code": None, "duration_s": 0})
print(f"\n── [{c.id}] {c.title} ──\n ⏭️ {reason}")
continue
print(f"\n── [{c.id}] {c.title} ──")
print(" $ " + " ".join(c.argv))
t0 = time.time()
+25
View File
@@ -0,0 +1,25 @@
#!/bin/sh
set -eu
if [ ! -f /.dockerenv ]; then
printf '%s\n' 'Chromium provisioning requires the disposable CI container. Use make tests-e2e here.' >&2
exit 1
fi
# Scope mirror settings to this command, keeping the runner image and its apt sources intact.
. /etc/os-release
if [ "$ID:$VERSION_CODENAME" != ubuntu:noble ]; then
printf '%s\n' 'Chromium provisioning expects Ubuntu 24.04.' >&2
exit 1
fi
apt_scope=$(mktemp -d)
trap 'rm -f "$apt_scope/ubuntu.list" "$apt_scope/apt.conf"; rmdir "$apt_scope"' EXIT
mirror=https://mirrors.aliyun.com/ubuntu/
for suite in noble noble-updates noble-security; do
printf 'deb [signed-by=/usr/share/keyrings/ubuntu-archive-keyring.gpg] %s %s main universe\n' "$mirror" "$suite"
done > "$apt_scope/ubuntu.list"
printf 'Dir::Etc::sourcelist "%s/ubuntu.list";\nDir::Etc::sourceparts "-";\nAcquire::Retries "2";\nAcquire::https::Timeout "15";\n' "$apt_scope" > "$apt_scope/apt.conf"
export APT_CONFIG="$apt_scope/apt.conf"
export DEBIAN_FRONTEND=noninteractive
export PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=90000
timeout 360s npm --prefix web exec -- playwright install --with-deps --only-shell chromium
+374
View File
@@ -0,0 +1,374 @@
#!/usr/bin/env python3
"""Prepare and exercise an isolated Knowledge Governance QA run."""
import argparse
from contextlib import ExitStack
import fcntl
import http.client
import json
import os
from pathlib import Path
import re
import shutil
import signal
import socket
import stat
import subprocess
import sys
import tempfile
import time
ROOT = Path(__file__).resolve().parents[1]
CONFIG = Path.home() / '.config/knowledge-governance/qa.json'
API_PORT = 8088
WEB_PORT = 5173
RUNTIME_RESPONSE = 'KG_QA_RUNTIME_OK'
class QAError(RuntimeError):
pass
def report(stage, detail):
print(f'[qa:{stage}] {detail}', flush=True)
def capture(argv, stage, timeout=10, env=None):
try:
return subprocess.run(argv, cwd=ROOT, env=env, text=True, capture_output=True,
timeout=timeout, stdin=subprocess.DEVNULL)
except FileNotFoundError as exc:
raise QAError(f'{stage} 缺少命令 {argv[0]}') from exc
except subprocess.TimeoutExpired as exc:
raise QAError(f'{stage} 超过 {timeout} 秒') from exc
def private_file(path):
try:
info = path.lstat()
except FileNotFoundError as exc:
raise QAError(f'缺少测试配置文件 {path}') from exc
if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) != 0o600:
raise QAError(f'{path} 必须是当前用户所有的 0600 普通文件')
def database_config(path):
private_file(path)
try:
config = json.loads(path.read_text())
except (UnicodeError, json.JSONDecodeError) as exc:
raise QAError(f'{path} 不是有效 JSON') from exc
if not isinstance(config, dict) or config.keys() != {'host', 'port', 'database', 'user'}:
raise QAError('qa.json 只接受 host、port、database、user 四个字段')
for field in ('database', 'user'):
if not re.fullmatch(r'kg_qa_[a-z0-9_]{1,56}', str(config[field])):
raise QAError(f'RDS {field} 必须以 kg_qa_ 开头并使用小写字母、数字或下划线')
host = config['host']
if not isinstance(host, str) or not re.fullmatch(r'[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+', host):
raise QAError('RDS host 必须填写证书对应的 DNS 主机名')
if type(config['port']) is not int or not 1 <= config['port'] <= 65535:
raise QAError('RDS port 必须是 1–65535 的整数')
return config
def tool_env():
allowed = ('HOME', 'PATH', 'LANG', 'TMPDIR', 'GOPROXY', 'GOSUMDB', 'GOPRIVATE', 'GONOSUMDB',
'GOMODCACHE', 'GOCACHE', 'npm_config_cache', 'npm_config_registry',
'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
'http_proxy', 'https_proxy', 'all_proxy', 'no_proxy')
env = {key: os.environ[key] for key in allowed if key in os.environ}
env['GOFLAGS'] = '-mod=readonly'
return env
def database_env(config, directory):
# Keep inherited PG variables and integration switches out of application children.
env = tool_env()
env.update(PGHOST=config['host'], PGPORT=str(config['port']), PGDATABASE=config['database'],
PGUSER=config['user'], PGSSLMODE='verify-full', PGCONNECT_TIMEOUT='5',
PGPASSFILE=str(directory / 'qa.pgpass'), PGSSLROOTCERT=str(directory / 'rds-ca.pem'),
PGOPTIONS='-c search_path=public', LC_ALL='C',
TEST_WEKNORA_ENABLED='false', PP_SCAN_ENABLED='false',
RELEASE_WORKER_ENABLED='false', PRODUCTION_RELEASE_REQUESTS_ENABLED='false',
DOBOTAI_OPS_READ_ENABLED='false', DOBOTAI_OPS_DIRECTORY_SYNC_ENABLED='false')
env['APP_ADDR'] = f'127.0.0.1:{API_PORT}'
env['DATA' + 'BASE_URL'] = (
f"postgresql://{config['user']}@{config['host']}:{config['port']}/{config['database']}"
'?sslmode=verify-full&connect_timeout=5&search_path=public'
)
return env
def psql(env, sql):
result = capture(['psql', '-XAtw', '-v', 'ON_ERROR_STOP=1', '-c', sql], 'RDS 探针', env=env)
if result.returncode == 0:
return result.stdout.strip()
detail = result.stderr.lower()
hints = (
('password', '口令认证失败,检查 qa.pgpass 和登录角色'),
('certificate', 'TLS 校验失败,检查 RDS 主机名和 CA'),
('does not exist', '数据库或角色不存在,联系管理员确认专用 QA 库'),
('permission denied', 'RDS 权限不足,检查专用 QA 角色的 CONNECT、schema USAGE/CREATE 权限'),
('could not translate host name', 'RDS 主机名无法解析,检查私网 DNS'),
('timeout', '连接 RDS 超时,检查 QA 虚拟机到 RDS 的私网和安全组'),
('connection refused', 'RDS 拒绝 TCP 连接,检查主机名、端口和私网接入'),
)
hint = next((message for marker, message in hints if marker in detail), '连接或 SQL 探针失败,检查 RDS 接入和权限')
raise QAError(f'RDS {hint}(psql 退出 {result.returncode})')
def database_state(env):
identity = psql(env, """
SELECT concat_ws('|', current_database(), current_user,
COALESCE((SELECT ssl FROM pg_stat_ssl WHERE pid = pg_backend_pid()), false),
(SELECT NOT (rolsuper OR rolcreaterole OR rolcreatedb OR rolreplication OR rolbypassrls)
FROM pg_roles WHERE rolname = current_user),
(has_schema_privilege(current_user, 'public', 'USAGE') AND
has_schema_privilege(current_user, 'public', 'CREATE')),
to_regclass('public.schema_migrations') IS NOT NULL,
EXISTS (SELECT FROM pg_class c JOIN pg_namespace n ON n.oid=c.relnamespace
WHERE n.nspname = 'public' AND c.relname <> 'schema_migrations')
OR EXISTS (SELECT FROM pg_namespace
WHERE nspname NOT IN ('public', 'information_schema') AND nspname !~ '^pg_')
OR EXISTS (SELECT FROM pg_proc p JOIN pg_namespace n ON n.oid=p.pronamespace
WHERE n.nspname = 'public'));
""")
fields = identity.split('|')
if len(fields) != 7 or fields[:4] != [env['PGDATABASE'], env['PGUSER'], 't', 't']:
raise QAError('RDS 实际库名、角色、TLS 或角色权限与 QA 配置不符')
if fields[4] != 't':
raise QAError('RDS 角色需要 public schema 的 USAGE 和 CREATE 权限')
rows = psql(env, 'SELECT version FROM public.schema_migrations ORDER BY version;') if fields[5] == 't' else ''
if any(not re.fullmatch(r'[0-9]+', row) for row in rows.splitlines()):
raise QAError('RDS 迁移记录包含无效版本')
return [int(row) for row in rows.splitlines()], fields[6] == 't'
def expected_migrations():
paths = (ROOT / 'internal/platform/postgres/migrations').glob('*.up.sql')
try:
versions = sorted(int(path.name.split('_', 1)[0]) for path in paths)
except ValueError as exc:
raise QAError('仓库存在无效的迁移文件名') from exc
if not versions or len(versions) != len(set(versions)):
raise QAError('仓库迁移文件缺失或版本重复')
return versions
def check_migrations(expected, applied, nonempty, *, complete):
if not applied and nonempty:
raise QAError('RDS 非空且缺少有效迁移记录,停止初始化')
if expected[:len(applied)] != applied:
raise QAError('RDS 迁移序列与当前提交不兼容,使用专用空库或匹配的测试库')
if complete and applied != expected:
raise QAError(f'RDS 迁移未完成,缺少版本 {expected[len(applied)]} 至 {expected[-1]}')
def check_hifox(output):
try:
state = json.loads(output)
online = state['connected'] is True and state['remoteLiveness']['status'] == 'online'
except (ValueError, KeyError, TypeError) as exc:
raise QAError('HiFox 未返回有效的在线状态,检查本机注册和接收服务') from exc
if not online:
raise QAError('HiFox 未确认测试机在线,检查本机接收服务和网络')
def check_checkout(expected):
if not re.fullmatch(r'[0-9a-f]{40}', expected):
raise QAError('设置 KG_QA_SHA 为提测的完整 40 位 Git SHA')
actual = capture(['git', 'rev-parse', 'HEAD'], 'Git 检出')
if actual.returncode or actual.stdout.strip() != expected:
raise QAError('Git 检出与提测提交不一致')
state = capture(['git', 'status', '--porcelain'], 'Git 状态')
if state.returncode or state.stdout.strip():
raise QAError('QA 需要干净的独立检出,请检查 Git 状态')
def preflight(env):
for cmd in ('git', 'make', 'go', 'node', 'npm', 'psql', 'hifox', 'omp'):
if not shutil.which(cmd, path=env.get('PATH')):
raise QAError(f'工具链缺少 {cmd},检查 QA 机器的 PATH')
go = capture(['go', 'env', 'GOROOT', 'GOVERSION'], 'Go 工具链', env=env)
fields = go.stdout.splitlines()
if go.returncode or len(fields) != 2 or not fields[1].startswith('go1.26.'):
raise QAError('QA 需要 Go 1.26 工具链')
root = Path(fields[0]) / 'bin'
if not os.access(root / 'gofmt', os.X_OK):
raise QAError('Go 工具链缺少 gofmt,请安装完整的 Go 1.26')
env['PATH'] = f"{root}:{env['PATH']}"
node = capture(['node', '--version'], 'Node.js 工具链', env=env)
if node.returncode or not node.stdout.startswith('v22.'):
raise QAError('QA 需要 Node.js 22 工具链')
report('toolchain', f'{fields[1]} / Node.js {node.stdout.strip()}')
hifox = capture(['hifox', 'computer', 'status', '--output', 'json'], 'HiFox 在线检查', timeout=15)
if hifox.returncode:
raise QAError(f'HiFox 状态命令失败(退出 {hifox.returncode})')
check_hifox(hifox.stdout)
report('machine', f'{socket.gethostname()} / HiFox online')
prompt = f'Reply with exactly {RUNTIME_RESPONSE}. Do not use tools.'
omp = capture(['omp', '--no-session', '-p', prompt], 'OMP Runtime 探针', timeout=35)
if omp.returncode or RUNTIME_RESPONSE not in {line.strip() for line in omp.stdout.splitlines()}:
raise QAError('OMP Runtime 没有返回探针结果,检查 OMP 模型配置和 Magpie 网关')
report('runtime', 'OMP 模型请求通过')
def check_ports():
for port in (API_PORT, WEB_PORT):
with socket.socket() as listener:
listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
try:
listener.bind(('127.0.0.1', port))
except OSError as exc:
raise QAError(f'QA 端口 {port} 无法绑定,检查已有监听进程') from exc
def run_step(argv, stage, env, timeout):
report(stage, ' '.join(argv[:2]))
process = subprocess.Popen(argv, cwd=ROOT, env=env, stdin=subprocess.DEVNULL, start_new_session=True)
try:
code = process.wait(timeout=timeout)
except subprocess.TimeoutExpired as exc:
raise QAError(f'{stage} 超过 {timeout} 秒') from exc
finally:
stop_process(process)
if code:
raise QAError(f'{stage} 失败(退出 {code}),查看上方命令输出')
def stop_process(process):
try:
os.killpg(process.pid, signal.SIGTERM)
except ProcessLookupError:
pass
try:
process.wait(timeout=5)
except subprocess.TimeoutExpired:
try:
os.killpg(process.pid, signal.SIGKILL)
except ProcessLookupError:
pass
process.wait(timeout=5)
def start_service(stack, argv, env, log):
output = stack.enter_context(log.open('w', encoding='utf-8'))
process = subprocess.Popen(argv, cwd=ROOT, env=env, stdin=subprocess.DEVNULL,
stdout=output, stderr=subprocess.STDOUT, start_new_session=True)
stack.callback(stop_process, process)
return process
def request(port, path):
connection = http.client.HTTPConnection('127.0.0.1', port, timeout=2)
try:
connection.request('GET', path)
response = connection.getresponse()
return response.status, response.getheader('Content-Type', ''), response.read(32768)
finally:
connection.close()
def probe(port, path, expected):
try:
code, content_type, body = request(port, path)
if code != 200:
return False
if expected == 'html':
return 'text/html' in content_type and b'id="root"' in body
return 'application/json' in content_type and json.loads(body)['status'] == expected
except (OSError, http.client.HTTPException, ValueError, KeyError, TypeError):
return False
def wait_service(process, port, path, expected, log):
deadline = time.monotonic() + 45
while time.monotonic() < deadline:
if process.poll() is not None:
raise QAError(f'服务端口 {port} 启动进程提前退出(退出 {process.returncode}),日志 {log}')
if probe(port, path, expected):
return
time.sleep(0.25)
raise QAError(f'服务探针超时 127.0.0.1:{port}{path},日志 {log}')
def qa_run(commit, env, db_env, versions, state):
with tempfile.TemporaryDirectory(prefix='run-', dir=state) as directory, ExitStack() as services:
binary = Path(directory) / 'api'
run_step(['make', 'deps-install'], 'deps', env, 300)
ldflags = f'-X knowledge-governance/internal/version.CommitSHA={commit}'
run_step(['go', 'build', '-ldflags', ldflags, '-o', str(binary), './cmd/api'], 'build-api', env, 300)
check_ports()
log_dir = Path(tempfile.mkdtemp(prefix=f'{commit[:12]}-', dir=state))
report('logs', str(log_dir))
app_env = db_env | {'PATH': env['PATH'], 'GOVERNANCE_SPOOL_ROOT': str(Path(directory) / 'spool')}
api_log = log_dir / 'api.log'
api = start_service(services, [str(binary)], app_env, api_log)
wait_service(api, API_PORT, '/readyz', 'ready', api_log)
check_migrations(versions, *database_state(db_env), complete=True)
report('migration', f'已核对全部 {len(versions)} 条迁移,最新版本 {versions[-1]}')
web_log = log_dir / 'web.log'
web = start_service(services, ['npm', '--prefix', 'web', 'run', 'dev', '--', '--host', '127.0.0.1',
'--port', str(WEB_PORT), '--strictPort'], env, web_log)
wait_service(web, WEB_PORT, '/', 'html', web_log)
wait_service(web, WEB_PORT, '/health', 'ok', web_log)
report('services', 'API /readyz、Web 首页与 Vite /health 代理通过')
run_step(['make', 'tests-go', 'tests-web', 'tests-e2e'], 'tests', env, 300)
check_checkout(commit)
if api.poll() is not None or web.poll() is not None or not probe(WEB_PORT, '/health', 'ok'):
raise QAError(f'服务在测试期间失去健康状态,日志目录 {log_dir}')
report('result', f'PASS {commit},已停止本次 API 和 Web 进程')
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('action', choices=('doctor', 'run'))
args = parser.parse_args()
env = tool_env()
try:
commit = os.environ.get('KG_QA_SHA', '')
if args.action == 'run':
check_checkout(commit)
check_ports()
preflight(env)
config_path = Path(os.environ.get('KG_QA_CONFIG', CONFIG)).expanduser().absolute()
config = database_config(config_path)
private_file(config_path.parent / 'qa.pgpass')
if not (config_path.parent / 'rds-ca.pem').is_file():
raise QAError(f'缺少 RDS CA 文件 {config_path.parent / "rds-ca.pem"}')
db_env = database_env(config, config_path.parent)
versions = expected_migrations()
if args.action == 'doctor':
applied, nonempty = database_state(db_env)
check_migrations(versions, applied, nonempty, complete=False)
report('database', f'连接与身份正常,已应用 {len(applied)}/{len(versions)} 条迁移')
return 0
state = Path.home() / '.local/state/knowledge-governance/qa'
state.mkdir(mode=0o700, parents=True, exist_ok=True)
with (state / 'run.lock').open('a') as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError as exc:
raise QAError('本机已有 QA 任务,等待当前任务退出') from exc
check_ports()
check_migrations(versions, *database_state(db_env), complete=False)
qa_run(commit, env, db_env, versions, state)
return 0
except (QAError, OSError, ValueError) as exc:
print(f'[qa:FAIL] {exc}', file=sys.stderr)
return 1
except KeyboardInterrupt:
print('[qa:FAIL] QA 任务中断', file=sys.stderr)
return 130
if __name__ == '__main__':
def interrupt(_signal, _frame):
raise KeyboardInterrupt
signal.signal(signal.SIGTERM, interrupt)
sys.exit(main())
+83
View File
@@ -0,0 +1,83 @@
#!/usr/bin/env python3
"""Select verification commands for staged changes."""
import argparse
from pathlib import Path, PurePosixPath
import re
import shlex
import subprocess
import sys
ROOT = Path(__file__).resolve().parents[1]
def select_commands(paths, removed=()):
removed = set(removed)
full_go = full_web = browser = tooling = False
go_packages, web_tests = set(), set()
for name in paths:
path = PurePosixPath(name)
if name.startswith('docs/') or path.suffix == '.md':
continue
if name.startswith('web/e2e/') or name == 'web/playwright.config.ts':
browser = True
elif name.startswith('web/'):
if (name not in removed and name.startswith('web/src/') and
re.fullmatch(r'[\w./-]+\.test\.[jt]sx?', name)):
web_tests.add(str(path.relative_to('web')))
else:
full_web = browser = True
elif name.startswith(('scripts/', '.githooks/')) or name == 'Makefile':
tooling = full_go = full_web = browser = True
elif path.name.endswith('_test.go') and name not in removed:
go_packages.add('./' + path.parent.as_posix())
elif path.suffix == '.go' or name in ('go.mod', 'go.sum') or name.startswith(('internal/', 'cmd/')):
full_go = True
else:
full_go = full_web = browser = True
commands = []
if tooling:
commands.append(['make', 'test-tooling'])
if full_go:
commands.append(['make', 'tests-go'])
elif go_packages:
commands.append(['go', 'test', '-count=1', *sorted(go_packages)])
if full_web:
commands.append(['make', 'tests-web'])
elif web_tests:
commands.append(['npm', '--prefix', 'web', 'test', '--', *sorted(web_tests)])
if browser:
commands.append(['make', 'tests-e2e'])
return commands
def staged_names(*args):
result = subprocess.check_output(['git', 'diff', '--cached', '--no-renames', '--name-only', '-z', *args], cwd=ROOT)
return [name for name in result.decode('utf-8', errors='surrogateescape').split('\0') if name]
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--list', action='store_true', help='print selected commands only')
args = parser.parse_args()
commands = select_commands(staged_names(), staged_names('--diff-filter=D'))
if not commands:
print('暂无需要执行测试的暂存文件')
return 0
if not args.list:
unstaged = subprocess.check_output(['git', 'diff', '--name-only', '-z'], cwd=ROOT)
paths = [name for name in unstaged.decode('utf-8', errors='surrogateescape').split('\0') if name]
if select_commands(paths):
print('还有未暂存的代码或配置,先整理工作区后再检查暂存改动', file=sys.stderr)
return 1
for cmd in commands:
print(shlex.join(cmd), flush=True)
if not args.list:
code = subprocess.run(cmd, cwd=ROOT, check=False).returncode
if code:
return code
return 0
if __name__ == '__main__':
sys.exit(main())
+99
View File
@@ -0,0 +1,99 @@
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
import json
import os
from threading import Thread
from pathlib import Path
import subprocess
import tempfile
import unittest
from unittest.mock import patch
import qa_env
class QAEnvironmentTests(unittest.TestCase):
def test_missing_approval_config_names_file(self):
with tempfile.TemporaryDirectory() as directory:
config = Path(directory) / 'qa.json'
with self.assertRaisesRegex(qa_env.QAError, 'qa.json'):
qa_env.database_config(config)
def test_rejects_non_qa_database_before_connection(self):
with tempfile.TemporaryDirectory() as directory:
config = Path(directory) / 'qa.json'
config.write_text(json.dumps(dict(host='rds.example.test', port=5432,
database='governance', user='kg_qa_app')))
config.chmod(0o600)
with self.assertRaisesRegex(qa_env.QAError, 'kg_qa_'):
qa_env.database_config(config)
def test_database_environment_uses_only_approved_identity(self):
settings = dict(host='rds.example.test', port=5432, database='kg_qa_app', user='kg_qa_app')
with patch.dict(os.environ, {'PGHOSTADDR': '127.0.0.1', 'PGPASSWORD': 'fixture',
'PGSERVICE': 'other', 'PRODUCTION_RELEASE_REQUESTS_ENABLED': 'true'}):
env = qa_env.database_env(settings, Path('/approved'))
self.assertEqual(env['PGHOST'], 'rds.example.test')
self.assertEqual(env['PGSSLMODE'], 'verify-full')
self.assertEqual(env['PRODUCTION_RELEASE_REQUESTS_ENABLED'], 'false')
self.assertFalse({'PGHOSTADDR', 'PGPASSWORD', 'PGSERVICE'} & env.keys())
def test_empty_database_or_known_migration_prefix_can_bootstrap(self):
for applied in ([], [1], [1, 2]):
with self.subTest(applied=applied):
qa_env.check_migrations([1, 2], applied, False, complete=False)
def test_pending_migrations_block_testing(self):
with self.assertRaisesRegex(qa_env.QAError, '迁移未完成'):
qa_env.check_migrations([1, 2], [1], False, complete=True)
def test_schema_without_ledger_is_rejected(self):
with self.assertRaisesRegex(qa_env.QAError, '非空'):
qa_env.check_migrations([1, 2], [], True, complete=False)
def test_unknown_or_missing_middle_migrations_are_rejected(self):
for applied in ([1, 3], [1, 2, 3], [2]):
with self.subTest(applied=applied), self.assertRaisesRegex(qa_env.QAError, '迁移序列'):
qa_env.check_migrations([1, 2], applied, False, complete=False)
def test_hifox_exit_zero_does_not_override_offline_state(self):
with self.assertRaisesRegex(qa_env.QAError, '在线'):
qa_env.check_hifox('{"connected":true,"remoteLiveness":{"status":"offline"}}')
qa_env.check_hifox('{"connected":true,"remoteLiveness":{"status":"online"}}')
def test_health_probe_rejects_spa_fallback(self):
class Handler(BaseHTTPRequestHandler):
def do_GET(self):
self.send_response(200)
self.send_header('Content-Type', 'text/html')
self.end_headers()
self.wfile.write(b'<html><div id="root"></div></html>')
def log_message(self, format, *args):
pass
with ThreadingHTTPServer(('127.0.0.1', 0), Handler) as server:
thread = Thread(target=server.serve_forever)
thread.start()
try:
self.assertTrue(qa_env.probe(server.server_port, '/', 'html'))
self.assertFalse(qa_env.probe(server.server_port, '/health', 'ok'))
finally:
server.shutdown()
thread.join()
def test_database_identity_mismatch_stops_before_reading_migrations(self):
env = {'PGDATABASE': 'kg_qa_app', 'PGUSER': 'kg_qa_app'}
with patch.object(qa_env, 'psql', return_value='other|kg_qa_app|t|t|t|t|t') as probe:
with self.assertRaisesRegex(qa_env.QAError, '实际库名'):
qa_env.database_state(env)
self.assertEqual(probe.call_count, 1)
def test_full_sha_mismatch_rejects_current_checkout(self):
full_sha = subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=qa_env.ROOT, text=True).strip()
wrong = ('0' if full_sha[0] != '0' else '1') + full_sha[1:]
with self.assertRaisesRegex(qa_env.QAError, '提交不一致'):
qa_env.check_checkout(wrong)
if __name__ == '__main__':
unittest.main()
+31
View File
@@ -0,0 +1,31 @@
import unittest
from test_changed import select_commands
class SelectionTests(unittest.TestCase):
def test_documentation_only(self):
self.assertEqual(select_commands(['docs/DEVELOPMENT_AND_TESTING.md']), [])
def test_go_test_only_selects_its_package(self):
self.assertEqual(select_commands(['internal/governance/a_test.go']),
[['go', 'test', '-count=1', './internal/governance']])
def test_go_source_and_migration_fall_back_to_suite(self):
for name in ('internal/governance/model.go', 'internal/platform/postgres/migrations/0099_qa.up.sql'):
self.assertEqual(select_commands([name]), [['make', 'tests-go']])
def test_frontend_test_only_selects_its_file(self):
self.assertEqual(select_commands(['web/src/scopeRules.test.ts']),
[['npm', '--prefix', 'web', 'test', '--', 'src/scopeRules.test.ts']])
def test_shared_frontend_code_covers_browser_suite(self):
self.assertEqual(select_commands(['web/src/scopeRules.ts']),
[['make', 'tests-web'], ['make', 'tests-e2e']])
def test_e2e_only_runs_browser_suite(self):
self.assertEqual(select_commands(['web/e2e/scope-rules.spec.ts']), [['make', 'tests-e2e']])
def test_unsafe_unknown_paths_fall_back_to_all_relevant_suites(self):
self.assertEqual(select_commands(['new-runtime.conf']),
[['make', 'tests-go'], ['make', 'tests-web'], ['make', 'tests-e2e']])
+2
View File
@@ -1,4 +1,6 @@
node_modules/
dist/
test-results/
playwright-report/
*.tsbuildinfo
package-lock.json
+11
View File
@@ -0,0 +1,11 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8" />
<title>目录范围规则测试</title>
</head>
<body>
<div id="root"></div>
<script type="module" src="./scope-rules.tsx"></script>
</body>
</html>
+128
View File
@@ -0,0 +1,128 @@
import { expect, test, type Page } from '@playwright/test'
import { document as sample } from '../src/documentFixture'
import type { ScopeRule, ScopeRuleDecision } from '../src/scopeRules'
const cases = [
{ id: 'parent', directory_path: '产品', title: '总览.pdf' },
{ id: 'child', directory_path: '产品/手册', title: '手册.pdf' },
{ id: 'sibling', directory_path: '产品/固件', title: '固件.pdf' },
]
const existing: ScopeRule = {
target_type: 'directory',
connection_id: 'pp-1',
directory_path: '产品',
visibility: 'external',
reason: '父目录已公开',
updated_by: 'QA工程师',
updated_at: sample.updated_at,
}
async function scopeFixture(page: Page, canWrite = true) {
const rules = new Map<string, ScopeRule>([['产品', existing]])
const changes: ScopeRuleDecision[] = []
await page.route('**/*', async (route) => {
const request = route.request()
const url = new URL(request.url())
if (url.hostname !== '127.0.0.1' || url.port !== '4175') return route.abort()
if (url.pathname === '/api/v1/scope-rules') {
if (request.method() === 'GET' && url.searchParams.get('connection_id') === 'pp-1') {
return route.fulfill({ json: { data: [...rules.values()] } })
}
if (request.method() === 'PUT') {
const input = request.postDataJSON() as ScopeRuleDecision
changes.push(input)
if (!canWrite) return route.fulfill({ status: 403, json: { error: 'forbidden' } })
if (
input.target_type !== 'directory' ||
input.connection_id !== 'pp-1' ||
!cases.some((item) => item.directory_path === input.directory_path) ||
!request.headers()['idempotency-key'] ||
!input.reason.trim()
) {
return route.fulfill({ status: 400, json: { error: 'invalid fixture input' } })
}
const rule = { ...existing, ...input }
rules.set(input.directory_path, rule)
return route.fulfill({ json: { data: rule } })
}
}
if (url.pathname === '/api/v1/source-items' && request.method() === 'GET') {
const items = cases.map((item) => {
const rule = rules.get(item.directory_path) ?? rules.get('产品')!
return {
...sample,
...item,
visibility: rule.visibility,
visibility_origin: 'directory_rule',
scope_rule_path: rule.directory_path,
}
})
return route.fulfill({ json: { data: items, summary: { total: items.length }, offset: 0, limit: 100 } })
}
if (url.pathname.startsWith('/api/'))
return route.fulfill({ status: 404, json: { error: 'unexpected fixture request' } })
return route.continue()
})
await page.goto('/e2e/scope-rules.html')
return changes
}
function openDirectory(page: Page, name: string) {
return page
.getByRole('complementary', { name: '来源目录' })
.getByRole('button', { name: new RegExp(`^▸ ${name} \\d+$`) })
.click()
}
async function saveInternal(page: Page) {
const editor = page.getByRole('region', { name: '对内对外范围设置' })
await editor.getByLabel('拟修改为').selectOption('internal')
await expect(editor.getByRole('button', { name: '保存范围' })).toBeDisabled()
await editor.getByLabel('判断原因').fill(' 仅供内部使用 ')
await editor.getByRole('button', { name: '保存范围' }).click()
}
test('编辑器保存目录范围并在刷新后读回', async ({ page }) => {
const changes = await scopeFixture(page)
await openDirectory(page, '产品/手册')
await saveInternal(page)
await expect(page.getByText('当前设置:对内')).toBeVisible()
expect(changes).toEqual([
{
target_type: 'directory',
connection_id: 'pp-1',
directory_path: '产品/手册',
source_item_id: '',
visibility: 'internal',
reason: '仅供内部使用',
},
])
await page.reload()
await openDirectory(page, '产品/手册')
await expect(page.getByText('当前设置:对内')).toBeVisible()
await expect(page.getByRole('row', { name: /手册.pdf/ })).toContainText('继承目录设置:产品/手册')
})
test('编辑器显示只读拒绝并保留原规则', async ({ page }) => {
const changes = await scopeFixture(page, false)
await openDirectory(page, '产品/手册')
await saveInternal(page)
await expect(page.getByRole('alert')).toHaveText('保存范围规则失败(HTTP 403)')
expect(changes).toHaveLength(1)
await page.reload()
await openDirectory(page, '产品/手册')
await expect(page.getByText('当前没有本级设置')).toBeVisible()
await expect(page.getByRole('row', { name: /手册.pdf/ })).toContainText('继承目录设置:产品')
})
test('编辑器刷新并显示子目录规则和兄弟目录的继承来源', async ({ page }) => {
await scopeFixture(page)
await openDirectory(page, '产品/手册')
await saveInternal(page)
await expect(page.getByRole('row', { name: /手册.pdf/ })).toContainText('继承目录设置:产品/手册')
await openDirectory(page, '产品/固件')
const sibling = page.getByRole('row', { name: /固件.pdf/ })
await expect(sibling).toContainText('对外')
await expect(sibling).toContainText('继承目录设置:产品')
})
+4
View File
@@ -0,0 +1,4 @@
import { createRoot } from 'react-dom/client'
import { DocumentWorkbench } from '../src/DocumentWorkbench'
createRoot(document.getElementById('root')!).render(<DocumentWorkbench mode="directory" connections={[]} />)
+4
View File
@@ -0,0 +1,4 @@
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({ plugins: [react()], publicDir: false })
+46
View File
@@ -14,6 +14,7 @@
"remark-gfm": "4.0.1"
},
"devDependencies": {
"@playwright/test": "1.65.1",
"@types/react": "19.1.10",
"@types/react-dom": "19.1.7",
"@vitejs/plugin-react": "5.0.1",
@@ -814,6 +815,22 @@
"node": "^22.20 || ^24.12 || >=25"
}
},
"node_modules/@playwright/test": {
"version": "1.65.1",
"resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.65.1.tgz",
"integrity": "sha512-y+NCIRm2LvY4slUVWvGh1nujJ8RF/hEisIsq2mtUPgdQC4L701bq5hZGMhrpeXjACvwvO9tj5dJqhvM6TP9lbw==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"playwright": "1.65.1"
},
"bin": {
"playwright": "cli.js"
},
"engines": {
"node": ">=20"
}
},
"node_modules/@rolldown/pluginutils": {
"version": "1.0.0-beta.32",
"resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.32.tgz",
@@ -2887,6 +2904,35 @@
"url": "https://github.com/sponsors/jonschlinkert"
}
},
"node_modules/playwright": {
"version": "1.65.1",
"resolved": "https://registry.npmjs.org/playwright/-/playwright-1.65.1.tgz",
"integrity": "sha512-vJ1FuoOrNwOKHUIVEvSt3jT1L+wjjDpwhwIstKtfvTh8XIG4FG4bIFuvNdMxi81LGfAhUgUZleVFaOLY4RIUUw==",
"dev": true,
"license": "Apache-2.0",
"dependencies": {
"playwright-core": "1.65.1"
},
"bin": {
"playwright": "cli.js"
},
"engines": {
"node": ">=20"
}
},
"node_modules/playwright-core": {
"version": "1.65.1",
"resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.65.1.tgz",
"integrity": "sha512-hqPpz7blSMPxWVdoeE1yiBSzXsKiVOd2k+kjCvmUywD2GPO2Dd9HfcWnq9NN0GHbNZDFgZ9JfBFr+X5/BLo0qw==",
"dev": true,
"license": "Apache-2.0",
"bin": {
"playwright-core": "cli.js"
},
"engines": {
"node": ">=20"
}
},
"node_modules/postcss": {
"version": "8.5.26",
"resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
+3 -1
View File
@@ -5,7 +5,8 @@
"type": "module",
"scripts": {
"dev": "vite --host 0.0.0.0",
"test": "vitest run",
"test": "vitest run --exclude 'e2e/**'",
"test:e2e": "playwright test",
"build": "tsc -b && vite build",
"typecheck": "tsc -b --pretty false",
"format": "prettier --write .",
@@ -18,6 +19,7 @@
"remark-gfm": "4.0.1"
},
"devDependencies": {
"@playwright/test": "1.65.1",
"@types/react": "19.1.10",
"@types/react-dom": "19.1.7",
"@vitejs/plugin-react": "5.0.1",
+23
View File
@@ -0,0 +1,23 @@
import { defineConfig } from '@playwright/test'
export default defineConfig({
testDir: './e2e',
workers: 1,
retries: 0,
forbidOnly: true,
timeout: 15000,
expect: { timeout: 5000 },
use: {
browserName: 'chromium',
baseURL: 'http://127.0.0.1:4175',
serviceWorkers: 'block',
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
},
webServer: {
command: 'vite --config e2e/vite.config.ts --host 127.0.0.1 --port 4175 --strictPort',
url: 'http://127.0.0.1:4175/e2e/scope-rules.html',
reuseExistingServer: false,
timeout: 20000,
},
})
+1 -1
View File
@@ -17,5 +17,5 @@
"jsx": "react-jsx",
"types": ["vitest/globals", "vite/client"]
},
"include": ["src", "vite.config.ts"]
"include": ["src", "e2e", "vite.config.ts", "playwright.config.ts"]
}