diff --git a/.github/scripts/bug-server-gray-scope.test.cjs b/.github/scripts/bug-server-gray-scope.test.cjs new file mode 100644 index 000000000..b6bc82067 --- /dev/null +++ b/.github/scripts/bug-server-gray-scope.test.cjs @@ -0,0 +1,55 @@ +const test = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { spawnSync } = require('node:child_process'); +const source = fs.readFileSync(path.join(__dirname, '../workflows/bug-server.yml'), 'utf8'); +const gate = / gray-scope:\n([\s\S]*?)\n build:/.exec(source)?.[1]; +assert(gate, '缺少独立交接 job'); +assert.match(gate, /permissions: \{\}/); +assert.doesNotMatch(gate, /uses:|checkout/); +assert.match(source, / build:\n needs: gray-scope\n if: (?:>-\n )?needs.gray-scope.outputs.skip != 'true'/); +const script = / run: \|\n([\s\S]*)/.exec(gate)[1].replace(/^ /gm, ''); +const repository = 'VisActor/VRender'; +const original = { EVENT_NAME:'pull_request', HEAD_REF:'fix/normal', HEAD_REPOSITORY:repository, BASE_REPOSITORY:repository, + BASE_REF:'develop', REPOSITORY:repository, HEAD_REPOSITORY_ID:'649514587', BASE_REPOSITORY_ID:'649514587', CREATED_AT:'2026-10-29T08:00:01Z', INTERNAL_SINCE:'' }; +const cutoff = String(Date.parse('2026-10-29T08:00:00Z')); + +// 直接执行 workflow 的真实 Bash/Python,临时输出在每次调用后回收。 +function runGate(env) { + const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'photo-ci-handoff-')); + try { + const output = path.join(directory,'output'); fs.writeFileSync(output,''); + const result = spawnSync('/bin/bash',['--noprofile','--norc','-e','-c',script],{encoding:'utf8',timeout:10000,env:{PATH:'/usr/bin:/bin',...original,...env,GITHUB_OUTPUT:output}}); + return { status:result.status, output:fs.readFileSync(output,'utf8'), stderr:result.stderr }; + } finally { fs.rmSync(directory,{recursive:true,force:true}); } +} + +test('仅新内部 PR 交接;起点未配置、历史、fork、push 和人工入口保持旧流程', () => { + for (const [env,skip] of [ + [{},false], [{INTERNAL_SINCE:cutoff},true], + ...['main','dev/test','Develop',''].map(BASE_REF => [{INTERNAL_SINCE:cutoff,BASE_REF},false]), + [{INTERNAL_SINCE:cutoff,CREATED_AT:'2026-10-29T08:00:00Z'},false], + [{INTERNAL_SINCE:cutoff,CREATED_AT:'2026-10-29T07:59:59Z'},false], + [{INTERNAL_SINCE:cutoff,DRAFT:'true'},true], + [{INTERNAL_SINCE:cutoff,HEAD_REPOSITORY:'contributor/repo'},false], + [{INTERNAL_SINCE:cutoff,HEAD_REPOSITORY:repository.toUpperCase()},false], + [{INTERNAL_SINCE:cutoff,BASE_REPOSITORY:'contributor/repo'},false], + [{INTERNAL_SINCE:cutoff,REPOSITORY:'contributor/repo'},false], + [{INTERNAL_SINCE:'invalid',EVENT_NAME:'push'},false], + [{INTERNAL_SINCE:'invalid',EVENT_NAME:'workflow_dispatch'},false], + ]) { + const result=runGate(env); assert.equal(result.status,0,result.stderr); assert.equal(result.output,`skip=${skip}\n`); + } +}); + +test('已配置内部交接却元数据或起点非法时停止旧构建,避免重复派发', () => { + for (const env of [ + {INTERNAL_SINCE:'invalid'}, {INTERNAL_SINCE:'0'}, {INTERNAL_SINCE:'8640000000000001'}, + {INTERNAL_SINCE:'1e12'}, {INTERNAL_SINCE:'1793257200000;echo injected'}, + {HEAD_REPOSITORY_ID:'124'}, {BASE_REPOSITORY_ID:'123',HEAD_REPOSITORY_ID:'123'}, {BASE_REPOSITORY_ID:'0',HEAD_REPOSITORY_ID:'0'}, + {CREATED_AT:''}, {CREATED_AT:'2026-02-30T08:00:00Z'}, {CREATED_AT:'2026-10-29T08:00:01'}, + {CREATED_AT:'2026-10-29T08:00:01+00:00'}, + ]) { const result=runGate({INTERNAL_SINCE:cutoff,...env}); assert.notEqual(result.status,0); assert.equal(result.output,''); } +}); diff --git a/.github/workflows/bug-server.yml b/.github/workflows/bug-server.yml index bfdc2a810..dbd11cfe7 100644 --- a/.github/workflows/bug-server.yml +++ b/.github/workflows/bug-server.yml @@ -21,10 +21,56 @@ permissions: contents: read jobs: + gray-scope: + # 无权限、不检出仓库;仅以 GitHub 事件元数据和受控起点交接旧 Photo。 + runs-on: ubuntu-latest + permissions: {} + outputs: + skip: ${{ steps.scope.outputs.skip }} + steps: + - id: scope + shell: bash + env: + EVENT_NAME: ${{ github.event_name }} + HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }} + BASE_REPOSITORY: ${{ github.event.pull_request.base.repo.full_name }} + BASE_REF: ${{ github.event.pull_request.base.ref }} + HEAD_REPOSITORY_ID: ${{ github.event.pull_request.head.repo.id }} + BASE_REPOSITORY_ID: ${{ github.event.pull_request.base.repo.id }} + CREATED_AT: ${{ github.event.pull_request.created_at }} + REPOSITORY: ${{ github.repository }} + INTERNAL_SINCE: ${{ vars.VISACTOR_WORKFLOW_INTERNAL_SINCE }} + run: | + # 仅交接目标 develop;其他分支保留旧 Photo,新 Draft 等待 ready。 + skip=$(python3 - <<'PY' + import os, re + from datetime import datetime + e = os.environ + skip = False + if (e['EVENT_NAME'] == 'pull_request' and e['REPOSITORY'] == 'VisActor/VRender' + and e['HEAD_REPOSITORY'] == e['BASE_REPOSITORY'] == e['REPOSITORY'] + and e['BASE_REF'] == 'develop' and e['INTERNAL_SINCE']): + # 已配置交接却缺失可信元数据时停止旧构建,避免两套 Photo 同时执行。 + since = e['INTERNAL_SINCE'] + if not re.fullmatch(r'[1-9][0-9]{0,15}', since) or int(since) > 8640000000000000: + raise SystemExit('Invalid VISACTOR_WORKFLOW_INTERNAL_SINCE') + if e['BASE_REPOSITORY_ID'] != '649514587' or e['HEAD_REPOSITORY_ID'] != e['BASE_REPOSITORY_ID']: + raise SystemExit('Invalid internal repository identity') + created = e['CREATED_AT'] + if not re.fullmatch(r'[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z', created): + raise SystemExit('Invalid PR creation time') + skip = int(datetime.fromisoformat(created.replace('Z', '+00:00')).timestamp() * 1000) > int(since) + print('true' if skip else 'false') + PY + ) + echo "skip=$skip" >> "$GITHUB_OUTPUT" + build: + needs: gray-scope if: >- - github.event_name == 'push' || - (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) + needs.gray-scope.outputs.skip != 'true' && + (github.event_name == 'push' || + (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)) runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/unit-test.yml b/.github/workflows/unit-test.yml index 7293ff485..4cc45b6ce 100644 --- a/.github/workflows/unit-test.yml +++ b/.github/workflows/unit-test.yml @@ -26,6 +26,9 @@ jobs: # run: | # fc-list + - name: Photo CI handoff contract tests + run: node --test .github/scripts/bug-server-gray-scope.test.cjs + # Install rush - name: Install native deps for node-canvas (macOS) if: runner.os == 'macOS' @@ -41,6 +44,8 @@ jobs: run: node common/scripts/install-run-rush.js update --bypass-policy - name: Install rush run: node common/scripts/install-run-rush.js install --bypass-policy + - name: Visual runner contract tests + run: node --test packages/vrender/scripts/visual-test.test.mjs - name: Source tests (without build artifacts) run: node common/scripts/install-run-rush.js test --only tag:package - run: node common/scripts/install-run-rush.js build --only tag:package diff --git a/.gitignore b/.gitignore index cabe68bb8..cd6fe3cef 100644 --- a/.gitignore +++ b/.gitignore @@ -101,3 +101,6 @@ spec-types *.tsbuildinfo .omx/ .worktrees/ + +# 本地视觉运行产物 +.vrender-visual/ diff --git a/README.md b/README.md index 99c6540d4..44ca9434a 100644 --- a/README.md +++ b/README.md @@ -136,3 +136,7 @@ Small streams converge to make great rivers and seas! # License [MIT License](./LICENSE) + +## Playwright 视觉回归 + +首批用例、运行命令、报告协议和维护说明见[本地视觉回归指南](packages/vrender/__tests__/visual/README.md)。该入口不改变现有 Photo CI 或生产工作流启用范围。 diff --git a/README.zh-CN.md b/README.zh-CN.md index ad02dd060..b1cc8930e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -137,3 +137,7 @@ st.defaultLayer.add(sy); # 许可证 [MIT 协议](./LICENSE) + +## Playwright 视觉回归 + +首批用例、运行命令、报告协议和维护说明见[本地视觉回归指南](packages/vrender/__tests__/visual/README.md)。该入口不改变现有 Photo CI 或生产工作流启用范围。 diff --git a/common/config/rush/pnpm-lock.yaml b/common/config/rush/pnpm-lock.yaml index 19a97cfa4..38da9711e 100644 --- a/common/config/rush/pnpm-lock.yaml +++ b/common/config/rush/pnpm-lock.yaml @@ -262,6 +262,9 @@ importers: '@internal/ts-config': specifier: workspace:* version: link:../../share/ts-config + '@playwright/test': + specifier: 1.63.0 + version: 1.63.0 '@rushstack/eslint-patch': specifier: ~1.1.4 version: 1.1.4 @@ -919,7 +922,7 @@ importers: version: 4.9.5 vitest: specifier: 0.30.1 - version: 0.30.1(jsdom@16.7.0(canvas@2.11.2))(less@4.1.3)(terser@5.17.1) + version: 0.30.1(jsdom@16.7.0(canvas@2.11.2))(less@4.1.3)(playwright@1.63.0)(terser@5.17.1) packages: @@ -1708,6 +1711,11 @@ packages: peerDependencies: jest: ^26.6.2 + '@playwright/test@1.63.0': + resolution: {integrity: sha512-oxMK4vllB9RK5NQ2l1pq1IfOf2AvnEuj/vYGDj0H2nMtmtZpKtCwt/l00GEO6xjGfpBNAvjovvYdCm50dRQkpQ==} + engines: {node: '>=20'} + hasBin: true + '@remix-run/router@1.4.0': resolution: {integrity: sha512-BJ9SxXux8zAg991UmT8slpwpsd31K1dHHbD3Ba4VzD+liLQ4WAMSxQp2d2ZPRPfN0jN2NPRowcSSoM7lCaF08Q==} engines: {node: '>=14'} @@ -5172,6 +5180,16 @@ packages: pkg-types@1.3.1: resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==} + playwright-core@1.63.0: + resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==} + engines: {node: '>=20'} + hasBin: true + + playwright@1.63.0: + resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==} + engines: {node: '>=20'} + hasBin: true + plugin-error@0.1.2: resolution: {integrity: sha512-WzZHcm4+GO34sjFMxQMqZbsz3xiNEgonCskQ9v+IroMmYgk/tas8dG+Hr2D6IbRPybZ12oWpzE/w3cGJ6FJzOw==} engines: {node: '>=0.10.0'} @@ -7667,6 +7685,10 @@ snapshots: - ts-node - utf-8-validate + '@playwright/test@1.63.0': + dependencies: + playwright: 1.63.0 + '@remix-run/router@1.4.0': {} '@resvg/resvg-js-android-arm-eabi@2.4.1': @@ -10744,7 +10766,7 @@ snapshots: jest-environment-jsdom: 26.6.2(canvas@2.11.2) jest-environment-node: 26.6.2 jest-get-type: 26.3.0 - jest-jasmine2: 26.6.3 + jest-jasmine2: 26.6.3(canvas@2.11.2)(ts-node@10.9.0(@types/node@25.6.0)(typescript@4.9.5)) jest-regex-util: 26.0.0 jest-resolve: 26.6.2 jest-util: 26.6.2 @@ -10838,7 +10860,7 @@ snapshots: optionalDependencies: fsevents: 2.3.3 - jest-jasmine2@26.6.3: + jest-jasmine2@26.6.3(canvas@2.11.2)(ts-node@10.9.0(@types/node@25.6.0)(typescript@4.9.5)): dependencies: '@babel/traverse': 7.29.0 '@jest/environment': 26.6.2 @@ -10859,7 +10881,11 @@ snapshots: pretty-format: 26.6.2 throat: 5.0.0 transitivePeerDependencies: + - bufferutil + - canvas - supports-color + - ts-node + - utf-8-validate jest-leak-detector@26.6.2: dependencies: @@ -11786,6 +11812,12 @@ snapshots: mlly: 1.8.2 pathe: 2.0.3 + playwright-core@1.63.0: {} + + playwright@1.63.0: + dependencies: + playwright-core: 1.63.0 + plugin-error@0.1.2: dependencies: ansi-cyan: 0.1.1 @@ -13064,7 +13096,7 @@ snapshots: less: 4.1.3 terser: 5.17.1 - vitest@0.30.1(jsdom@16.7.0(canvas@2.11.2))(less@4.1.3)(terser@5.17.1): + vitest@0.30.1(jsdom@16.7.0(canvas@2.11.2))(less@4.1.3)(playwright@1.63.0)(terser@5.17.1): dependencies: '@types/chai': 4.3.20 '@types/chai-subset': 1.3.6(@types/chai@4.3.20) @@ -13094,6 +13126,7 @@ snapshots: why-is-node-running: 2.3.0 optionalDependencies: jsdom: 16.7.0(canvas@2.11.2) + playwright: 1.63.0 transitivePeerDependencies: - less - sass diff --git a/packages/vrender/__tests__/visual/README.md b/packages/vrender/__tests__/visual/README.md new file mode 100644 index 000000000..66369cad6 --- /dev/null +++ b/packages/vrender/__tests__/visual/README.md @@ -0,0 +1,58 @@ +# VRender 本地视觉回归 + +在 Chromium 中对当前工作区和官方 `VisActor/VRender develop` 的构建逐例比较。两侧使用冻结的同一套用例和断言,仅替换 SDK。协议沿用 VChart/VTable 串行运行器:完整 SHA、逐侧依赖校验、两侧构建、原生 Playwright 比较和可搬迁报告。首期 6 项代表用例,不代表 VRender 全功能、多浏览器或多端通过;不替代单测和 BugServer Photo。 + +运行器与报告基础复用 VChart `0b14ff87f9cc3970248c26f4ce9ecd50d9d82262` 的串行实现,仅适配 VRender 构建和页面。后续协议修复应对照两仓同步,不另建共享运行时服务。 + +## 准备与运行 + +使用 Node.js 22 或 24(产品 CI 使用 24),安装锁文件依赖和 Playwright 1.63.0 对应 Chromium;Linux 还需要浏览器系统库。 + +```sh +node common/scripts/install-run-rush.js install --ignore-hooks +PLAYWRIGHT_SKIP_BROWSER_GC=1 node packages/vrender/node_modules/@playwright/test/cli.js install chromium +node packages/vrender/scripts/visual-test.mjs --check +node packages/vrender/scripts/visual-test.mjs --list +node packages/vrender/scripts/visual-test.mjs --self-compare +node packages/vrender/scripts/visual-test.mjs --case picking-events +node packages/vrender/scripts/visual-test.mjs --baseline <完整40位SHA> +node packages/vrender/scripts/visual-test.mjs +node --test packages/vrender/scripts/visual-test.test.mjs +# 使用已经通过的真实报告执行负对照(不改源码/标准图) +VRENDER_VISUAL_FIXTURE=<报告绝对目录> node --test packages/vrender/scripts/visual-negative.test.mjs +``` + +不传筛选参数运行清单全部用例;`--case` 和 `--dir` 互斥,`--dir` 按用例子目录选择(首批用例位于根目录)。默认从固定官方地址获取 develop,fork origin 不参与解析。`--self-compare` 使用同一构建、两个浏览器上下文,仅用于确定性检查,不是正式 head/base 验证。SDK 使用既有 bundler,依次构建 core、kits、animate、components 的 ES 及主包 UMD;不会修改产品运行时代码。 + +隔离执行:`--baseline <完整SHA> --offline`。宿主预先准备两侧 Git 提交、依赖和浏览器,分别通过 `VISUAL_HEAD_DEPENDENCIES` / `VISUAL_BASELINE_DEPENDENCIES` 指定快照。每侧完整工程清单和配置须与其 SHA 一致,缺失或错配即失败;执行时不联网 fetch/install。新增运行器无需基线提交已经包含运行器,两侧均使用候选冻结套件。正式 Bot 准入只消费全量范围,单例和自比较不用于判定全量通过。 + +## 首批覆盖 + +| ID | 场景与断言 | +| --- | --- | +| primitives-text | 矩形、圆、中文/数字文本;有效边界及非空白绘制 | +| transform-clip | 分组平移、缩放、裁剪;裁剪内外真实像素 | +| picking-events | 真实鼠标悬停/点击;顶层命中、事件计数及未穿透下层 | +| tag-component | Tag 背景、文本及更新后的内容/尺寸 | +| attribute-update | 属性更新后几何与拾取位置同步 | +| stage-lifecycle | 独立 Stage 销毁后画布移除,主 Stage 继续正常绘制 | + +固定画布、视口、DPR、UTC、字体与输入;无外部资源和随机数据。必须等待两张连续截图一致。比较沿用 `threshold=0.1 / maxDiffPixels=0`,不以放宽阈值解决不稳定。动画时序、多端环境、复杂组件及性能不在首批范围。 + +## 报告与失败处理 + +产物位于 Git 忽略的 `.vrender-visual/runs//`: + +- `index.html`:基线/当前/差异图;整体复制目录以保留相对链接。 +- `agent-summary.md` 与 `summary.json`:问题摘要及 schemaVersion=1 结构化证据,含 head/base、源码摘要、用例集合、SDK 摘要、阶段结果和真实错误。 +- `build.log`、两侧 Playwright 报告、PNG 和失败 trace:排查构建、资源、交互及截图问题。 + +退出码 `0` 为所选用例通过,`1` 为视觉差异,`2` 为执行/构建/资源/清理错误。缺图、漏项、未执行、超时不得算通过。基线显式业务断言失败而当前通过时保留 `new_baseline` 证据供人工调查,不自动接受或更新标准图。先看报告错误分类,再按记录 SHA 和命令复现;禁止用跳过断言或接受差异代替修复。 + +正常、异常和 Ctrl+C 都回收本轮子进程、浏览器、HTTP 服务和基线 worktree。SIGKILL/断电后检查 `git worktree list` 及 `.vrender-visual/running.lock/owner.json`,确认所属进程结束后才处理残留,勿清理其他任务资源。 + +## 添加用例 + +在 `cases/` 新增模块并在 `cases/index.mjs` 显式登记稳定 ID、中文目的和文件路径。模块必须可被 Node/浏览器导入:`createSpec(VRender, stage)` 创建图形并返回供断言使用的对象;可选 `exercise(page)` 执行交互;`verify(page)` 核对真实业务结果。仅明确的业务不符使用 `assertionError`,不得把资源/浏览器异常包装成业务失败。新增后运行自检、自比较和冻结基线比较,并证明可见变化/错误行为能被检测。 + +本入口合入不代表 AI PR 工作流已上线。旧 Photo CI 已准备独立的 `gray-scope` 判断,`VISACTOR_WORKFLOW_INTERNAL_SINCE` 未配置时保持原有触发。启用后仅交接仓库 ID 649514587、同仓、目标 develop 且创建时间晚于起点的新 PR;新 Draft 同样交接并由 Bot 等待 ready。存量、fork、其他目标、main push 和维护者手动入口保持原职责。起点或仓库身份非法时停止旧构建,避免重复派发。该变量必须与 Bot discovery.createdAfter、BugServer 服务身份 internalSince 一致,并在起点前完成存量快照;本提交不设置变量或变更生产调度,正式切流另行验收与授权。 diff --git a/packages/vrender/__tests__/visual/assertions.mjs b/packages/vrender/__tests__/visual/assertions.mjs new file mode 100644 index 000000000..f1e8f5560 --- /dev/null +++ b/packages/vrender/__tests__/visual/assertions.mjs @@ -0,0 +1,14 @@ +/** 仅在显式业务状态比较失败处构造;不要包装浏览器或页面 API 的执行异常。 */ +export function assertionError(message) { + const error = new Error(message); + error.name = 'VisualAssertionError'; + return error; +} + +/** 识别显式业务断言,包括 Playwright 跨 page.evaluate 序列化后的首行类型标记。 */ +export function isBusinessAssertion(error) { + return ( + error.name === 'VisualAssertionError' || + /^(?:Error: )?(?:(?:page|frame)\.evaluate(?:Handle)?: )?VisualAssertionError: /.test(String(error.message ?? '')) + ); +} diff --git a/packages/vrender/__tests__/visual/cases/attribute-update.mjs b/packages/vrender/__tests__/visual/cases/attribute-update.mjs new file mode 100644 index 000000000..ada5df60f --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/attribute-update.mjs @@ -0,0 +1,15 @@ +import { assertionError } from '../assertions.mjs'; + +/** 属性更新同步改变几何与拾取位置。 */ +export function createSpec(v, stage) { + const rect=v.createRect({x:40,y:50,width:100,height:60,fill:'#3366cc'});stage.defaultLayer.add(rect);return {rect}; +} + +/** 通过真实浏览器操作或公开 API 执行交互。 */ +export async function exercise(page) { await page.evaluate(()=>{window.__visualObjects.rect.setAttributes({x:220,width:160,fill:'#e8684a'});window.__visualStage.render();}); } + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const {rect}=window.__visualObjects;const stage=window.__visualStage;return rect.attribute.x===220 && stage.pick(250,80).graphic===rect && !stage.pick(60,80); }); + if (!ok) throw assertionError('属性更新同步改变几何与拾取位置断言失败'); +} diff --git a/packages/vrender/__tests__/visual/cases/index.mjs b/packages/vrender/__tests__/visual/cases/index.mjs new file mode 100644 index 000000000..1e9417f02 --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/index.mjs @@ -0,0 +1,36 @@ +/** 冻结的首批用例清单;新增用例须显式登记。 */ +export const cases = [ + { + "id": "primitives-text", + "purpose": "图元和文本产生实际绘制与有效边界", + "file": "./primitives-text.mjs" + }, + { + "id": "transform-clip", + "purpose": "分组平移缩放与裁剪边界", + "file": "./transform-clip.mjs" + }, + { + "id": "picking-events", + "purpose": "真实鼠标悬停及点击命中顶层图元", + "file": "./picking-events.mjs" + }, + { + "id": "tag-component", + "purpose": "标签组件文字、背景与更新", + "file": "./tag-component.mjs" + }, + { + "id": "attribute-update", + "purpose": "属性更新同步改变几何与拾取位置", + "file": "./attribute-update.mjs" + }, + { + "id": "stage-lifecycle", + "purpose": "销毁独立 Stage 后画布移除且主 Stage 可继续绘制", + "file": "./stage-lifecycle.mjs" + } +]; + +/** Node 和浏览器共用相同用例模块。 */ +export function loadCase(item) { return import(item.file); } diff --git a/packages/vrender/__tests__/visual/cases/picking-events.mjs b/packages/vrender/__tests__/visual/cases/picking-events.mjs new file mode 100644 index 000000000..d9220a7e9 --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/picking-events.mjs @@ -0,0 +1,21 @@ +import { assertionError } from '../assertions.mjs'; + +/** 真实鼠标悬停及点击命中顶层图元。 */ +export function createSpec(v, stage) { + const bottom=v.createRect({x:40,y:40,width:240,height:160,fill:'#3366cc'}); + const top=v.createRect({x:80,y:80,width:120,height:80,fill:'#e8684a'}); + const counts={click:0,enter:0,bottom:0}; + top.addEventListener('pointerenter',()=>{counts.enter++;}); + top.addEventListener('click',()=>{counts.click++; top.setAttribute('fill','#339966');stage.render();}); + bottom.addEventListener('click',()=>{counts.bottom++;}); + stage.defaultLayer.add(bottom);stage.defaultLayer.add(top);return {top,counts}; +} + +/** 通过真实浏览器操作或公开 API 执行交互。 */ +export async function exercise(page) { await page.mouse.move(10,10); await page.mouse.move(120,110); await page.mouse.click(120,110); } + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const {top,counts}=window.__visualObjects;return counts.click===1 && counts.enter>=1 && counts.bottom===0 && window.__visualStage.pick(120,110).graphic===top && top.attribute.fill==='#339966'; }); + if (!ok) throw assertionError('真实鼠标悬停及点击命中顶层图元断言失败'); +} diff --git a/packages/vrender/__tests__/visual/cases/primitives-text.mjs b/packages/vrender/__tests__/visual/cases/primitives-text.mjs new file mode 100644 index 000000000..ca4e7d7e9 --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/primitives-text.mjs @@ -0,0 +1,16 @@ +import { assertionError } from '../assertions.mjs'; + +/** 图元和文本产生实际绘制与有效边界。 */ +export function createSpec(v, stage) { + const rect = v.createRect({x: 40, y: 40, width: 180, height: 90, fill: '#3366cc'}); + const circle = v.createCircle({x: 320, y: 90, radius: 45, fill: '#e8684a'}); + const text = v.createText({x: 40, y: 200, text: 'VRender 123 中文', fontSize: 24, fontFamily: 'Arial', fill: '#222'}); + for (const graphic of [rect, circle, text]) stage.defaultLayer.add(graphic); + return {rect, circle, text}; +} + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const {rect,circle,text}=window.__visualObjects; return [rect,circle,text].every(g=>g.AABBBounds.width()>0 && g.AABBBounds.height()>0) && text.attribute.text==='VRender 123 中文'; }); + if (!ok) throw assertionError('图元和文本产生实际绘制与有效边界断言失败'); +} diff --git a/packages/vrender/__tests__/visual/cases/stage-lifecycle.mjs b/packages/vrender/__tests__/visual/cases/stage-lifecycle.mjs new file mode 100644 index 000000000..47917f98c --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/stage-lifecycle.mjs @@ -0,0 +1,17 @@ +import { assertionError } from '../assertions.mjs'; + +/** 销毁独立 Stage 后画布移除且主 Stage 可继续绘制。 */ +export function createSpec(v, stage) { + const container=document.createElement('div');document.body.append(container); + const temporary=v.createStage({container,width:100,height:100,dpr:1,autoRender:false}); + temporary.defaultLayer.add(v.createRect({width:60,height:60,fill:'#f00'}));temporary.render(); + const hadCanvas=container.querySelectorAll('canvas').length>0; + temporary.release();const removed=container.querySelectorAll('canvas').length===0;container.remove(); + stage.defaultLayer.add(v.createRect({x:40,y:40,width:200,height:100,fill:'#339966'}));return {hadCanvas,removed,temporary}; +} + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const x=window.__visualObjects;return x.hadCanvas && x.removed && x.temporary.releaseStatus==='released' && document.querySelectorAll('#chart canvas').length>0; }); + if (!ok) throw assertionError('销毁独立 Stage 后画布移除且主 Stage 可继续绘制断言失败'); +} diff --git a/packages/vrender/__tests__/visual/cases/tag-component.mjs b/packages/vrender/__tests__/visual/cases/tag-component.mjs new file mode 100644 index 000000000..38f25128a --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/tag-component.mjs @@ -0,0 +1,16 @@ +import { assertionError } from '../assertions.mjs'; + +/** 标签组件文字、背景与更新。 */ +export function createSpec(v, stage) { + const tag=new v.Tag({x:60,y:60,text:'Ready',padding:12,textStyle:{fontSize:20,fontFamily:'Arial',fill:'#222'},panel:{visible:true,fill:'#ddeeff',cornerRadius:6}}); + stage.defaultLayer.add(tag);return {tag}; +} + +/** 通过真实浏览器操作或公开 API 执行交互。 */ +export async function exercise(page) { await page.evaluate(()=>{window.__visualObjects.tag.setAttribute('text','Updated');window.__visualStage.render();}); } + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const {tag}=window.__visualObjects;return tag.getTextShape().attribute.text==='Updated' && tag.getBgRect().AABBBounds.width()>40 && tag.AABBBounds.height()>20; }); + if (!ok) throw assertionError('标签组件文字、背景与更新断言失败'); +} diff --git a/packages/vrender/__tests__/visual/cases/transform-clip.mjs b/packages/vrender/__tests__/visual/cases/transform-clip.mjs new file mode 100644 index 000000000..9c028a03d --- /dev/null +++ b/packages/vrender/__tests__/visual/cases/transform-clip.mjs @@ -0,0 +1,14 @@ +import { assertionError } from '../assertions.mjs'; + +/** 分组平移缩放与裁剪边界。 */ +export function createSpec(v, stage) { + const group = v.createGroup({x: 80, y: 70, width: 120, height: 80, scaleX: 1.5, scaleY: 1.5, clip: true}); + const rect = v.createRect({x: 0, y: 0, width: 200, height: 150, fill: '#3366cc'}); + group.add(rect); stage.defaultLayer.add(group); return {group,rect}; +} + +/** 显式核对业务结果,空白截图不能替代语义成功。 */ +export async function verify(page) { + const ok=await page.evaluate(()=>{ const canvas=document.querySelector('#chart canvas'),ctx=canvas.getContext('2d'); const inside=ctx.getImageData(100,90,1,1).data,outside=ctx.getImageData(280,210,1,1).data; return inside[2]>inside[0] && outside[0]===255 && outside[1]===255 && outside[2]===255; }); + if (!ok) throw assertionError('分组平移缩放与裁剪边界断言失败'); +} diff --git a/packages/vrender/__tests__/visual/page.html b/packages/vrender/__tests__/visual/page.html new file mode 100644 index 000000000..2b519307b --- /dev/null +++ b/packages/vrender/__tests__/visual/page.html @@ -0,0 +1,62 @@ + + + + + + + VRender visual regression + + + +
+ + + diff --git a/packages/vrender/__tests__/visual/playwright.config.mjs b/packages/vrender/__tests__/visual/playwright.config.mjs new file mode 100644 index 000000000..17caa4b11 --- /dev/null +++ b/packages/vrender/__tests__/visual/playwright.config.mjs @@ -0,0 +1,37 @@ +import path from 'node:path'; +import { defineConfig } from '@playwright/test'; +import { settings } from './settings.mjs'; + +const runDir = process.env.VISUAL_RUN_DIR; +const phase = process.env.VISUAL_PHASE; +if (!runDir || !['baseline', 'current'].includes(phase)) throw new Error('请通过 visual-test.mjs 运行'); + +export default defineConfig({ + testDir: '.', + testMatch: 'visual.spec.mjs', + workers: 1, + retries: 0, + timeout: settings.timeout, + outputDir: path.join(runDir, `${phase}-results`), + snapshotPathTemplate: path.join(runDir, 'snapshots', '{arg}{ext}'), + updateSnapshots: phase === 'baseline' ? 'all' : 'none', + expect: { timeout: 5000, toMatchSnapshot: settings.comparison }, + reporter: [ + ['line'], + ['html', { outputFolder: path.join(runDir, `${phase}-report`), open: 'never' }], + ['json', { outputFile: path.join(runDir, `${phase}-playwright.json`) }], + ['./reporter.mjs'] + ], + use: { + browserName: 'chromium', + headless: true, + viewport: settings.viewport, + deviceScaleFactor: settings.deviceScaleFactor, + locale: settings.locale, + timezoneId: settings.timezoneId, + colorScheme: 'light', + reducedMotion: 'reduce', + serviceWorkers: 'block', + trace: 'retain-on-failure' + } +}); diff --git a/packages/vrender/__tests__/visual/report.mjs b/packages/vrender/__tests__/visual/report.mjs new file mode 100644 index 000000000..edca81175 --- /dev/null +++ b/packages/vrender/__tests__/visual/report.mjs @@ -0,0 +1,488 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; + +/** 转义报告中的动态文本,同时用于 HTML 内容和属性。 */ +function escape(value) { + return String(value ?? '') + .replaceAll('&', '&') + .replaceAll('<', '<') + .replaceAll('>', '>') + .replaceAll('"', '"') + .replaceAll("'", '''); +} + +/** 复现参数以单引号包裹,避免目录或报告文字被 shell 解释。 */ +function quote(value) { + return `'${String(value).replaceAll("'", "'\\''")}'`; +} + +/** 人与 Agent 共用范围说明;未选用例不被描述为已通过。 */ +function selectionDescription(report) { + const selection = report.selection; + if (!selection) return `范围未记录;本次记录 ${report.cases.length} 个用例`; + const label = + selection.mode === 'all' + ? '全部本地用例' + : `${selection.mode === 'directory' ? '目录' : '单用例'} ${selection.value}`; + return `${label};选中 ${selection.selectedCount} / ${selection.totalCount};其余 ${ + selection.totalCount - selection.selectedCount + } 个未执行`; +} + +/** 将已存在的运行内文件转换为可搬迁的相对路径,拒绝越界引用。 */ +async function artifact(runDir, relative) { + if (!relative || path.isAbsolute(relative) || relative.split(/[\\/]/).includes('..')) return null; + try { + return (await fs.stat(path.join(runDir, relative))).isFile() ? relative : null; + } catch (error) { + if (error.code === 'ENOENT') return null; + throw error; + } +} + +/** 汇合两阶段结果;缺少图片或未完成比较不能被解释为通过。 */ +export async function saveReport(runDir, summary) { + const phases = {}; + const reportStarted = performance.now(); + const issues = [...(summary.issues ?? [])]; + const selection = summary.selection; + if ( + selection && + (!['all', 'directory', 'case'].includes(selection.mode) || + !Number.isSafeInteger(selection.totalCount) || + selection.totalCount < summary.cases.length || + selection.selectedCount !== summary.cases.length || + !Array.isArray(selection.selectedIds) || + selection.selectedIds.length !== summary.cases.length || + new Set(selection.selectedIds).size !== summary.cases.length || + summary.cases.some(item => !selection.selectedIds.includes(item.id)) || + (selection.mode === 'all' && (selection.value !== null || selection.totalCount !== selection.selectedCount)) || + (selection.mode !== 'all' && typeof selection.value !== 'string') || + (selection.mode === 'case' && (selection.selectedCount !== 1 || selection.selectedIds[0] !== selection.value))) + ) + issues.push({ + phase: 'report', + category: 'execution', + code: 'RESULT_SET_MISMATCH', + message: '报告范围与选中用例集合不一致' + }); + for (const phase of ['baseline', 'current']) { + phases[phase] = summary[`${phase}Result`]; + if (!phases[phase]) { + try { + phases[phase] = JSON.parse(await fs.readFile(path.join(runDir, `${phase}-result.json`), 'utf8')); + } catch (error) { + if (error.code !== 'ENOENT') + issues.push({ phase, category: 'report', code: 'REPORT_FAILED', message: String(error) }); + } + } + for (const message of phases[phase]?.errors ?? []) + issues.push({ phase, category: 'execution', code: 'EXECUTION_FAILED', message }); + } + if (summary.error) + issues.push({ phase: summary.stage ?? 'preparation', category: 'execution', message: summary.error }); + if (summary.cleanupError) issues.push({ phase: 'cleanup', category: 'execution', message: summary.cleanupError }); + for (const [phase, result] of Object.entries(phases)) { + if (!result) continue; + const expected = summary.cases.map(item => item.id); + const actual = result.tests.map(item => item.id); + if ( + actual.length !== expected.length || + new Set(actual).size !== actual.length || + actual.some(id => !expected.includes(id)) + ) + issues.push({ phase, category: 'execution', code: 'RESULT_SET_MISMATCH', message: '阶段结果与选择集不一致' }); + // 独立汇总也校验原始阶段终态;不把超时、中断或旧格式缺失终态解释为完整通过。 + if (result.finalized !== true || !['passed', 'failed'].includes(result.endedStatus)) + issues.push({ + phase, + category: 'execution', + code: 'RUN_INCOMPLETE', + message: `阶段未正常结束(${result.endedStatus ?? 'missing'}),保留已完成用例` + }); + + } + // 预检失败时尚未解析基线,复现仍应保留用户请求的 SHA 或自比较模式。 + const command = summary.command ?? 'node packages/vrender/scripts/visual-test.mjs'; + const baselineSha = summary.baseline?.sha ?? summary.request?.baseline; + const baselineArg = + summary.baseline?.repository === 'working-tree' || summary.request?.['self-compare'] + ? '--self-compare' + : baselineSha + ? `--baseline ${baselineSha}${summary.request?.offline ? ' --offline' : ''}` + : ''; + const cases = []; + for (const item of summary.cases) { + const baseline = phases.baseline?.tests.find(test => test.id === item.id); + const current = phases.current?.tests.find(test => test.id === item.id); + const errors = []; + const images = { baseline: null, current: null, diff: null }; + for (const [phase, result] of [ + ['baseline', baseline], + ['current', current] + ]) { + for (const message of result?.errors ?? []) { + errors.push({ + phase, + stage: result.stage ?? 'execution', + category: result.status === 'diff' ? 'visual_difference' : result.category ?? 'execution', + code: result.code ?? (result.status === 'diff' ? 'VISUAL_DIFFERENCE' : 'EXECUTION_FAILED'), + message + }); + } + images[phase] = await artifact(runDir, result?.attachments?.find(file => file.name === 'rendered')?.path); + if (['passed', 'diff'].includes(result?.status) && !images[phase]) { + errors.push({ + phase, + stage: 'report', + category: 'missing_artifact', + code: 'MISSING_ARTIFACT', + message: '缺少最终截图' + }); + } + } + images.diff = await artifact(runDir, current?.attachments?.find(file => file.name.endsWith('-diff.png'))?.path); + if (current?.status === 'diff' && !images.diff) + errors.push({ + phase: 'current', + stage: 'report', + category: 'missing_artifact', + code: 'MISSING_ARTIFACT', + message: '缺少差异图' + }); + const baselineAssertion = + phases.baseline?.finalized === true && + phases.baseline.endedStatus === 'failed' && + !phases.baseline.errors?.length && + phases.current?.finalized === true && + phases.current.endedStatus === 'passed' && + !phases.current.errors?.length && + baseline?.status === 'error' && + baseline.businessAssertion === true && + ['INTERACTION_ASSERTION_FAILED', 'CASE_ASSERTION_FAILED'].includes(baseline.code) && + current?.status === 'passed' && + images.current && + errors.length > 0 && + errors.every( + error => + error.phase === 'baseline' && ['INTERACTION_ASSERTION_FAILED', 'CASE_ASSERTION_FAILED'].includes(error.code) + ); + const executionError = + errors.some(error => error.category !== 'visual_difference') || + [baseline, current].some(result => result?.status === 'error'); + const status = baselineAssertion + ? 'new_baseline' + : executionError + ? 'error' + : baseline?.status !== 'passed' || !current || current.status === 'not_run' + ? 'not_run' + : current.status; + const attachments = []; + for (const [phase, result] of [ + ['baseline', baseline], + ['current', current] + ]) { + for (const file of result?.attachments ?? []) { + const relative = await artifact(runDir, file.path); + if (relative) attachments.push({ phase, ...file, path: relative }); + } + } + cases.push({ + ...item, + status, + ...(status === 'not_run' + ? { + blockedBy: { + phase: baseline?.status === 'passed' ? 'current' : 'baseline', + reason: '前序阶段失败或该阶段未完成' + } + } + : {}), + phases: { baseline: baseline?.status ?? 'not_run', current: current?.status ?? 'not_run' }, + durationMs: (baseline?.durationMs ?? 0) + (current?.durationMs ?? 0), + images, + attachments, + errors, + rerun: `${command} ${baselineArg} --case ${quote(item.id)}`.replace(' ', ' ') + }); + } + const counts = Object.fromEntries( + ['passed', 'diff', 'new_baseline', 'error', 'not_run'].map(status => [ + status, + cases.filter(item => item.status === status).length + ]) + ); + const complete = + cases.length > 0 && + cases.every(item => ['passed', 'diff', 'new_baseline'].includes(item.status)) && + !issues.some(issue => ['RESULT_SET_MISMATCH', 'RUN_INCOMPLETE'].includes(issue.code)); + const status = + summary.status === 'error' || issues.length || !complete + ? 'error' + : counts.diff || counts.new_baseline + ? 'diff' + : 'passed'; + const logs = {}; + for (const name of [ + 'build.log', + 'baseline.log', + 'current.log', + 'baseline-report/index.html', + 'current-report/index.html' + ]) { + const relative = await artifact(runDir, name); + if (relative) logs[name] = relative; + } + const { baselineResult, currentResult, ...metadata } = summary; + const report = { + ...metadata, + schemaVersion: 1, + finalized: summary.finalized ?? true, + status, + complete, + counts, + cases, + issues, + logs, + rerun: selection + ? [ + command, + baselineArg, + selection.mode === 'all' + ? '' + : `${selection.mode === 'directory' ? '--dir' : '--case'} ${quote(selection.value)}` + ] + .filter(Boolean) + .join(' ') + : null, + environment: { + ...summary.environment, + browser: phases.current?.browser ?? phases.baseline?.browser ?? summary.environment.browser + } + }; + // 汇总只生成新对象;HTML 和 Markdown 不改变调用方的状态。 + report.timings = { ...summary.timings, reportMs: Math.round(performance.now() - reportStarted) }; + await writeJson(path.join(runDir, 'summary.json'), report); + await fs.writeFile(path.join(runDir, 'agent-summary.md'), agentSummary(report)); + await fs.writeFile(path.join(runDir, 'index.html'), renderHtml(report)); + report.timings.reportMs = Math.round(performance.now() - reportStarted); + if (report.timings.totalMs !== undefined) report.timings.totalMs += report.timings.reportMs; + await writeJson(path.join(runDir, 'summary.json'), report); + await fs.writeFile(path.join(runDir, 'agent-summary.md'), agentSummary(report)); + await fs.writeFile(path.join(runDir, 'index.html'), renderHtml(report)); + return report; +} + +/** 输出失败优先的纯文本入口,让 Agent 按路径读取证据而非消耗 Base64。 */ +function agentSummary(report) { + const lines = [ + '# VRender 视觉回归结果', + '', + `状态:${report.status};完整执行:${report.complete};${JSON.stringify(report.counts)}`, + `测试范围:${selectionDescription(report)}`, + ...(report.rerun ? [`本次范围复现:\`${report.rerun}\``] : []), + '', + `基线:${report.baseline?.repository ?? '未解析'} @ ${report.baseline?.sha ?? '未解析'}`, + `本地:${report.local?.head ?? '未知'};dirty=${report.local?.dirty ?? '未知'};工作区摘要=${ + report.local?.digest ?? '未知' + }`, + `环境:${JSON.stringify(report.environment)}`, + '', + '完整结构化结果:[summary.json](summary.json)(schemaVersion=1);所有证据路径相对于此报告目录。', + '以下记录测试事实,不判断差异是否属于缺陷。复现命令在仓库根目录执行;基线 SHA 固定,本地工作区需要与摘要一致。', + '用例 source.path 指向仓库文件;source.frozenPath 指向本次运行冻结文件。', + '截图需由支持图片的 Agent 按需打开;本报告不调用模型,也不自动接受差异。', + '' + ]; + for (const issue of report.issues) + lines.push( + `## 运行错误:${issue.phase} / ${issue.code ?? issue.category}`, + '', + ...issue.message.split('\n').map(line => `> ${line}`), + '' + ); + for (const item of report.cases.filter(item => item.status !== 'passed')) { + lines.push( + `## ${item.id} — ${item.status}`, + '', + item.purpose, + '', + `源码:${item.source?.path ?? '未知'}:${item.source?.line ?? '?'};冻结副本:${ + item.source?.frozenPath ?? '未知' + }`, + `阶段:${JSON.stringify(item.phases)}`, + '', + `复现:\`${item.rerun}\``, + '' + ); + for (const [kind, file] of Object.entries(item.images)) + lines.push(`- ${kind}:${file ? `[${file}](${file})` : '未生成或缺失'}`); + for (const error of item.errors) + lines.push( + '', + `${error.phase} / ${error.stage} / ${error.code ?? error.category}`, + ...error.message.split('\n').map(line => `> ${line}`) + ); + lines.push(''); + } + if (report.complete && !report.counts.diff && !report.counts.new_baseline) + lines.push('所选用例全部通过,详情见 summary.json。', ''); + lines.push('## 日志与详细报告', '', ...Object.values(report.logs).map(file => `- [${file}](${file})`), ''); + return lines.join('\n'); +} + +/** 生成无需服务和网络的三图报告;原图链接保留完整分辨率。 */ +function renderHtml(report) { + const labels = { + new_baseline: '旧版断言失败,修复待确认', + passed: '通过', + diff: '视觉差异', + error: '执行错误', + not_run: '未完成' + }; + const link = (file, label) => `${escape(label)}`; + const baseline = report.baseline?.repository === 'working-tree' ? '工作区自比较' : '官方基线'; + const cards = report.cases + .map( + item => `
+

${escape(item.id)}

${ + labels[item.status] + }${(item.durationMs / 1000).toFixed(1)}s
+

${escape(item.purpose)}

${[ + ['baseline', `${baseline} · ${report.baseline?.sha?.slice(0, 8) ?? '?'}`], + ['current', `本地 · ${report.local?.head?.slice(0, 8) ?? '?'}${report.local?.dirty ? ' + 未提交修改' : ''}`], + ['diff', 'Diff · 差异图'] + ] + .map( + ([kind, title]) => + `
${escape(title)}
${ + item.images[kind] + ? `${escape(`${item.id} ${title}`)}` + : `
${ + kind === 'diff' && item.status === 'passed' ? '无视觉差异' : '未生成或缺失;请查看状态与诊断' + }
` + }
` + ) + .join('')}
+

用例:${escape(item.source?.path)}:${item.source?.line ?? '?'} · ${ + item.source?.frozenPath ? link(item.source.frozenPath, '查看冻结用例') : '' + } · baseline=${item.phases.baseline} / current=${item.phases.current}

+
${escape(item.rerun)}
+ ${ + item.errors.length + ? `
诊断(${ + item.errors.length + })${item.errors + .map( + error => + `

${escape(`${error.phase} / ${error.stage} / ${error.code ?? error.category}`)}

${escape(
+                  error.message
+                )}
` + ) + .join('')}
` + : '' + } + ${ + item.attachments.length + ? `
证据文件
    ${item.attachments + .map(file => `
  • ${escape(file.phase)} · ${link(file.path, file.name)}
  • `) + .join('')}
` + : '' + }
` + ) + .join(''); + return `VRender 视觉回归 · ${ + labels[report.status] + } +

VRender 视觉回归 · ${labels[report.status]}

${escape(report.startedAt)} · ${ + report.complete ? '所选用例执行完整;待确认项不代表比较通过' : '执行未完整完成' + } · ${escape(report.environment.platform)} / ${escape(report.environment.arch)} · Chromium ${escape( + report.environment.browser ?? '未启动' + )}

基线 ${escape(report.baseline?.sha ?? '未解析')} · 本地 ${escape(report.local?.head ?? '未解析')}${ + report.local?.dirty ? '(有未提交修改)' : '' + }

${escape(selectionDescription(report))}

+
${Object.entries(report.counts) + .map(([status, count]) => `
${count}${labels[status]}
`) + .join('')}
+

同机、同一套用例对比。点击图片打开原图;视觉差异需要审查,不自动判为缺陷。

+ ${ + report.rerun + ? `

本次范围复现:

${escape( + report.rerun + )}
` + : '' + } + ${report.issues + .map( + issue => + `
${escape( + `${issue.phase} / ${issue.code ?? issue.category}` + )}
${escape(issue.message)}
` + ) + .join('')} +
${cards} +
+ `; +} + +/** 在报告目录内原子替换 JSON,避免读者看到半写入的终态。 */ +async function writeJson(file, value) { + const temporary = `${file}.tmp`; + await fs.writeFile(temporary, JSON.stringify(value, null, 2)); + await fs.rename(temporary, file); +} diff --git a/packages/vrender/__tests__/visual/reporter.mjs b/packages/vrender/__tests__/visual/reporter.mjs new file mode 100644 index 000000000..b4e0c588b --- /dev/null +++ b/packages/vrender/__tests__/visual/reporter.mjs @@ -0,0 +1,103 @@ +import fs from 'node:fs'; +import path from 'node:path'; +import { stripVTControlCharacters } from 'node:util'; +import { isBusinessAssertion } from './assertions.mjs'; + +/** 每个完成用例即保存证据,不依赖进程正常结束才落盘。 */ +export default class VisualReporter { + tests = []; + errors = []; + onError(error) { + // 记录 worker 等运行级错误,并保留已完成用例。 + this.errors.push(stripVTControlCharacters(error.message ?? String(error))); + this.persist(false); + } + onTestEnd(test, result) { + // diff 标记仅由截图适配层在确认原生比较证据完整后添加。 + const difference = result.attachments.some(item => item.name === 'visual-difference'); + const stage = test.annotations.find(item => item.type === 'stage')?.description ?? 'setup'; + const businessAssertion = + result.status === 'failed' && result.errors.length > 0 && result.errors.every(isBusinessAssertion); + const failureCategory = + result.status === 'timedOut' + ? 'timeout' + : test.annotations.find(item => item.type === 'failure-category')?.description || stage; + // 阶段只描述动作位置;普通异常和浏览器生命周期错误不能冒充业务断言。 + const category = + result.status === 'failed' && ['interaction', 'verify'].includes(failureCategory) && !businessAssertion + ? 'execution' + : failureCategory; + const codes = { + resource: 'RESOURCE_FAILED', + render: 'RENDER_FAILED', + interaction: 'INTERACTION_ASSERTION_FAILED', + verify: 'CASE_ASSERTION_FAILED', + screenshot: 'SCREENSHOT_FAILED', + comparison: 'COMPARISON_FAILED', + timeout: 'TIMEOUT', + missing_artifact: 'MISSING_ARTIFACT', + setup: 'PREFLIGHT_FAILED' + }; + this.browser = test.annotations.find(item => item.type === 'browser')?.description ?? this.browser; + this.tests.push({ + id: test.title, + businessAssertion, + status: + result.status === 'passed' + ? 'passed' + : result.status === 'skipped' + ? 'not_run' + : result.status === 'failed' && difference + ? 'diff' + : 'error', + stage, + category, + code: + result.status === 'passed' + ? null + : result.status === 'skipped' + ? 'RUN_INCOMPLETE' + : difference + ? 'VISUAL_DIFFERENCE' + : codes[category] ?? 'EXECUTION_FAILED', + durationMs: result.duration, + errors: result.errors.map(error => stripVTControlCharacters(error.message ?? String(error))), + attachments: result.attachments + .filter(item => item.path) + .map(item => ({ + name: item.name, + contentType: item.contentType, + path: path.relative(process.env.VISUAL_RUN_DIR, item.path).split(path.sep).join('/') + })) + }); + this.persist(false); + } + persist(finalized, endedStatus) { + // 原子替换阶段结果并保留 Playwright 原始终态,逐用例通过不能覆盖阶段超时。 + const status = + !finalized || + this.errors.length || + !this.tests.length || + this.tests.some(test => ['error', 'not_run'].includes(test.status)) || + ['interrupted', 'timedout'].includes(endedStatus) + ? 'error' + : this.tests.some(test => test.status === 'diff') + ? 'diff' + : 'passed'; + const file = path.join(process.env.VISUAL_RUN_DIR, `${process.env.VISUAL_PHASE}-result.json`); + const temporary = `${file}.tmp`; + fs.writeFileSync( + temporary, + JSON.stringify( + { finalized, endedStatus, status, browser: this.browser, tests: this.tests, errors: this.errors }, + null, + 2 + ) + ); + fs.renameSync(temporary, file); + } + onEnd(result) { + // 最终更新状态,保留每个用例独立写入的原始诊断。 + this.persist(true, result.status); + } +} diff --git a/packages/vrender/__tests__/visual/settings.mjs b/packages/vrender/__tests__/visual/settings.mjs new file mode 100644 index 000000000..e10123d2d --- /dev/null +++ b/packages/vrender/__tests__/visual/settings.mjs @@ -0,0 +1,12 @@ +/** 两阶段共用的确定性环境与像素比较策略。 */ +export const settings = { + viewport: { width: 1000, height: 800 }, + chart: { width: 800, height: 600 }, + deviceScaleFactor: 1, + locale: 'en-US', + timezoneId: 'UTC', + fontFamily: 'Arial', + timeout: 30000, + stableTimeout: 5000, + comparison: { threshold: 0.1, maxDiffPixels: 0 } +}; diff --git a/packages/vrender/__tests__/visual/visual.spec.mjs b/packages/vrender/__tests__/visual/visual.spec.mjs new file mode 100644 index 000000000..e70474638 --- /dev/null +++ b/packages/vrender/__tests__/visual/visual.spec.mjs @@ -0,0 +1,142 @@ +import fs from 'node:fs/promises'; +import { test, expect } from '@playwright/test'; +import { cases, loadCase } from './cases/index.mjs'; +import { settings } from './settings.mjs'; + +/** 等待两张连续截图完全一致;持续变化视为执行错误而非像素差异。 */ +async function stableScreenshot(page) { + let previous; + const deadline = Date.now() + settings.stableTimeout; + while (Date.now() < deadline) { + const current = await page.screenshot({ animations: 'disabled', timeout: 5000 }); + if (previous?.equals(current)) return current; + previous = current; + await page.waitForTimeout(100); + } + throw new Error('截图持续变化,5 秒内未稳定'); +} + +/** 检查渲染错误和有效画布内容,拒绝两侧同时空白造成的假通过。 */ +async function checkDrawing(page, errors) { + if (errors.length) throw new Error(errors.join('\n')); + await page.evaluate(() => { + // 图表绘制必须产生非透明、非白色像素。 + if (window.__visualErrors.length) throw new Error(window.__visualErrors.join('\n')); + const canvas = document.querySelector('#chart canvas'); + if (!canvas || canvas.width <= 0 || canvas.height <= 0) throw new Error('没有有效画布'); + const context = canvas.getContext('2d'); + const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data; + let ink = 0; + for (let i = 0; i < pixels.length; i += 4) + if (pixels[i + 3] && (pixels[i] < 245 || pixels[i + 1] < 245 || pixels[i + 2] < 245)) ink++; + if (ink < 100) throw new Error('图表没有有效绘制'); + }); +} + +const selectedIds = JSON.parse(process.env.VISUAL_CASE_IDS); +for (const metadata of cases.filter(item => selectedIds.includes(item.id))) { + const item = { ...metadata, ...(await loadCase(metadata)) }; + test(item.id, async ({ page, browser }, info) => { + // 记录来源和浏览器版本,并收集整个用例生命周期内的异常。 + info.annotations.push( + { type: 'purpose', description: item.purpose }, + { type: 'browser', description: browser.version() } + ); + const stage = { type: 'stage', description: 'resource' }; + info.annotations.push(stage); + const failure = { type: 'failure-category', description: '' }; + info.annotations.push(failure); + const errors = []; + const base = process.env.VISUAL_BASE_URL; + page.on('pageerror', error => { + failure.description = 'render'; + errors.push(error.message); + }); + page.on('requestfailed', request => { + failure.description = 'resource'; + errors.push(`资源失败:${request.url()} ${request.failure()?.errorText}`); + }); + page.on('response', response => { + if (response.status() >= 400) { + failure.description = 'resource'; + errors.push(`HTTP ${response.status()}:${response.url()}`); + } + }); + await page.route('**/*', route => { + // 截图阶段禁止 CDN 和内网请求。 + if (new URL(route.request().url()).origin === base) return route.continue(); + failure.description = 'resource'; + errors.push(`禁止外部请求:${route.request().url()}`); + return route.abort(); + }); + try { + await page.goto(`${base}/suite/page.html?phase=${process.env.VISUAL_PHASE}&case=${item.id}`); + stage.description = 'render'; + await page.waitForFunction(() => window.__visualReady || window.__visualErrors?.length); + await checkDrawing(page, errors); + stage.description = 'interaction'; + await item.exercise?.(page); + stage.description = item.exercise ? 'interaction' : 'verify'; + await item.verify(page); + stage.description = 'screenshot'; + await page.evaluate(() => document.fonts.ready); + const screenshot = await stableScreenshot(page); + await checkDrawing(page, errors); + const renderedPath = info.outputPath('rendered.png'); + await fs.writeFile(renderedPath, screenshot); + await info.attach('rendered', { path: renderedPath, contentType: 'image/png' }); + stage.description = 'comparison'; + const name = `${item.id}.png`; + if (process.env.VISUAL_PHASE === 'current') { + // 缺失基线必须在图片断言之前归类为执行错误。 + try { + await fs.access(info.snapshotPath(name)); + } catch (error) { + // 仅当完整基线记录明确复现业务断言失败时保留当前截图,交由后续调查。 + const baseline = JSON.parse(await fs.readFile(`${process.env.VISUAL_RUN_DIR}/baseline-result.json`, 'utf8')); + const previous = baseline.tests.find(test => test.id === item.id); + if ( + baseline.finalized && baseline.endedStatus === 'failed' && + !baseline.errors.length && + previous?.status === 'error' && previous.businessAssertion === true && + ['INTERACTION_ASSERTION_FAILED', 'CASE_ASSERTION_FAILED'].includes(previous.code) + ) + return; + failure.description = 'missing_artifact'; + throw error; + } + } + try { + expect(screenshot).toMatchSnapshot(name); + } catch (error) { + if (process.env.VISUAL_PHASE === 'current' && (await hasComparisonEvidence(info, name))) + await info.attach('visual-difference', { + body: Buffer.from('图像存在差异,请检查是否符合预期'), + contentType: 'text/plain' + }); + throw error; + } + } finally { + // 显式释放 Stage,浏览器 context 由 Playwright fixture 自动回收。 + await page.evaluate(() => window.__visualStage?.release()).catch(() => {}); + } + }); +} + +/** 只有原生比较生成完整 PNG 证据时才允许把断言失败归类为视觉差异。 */ +async function hasComparisonEvidence(info, name) { + const stem = name.slice(0, -4); + const dimensions = []; + for (const kind of ['expected', 'actual', 'diff']) { + const file = info.attachments.find(item => item.name === `${stem}-${kind}.png`)?.path; + if (!file) return false; + try { + const bytes = await fs.readFile(file); + if (bytes.length < 24 || bytes.subarray(0, 8).toString('hex') !== '89504e470d0a1a0a') return false; + dimensions.push(`${bytes.readUInt32BE(16)}x${bytes.readUInt32BE(20)}`); + } catch { + return false; + } + } + return new Set(dimensions).size === 1; +} diff --git a/packages/vrender/package.json b/packages/vrender/package.json index 940f48e2f..04318f3e9 100644 --- a/packages/vrender/package.json +++ b/packages/vrender/package.json @@ -8,8 +8,12 @@ "types": "es/index.d.ts", "typesVersions": { "*": { - "entries": ["es/entries/index.d.ts"], - "entries/*": ["es/entries/*"] + "entries": [ + "es/entries/index.d.ts" + ], + "entries/*": [ + "es/entries/*" + ] } }, "files": [ @@ -29,7 +33,9 @@ "test:electron": "jest -c jest.electron.config.js --runInBand --passWithNoTests --testPathPattern='__tests__/(browser|electron)/'", "test-cov": "jest -c jest.config.js -w 16 --coverage", "test-live": "npm run test-watch __tests__/unit/theme/line.test.ts", - "test-watch": "cross-env DEBUG_MODE=1 jest --watch -c jest.config.js" + "test-watch": "cross-env DEBUG_MODE=1 jest --watch -c jest.config.js", + "test:visual": "node scripts/visual-test.mjs", + "test:visual-runner": "node --test scripts/visual-test.test.mjs" }, "dependencies": { "@visactor/vrender-core": "workspace:1.1.14", @@ -58,7 +64,8 @@ "vite": "3.2.6", "typescript": "4.9.5", "zrender": "5.4.0", - "cross-env": "^7.0.3" + "cross-env": "^7.0.3", + "@playwright/test": "1.63.0" }, "keywords": [ "VisActor", diff --git a/packages/vrender/scripts/visual-negative.test.mjs b/packages/vrender/scripts/visual-negative.test.mjs new file mode 100644 index 000000000..bad1c986a --- /dev/null +++ b/packages/vrender/scripts/visual-negative.test.mjs @@ -0,0 +1,42 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import os from 'node:os'; +import { fileURLToPath } from 'node:url'; +import { createRuntime, serve } from './visual/runtime.mjs'; +import { executePhase } from './visual/runner.mjs'; + +// 仅消费已经通过的真实构建报告;受控污染发生在独立副本,不改源码或标准图。 +const source=process.env.VRENDER_VISUAL_FIXTURE; +const dependencies=process.env.VRENDER_VISUAL_DEPENDENCIES ?? path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'); +test('真实 PNG 差异和业务断言失败必须被检测', {skip: !source, timeout:120000}, async () => { + const original=JSON.parse(await fs.readFile(path.join(source,'summary.json'))); + assert.equal(original.status,'passed');assert.equal(original.complete,true); + const dir=await fs.mkdtemp(path.join(os.tmpdir(),'vrender-negative-')); + const runtime=createRuntime();const detach=runtime.listenSignals(); + try { + await fs.cp(path.join(source,'suite'),path.join(dir,'suite'),{recursive:true}); + for(const file of ['baseline.js','current.js']) await fs.copyFile(path.join(source,file),path.join(dir,file)); + await fs.symlink(path.join(dependencies,'packages/vrender/node_modules'),path.join(dir,'node_modules')); + const {server,url}=await serve(dir); + runtime.defer(async()=>{server.closeAllConnections();await new Promise(resolve=>server.close(resolve));}); + const ids=['primitives-text']; + assert.equal((await executePhase(dependencies,dir,'baseline',url,ids,runtime)).status,'passed'); + // 保持图元和语义不变,仅在当前 bundle 中加入可见标记,证明原生像素比较确实工作。 + await fs.appendFile(path.join(dir,'current.js'), '\nwindow.addEventListener("load",()=>{const marker=document.createElement("div");marker.style="position:absolute;left:700px;top:500px;width:40px;height:40px;background:red";document.body.append(marker)});\n'); + const changed=await executePhase(dependencies,dir,'current',url,ids,runtime); + assert.equal(changed.status,'diff');assert.equal(changed.tests[0].code,'VISUAL_DIFFERENCE'); + const images=changed.tests[0].attachments.filter(x=>x.name.endsWith('.png')); + for(const kind of ['expected','actual','diff']) assert(images.some(x=>x.name.includes(kind))); + await fs.copyFile(path.join(source,'current.js'),path.join(dir,'current.js')); + const file=path.join(dir,'suite/cases/primitives-text.mjs'); + await fs.writeFile(file,(await fs.readFile(file,'utf8')).replace('if (!ok)', 'if (true)')); + await assert.rejects(executePhase(dependencies,dir,'current',url,ids,runtime), /阶段执行失败/); + const failed=JSON.parse(await fs.readFile(path.join(dir,'current-result.json'))); + assert.equal(failed.status,'error');assert.equal(failed.tests[0].code,'CASE_ASSERTION_FAILED'); + console.log(JSON.stringify({visibleDifference:changed.status,assertionFailure:failed.tests[0].code,externalWrites:0})); + } finally { + const errors=await runtime.cleanup();detach();await fs.rm(dir,{recursive:true,force:true});assert.deepEqual(errors,[]); + } +}); diff --git a/packages/vrender/scripts/visual-test.mjs b/packages/vrender/scripts/visual-test.mjs new file mode 100644 index 000000000..5479a9754 --- /dev/null +++ b/packages/vrender/scripts/visual-test.mjs @@ -0,0 +1,92 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseArgs } from 'node:util'; +import { createRuntime, fault } from './visual/runtime.mjs'; +import { loadCases, preflight, runVisual } from './visual/runner.mjs'; + +/** 解析公共命令;帮助不加载 Playwright,非法选项仍明确报错。 */ +export function parseOptions(args) { + let values, tokens; + try { + ({ values, tokens } = parseArgs({ + args, + tokens: true, + options: { + baseline: { type: 'string' }, + offline: { type: 'boolean' }, + case: { type: 'string' }, + dir: { type: 'string' }, + 'self-compare': { type: 'boolean' }, + list: { type: 'boolean' }, + check: { type: 'boolean' }, + help: { type: 'boolean' } + } + })); + } catch (error) { + throw fault('INVALID_ARGUMENT', error.message, error); + } + if (values.help) return values; + if (tokens.filter(token => token.kind === 'option' && token.name === 'dir').length > 1) + throw fault('INVALID_ARGUMENT', '--dir 只能指定一次'); + if (values.dir !== undefined && !/^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/.test(values.dir)) + throw fault('INVALID_ARGUMENT', '--dir 需要 cases 内的相对目录,例如 components/label'); + if (values.dir !== undefined && values.case !== undefined) throw fault('INVALID_ARGUMENT', '--dir 与 --case 互斥'); + if ( + (values.list || values.check) && + ((values.list && values.check) || + values.baseline !== undefined || + values.offline || + values.case !== undefined || + values.dir !== undefined || + values['self-compare']) + ) + throw fault('INVALID_ARGUMENT', '--list/--check 必须独立使用'); + if (values.baseline !== undefined && !/^[a-f0-9]{40}$/i.test(values.baseline)) + throw fault('INVALID_ARGUMENT', '--baseline 需要完整 40 位 SHA'); + if (values.baseline && values['self-compare']) throw fault('INVALID_ARGUMENT', '--baseline 与 --self-compare 互斥'); + if (values.offline && !values.baseline) throw fault('INVALID_ARGUMENT', '--offline 需要已准备的 --baseline 完整 SHA'); + if (values.case !== undefined && !/^[a-z][a-z0-9-]*$/.test(values.case)) + throw fault('INVALID_ARGUMENT', '--case 需要有效用例 ID'); + return values; +} +/** 入口只管理参数、预检模式和运行生命周期。 */ +export async function main(configuration = {}) { + const { suitePath = 'packages/vrender/__tests__/visual', command = 'node packages/vrender/scripts/visual-test.mjs' } = + configuration; + const options = parseOptions(process.argv.slice(2)); + const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'); + if (options.help) { + console.log( + command + + ' [--baseline <40位SHA> [--offline] | --self-compare] [--dir <目录> | --case ]\n默认运行全部本地用例;--dir 递归运行 cases 内的一个目录(例如 components/label)。\n--offline 使用已准备提交与逐侧校验的依赖,不联网或安装。\n--list 列举用例;--check 本机环境检查;--help 帮助\n默认:官方 VisActor/VRender develop。退出码:0 通过,1 视觉差异,2 执行错误。' + ); + return; + } + if (options.list || options.check) { + const cases = await loadCases(path.join(root, suitePath)); + if (options.list) { + console.log( + cases.map(item => `${item.id}\t${item.purpose}\t${item.file}\t${item.sourceExample ?? ''}`).join('\n') + ); + return; + } + await fs.mkdir(path.join(root, '.vrender-visual'), { recursive: true }); + const runtime = createRuntime(); + const detach = runtime.listenSignals(); + try { + console.log(JSON.stringify({ status: 'passed', ...(await preflight(root, runtime)), cases: cases.length })); + } finally { + const errors = await runtime.cleanup(); + detach(); + if (errors.length) throw fault('CLEANUP_FAILED', JSON.stringify(errors)); + } + return; + } + process.exitCode = await runVisual(root, options, configuration); +} +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) + main().catch(error => { + console.error(`${error.code ?? 'EXECUTION_FAILED'}: ${error.message}`); + process.exitCode = 2; + }); diff --git a/packages/vrender/scripts/visual-test.test.mjs b/packages/vrender/scripts/visual-test.test.mjs new file mode 100644 index 000000000..7f2ac31b4 --- /dev/null +++ b/packages/vrender/scripts/visual-test.test.mjs @@ -0,0 +1,53 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { parseOptions } from './visual-test.mjs'; +import { loadCases, selectCases, validateResults, acquireLock } from './visual/runner.mjs'; +import { saveReport } from '../__tests__/visual/report.mjs'; +import Reporter from '../__tests__/visual/reporter.mjs'; + +const suite = fileURLToPath(new URL('../__tests__/visual', import.meta.url)); +test('首批清单恰好六项,非法参数和结果漏项/重复项拒绝', async () => { + const cases = await loadCases(suite); + assert.equal(cases.length, 6); + assert.equal(selectCases(cases, {case:'picking-events'})[0].id, 'picking-events'); + for (const args of [['--offline'], ['--baseline','abc'], ['--case','../x'], ['--update-snapshots'], ['--case','x','--dir','y']]) assert.throws(()=>parseOptions(args)); + assert.throws(()=>selectCases(cases,{case:'unknown'})); + for(const tests of [[],[{id:'a'},{id:'a'}],[{id:'b'}]]) assert.throws(()=>validateResults({tests},['a'])); + validateResults({tests:[{id:'a'}]},['a']); +}); + +test('运行锁互斥,缺少截图和未完成阶段不能判绿', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(),'vrender-report-')); + try { + const release=await acquireLock(dir,{runId:'test'}); + await assert.rejects(acquireLock(dir,{runId:'other'}));await release(); + const summary={runId:'test',finalized:true,status:'passed',cases:[{id:'a',purpose:'测试'}],issues:[],request:{},timings:{},environment:{},selection:{mode:'all',value:null,totalCount:1,selectedCount:1,selectedIds:['a']}}; + await saveReport(dir,summary); + const result=JSON.parse(await fs.readFile(path.join(dir,'summary.json'))); + assert.notEqual(result.status,'passed'); + assert.equal(result.complete,false); + } finally {await fs.rm(dir,{recursive:true,force:true});} +}); + +test('普通执行异常与显式业务断言分开,阶段超时保留错误', async () => { + const dir=await fs.mkdtemp(path.join(os.tmpdir(),'vrender-reporter-')); + const previous=[process.env.VISUAL_RUN_DIR,process.env.VISUAL_PHASE]; + process.env.VISUAL_RUN_DIR=dir;process.env.VISUAL_PHASE='current'; + try { + for (const [name,business] of [['Error',false],['VisualAssertionError',true]]) { + const reporter=new Reporter(); + reporter.onTestEnd({title:'a',annotations:[{type:'stage',description:'verify'}]}, {status:'failed',attachments:[],errors:[{name,message:'broken'}],duration:1}); + reporter.onEnd({status:'timedout'}); + const result=JSON.parse(await fs.readFile(path.join(dir,'current-result.json'))); + assert.equal(result.status,'error'); assert.equal(result.tests[0].businessAssertion,business); + assert.equal(result.tests[0].code,business?'CASE_ASSERTION_FAILED':'EXECUTION_FAILED'); + } + } finally { + for(const [i,key] of ['VISUAL_RUN_DIR','VISUAL_PHASE'].entries()) if(previous[i]===undefined) delete process.env[key];else process.env[key]=previous[i]; + await fs.rm(dir,{recursive:true,force:true}); + } +}); diff --git a/packages/vrender/scripts/visual/build.mjs b/packages/vrender/scripts/visual/build.mjs new file mode 100644 index 000000000..3d91daabe --- /dev/null +++ b/packages/vrender/scripts/visual/build.mjs @@ -0,0 +1,318 @@ +import { execFileSync } from 'node:child_process'; +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { digest, atomicJson, fault } from './runtime.mjs'; + +export const official = 'https://github.com/VisActor/VRender.git'; +const buildEnv = { NODE_ENV: 'production' }; + +/** 查询指定仓库,禁止改变分支、索引和远端配置。 */ +export function git(root, args) { + return execFileSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).trim(); +} +/** 包含未提交和未跟踪源码,不将忽略的生成产物纳入摘要。 */ +export async function workingTree(root) { + const status = git(root, ['status', '--short']); + // 使用完整对象哈希,避免 fetch 后 Git 自动延长缩写导致指纹误变。 + const patch = execFileSync('git', ['diff', 'HEAD', '--binary', '--full-index'], { + cwd: root, + maxBuffer: 64 * 1024 * 1024 + }); + const files = execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { + cwd: root, + encoding: 'utf8' + }) + .split('\0') + .filter(Boolean) + .sort(); + const untracked = []; + for (const file of files) { + const full = path.join(root, file); + const stat = await fs.lstat(full); + untracked.push([file, digest(stat.isSymbolicLink() ? await fs.readlink(full) : await fs.readFile(full))]); + } + return { + head: git(root, ['rev-parse', 'HEAD']), + dirty: Boolean(status), + status, + digest: digest(Buffer.concat([patch, Buffer.from(JSON.stringify(untracked))])) + }; +} +/** 从固定官方地址获取并固定提交;fork 的 origin 不参与解析。 */ +export async function resolveBaseline(root, sha, runtime, log) { + if (runtime.offline) { + try { + if (!/^[a-f0-9]{40}$/i.test(sha ?? '') || git(root, ['rev-parse', `${sha}^{commit}`]) !== sha.toLowerCase()) + throw new Error('提交不符'); + return sha.toLowerCase(); + } catch (error) { + throw fault('BASELINE_FETCH_FAILED', '离线基线提交缺失或不符', error); + } + } + await runtime.run('git', ['fetch', '--no-tags', official, sha || 'refs/heads/develop'], root, log, { + code: 'BASELINE_FETCH_FAILED' + }); + const resolved = git(root, ['rev-parse', 'FETCH_HEAD^{commit}']); + if (sha && resolved !== sha.toLowerCase()) throw fault('BASELINE_FETCH_FAILED', '基线 SHA 与请求不一致'); + return resolved; +} +/** 仅将源码工程清单和 Rush 配置纳入依赖契约。 */ +function isDependencyConfiguration(file) { + return ( + file === 'rush.json' || + file === 'package.json' || + file.endsWith('/package.json') || + file.startsWith('common/config/rush/') + ); +} +/** 核对工作区与指定提交的依赖配置;默认拒绝未提交变化,保留普通源码修改。 */ +export function assertOfflineDependencyConfiguration(root, reference = 'HEAD') { + const options = { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }; + const changed = [ + ...execFileSync( + 'git', + ['diff', '--no-ext-diff', '--no-textconv', '--name-only', '--no-renames', '-z', reference, '--'], + options + ).split('\0'), + ...execFileSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], options).split('\0') + ].find(isDependencyConfiguration); + if (changed) + throw fault( + 'DEPENDENCIES_CHANGED', + `离线依赖配置不同:${JSON.stringify(changed)};配置修改须先提交,并分别准备候选与基线依赖` + ); +} + +/** 逐侧核对完整源码配置集合、内容和边界,不依赖快照自身的 Git 元数据。 */ +export async function offlineConfiguration(root, sha, snapshot = process.env.VISUAL_BASELINE_DEPENDENCIES ?? root) { + const directory = await fs.realpath(snapshot); + // 复用实际工作区时还须比较双侧文件集合;别名和缓存命中不能绕过新增配置检查。 + if (directory === (await fs.realpath(root))) assertOfflineDependencyConfiguration(root, sha); + const files = new Set([ + 'rush.json', + 'common/config/rush/pnpm-lock.yaml', + ...git(root, ['ls-tree', '-r', '--name-only', '-z', sha]).split('\0').filter(isDependencyConfiguration) + ]); + const parents = new Set(), + projects = new Set(); + for (const file of files) { + if (file === 'package.json' || file.endsWith('/package.json')) projects.add(path.dirname(file)); + for (let parent = path.dirname(file); parent !== '.'; parent = path.dirname(parent)) parents.add(parent); + } + const generated = new Set([ + 'build', + 'build-es5', + 'dist', + 'es', + 'cjs', + 'lib', + 'output', + 'coverage', + '.next', + '.cache', + '.rollup.cache', + '.nyc_output', + 'rush-logs' + ]); + const actual = new Set(); + // 只使用固定产物排除规则;Rush 目录和冻结提交已有配置不受排除影响,不读取快照的 Git/ignore 策略。 + async function visit(relative, ancestors) { + const full = path.join(directory, relative), + real = await fs.realpath(full); + if (real !== directory && !real.startsWith(directory + path.sep)) + throw fault('DEPENDENCIES_CHANGED', '离线依赖配置不同:目录越界'); + if (ancestors.has(real)) throw fault('DEPENDENCIES_CHANGED', '离线依赖配置不同:目录循环引用'); + const next = new Set(ancestors).add(real); + for (const entry of await fs.readdir(full, { withFileTypes: true })) { + const name = path.join(relative, entry.name), + rush = name.startsWith('common/config/rush/'); + if ( + !rush && + !parents.has(name) && + (['.git', 'node_modules', '.rush', '.vrender-visual'].includes(entry.name) || + name === 'common/temp' || + (generated.has(entry.name) && (!relative || projects.has(relative)))) + ) + continue; + let kind = entry; + if (entry.isSymbolicLink()) { + const target = await fs.realpath(path.join(directory, name)); + if (!target.startsWith(directory + path.sep) && target !== directory) + throw fault('DEPENDENCIES_CHANGED', '离线依赖配置不同:链接越界'); + kind = await fs.stat(target); + } + if (kind.isDirectory()) await visit(name, next); + else if (isDependencyConfiguration(name)) { + if (!kind.isFile() || !files.has(name)) + throw fault('DEPENDENCIES_CHANGED', `离线快照包含额外或无效配置:${JSON.stringify(name)}`); + actual.add(name); + } + } + } + await visit('', new Set()); + const missing = [...files].find(file => !actual.has(file)); + if (missing) throw fault('DEPENDENCIES_CHANGED', `离线快照缺少配置:${JSON.stringify(missing)}`); + for (const file of files) { + const resolved = await fs.realpath(path.join(directory, file)); + if ( + !resolved.startsWith(directory + path.sep) || + !(await fs.readFile(resolved)).equals( + execFileSync('git', ['show', `${sha}:${file}`], { cwd: root, maxBuffer: 64 * 1024 * 1024 }) + ) + ) + throw fault('DEPENDENCIES_CHANGED', '离线依赖配置不同,需要按各侧提交分别准备后再运行'); + } + return directory; +} + +/** 复用只读第三方存储,复制每侧项目链接以解析到该侧源码,不执行安装。 */ +export async function offlineDependencies(root, worktree, sha) { + const directory = await offlineConfiguration(root, sha); + await fs.mkdir(path.join(worktree, 'common'), { recursive: true }); + await fs.symlink(path.join(directory, 'common/temp'), path.join(worktree, 'common/temp'), 'dir'); + const packages = git(worktree, ['ls-files', '--', 'package.json', '**/package.json']).split('\n').filter(Boolean); + for (const file of packages) { + const relative = path.join(path.dirname(file), 'node_modules'); + if ( + await fs + .stat(path.join(directory, relative)) + .catch(error => (error.code === 'ENOENT' ? null : Promise.reject(error))) + ) { + await fs.mkdir(path.dirname(path.join(worktree, relative)), { recursive: true }); + await fs.cp(await fs.realpath(path.join(directory, relative)), path.join(worktree, relative), { + recursive: true, + verbatimSymlinks: true + }); + } + } +} + +/** 执行既有最小构建链,仅删除已知且被忽略的 UMD 目标以排除旧文件。 */ +export async function build(root, destination, runtime, log) { + const output = 'packages/vrender/dist/index.js'; + if (git(root, ['ls-files', '--', output])) throw fault('BUILD_FAILED', '构建目标被 Git 跟踪,拒绝删除'); + try { + git(root, ['check-ignore', '--no-index', output]); + } catch { + throw fault('BUILD_FAILED', '构建目标不属于忽略的生成目录'); + } + await fs.rm(path.join(root, output), { force: true }); + const env = { + ...buildEnv, + ...(runtime.offline ? { NODE_OPTIONS: '--max-old-space-size=2048' } : {}), + NODE_PATH: path.join(root, 'tools/bundler/node_modules') + }; + await runtime.run(process.execPath, [path.join(root, 'common/scripts/install-run-rushx.js'), 'build'], + path.join(root, 'tools/bundler'), log, { code: 'BUILD_FAILED', env }); + // 各侧只构建冻结源码的包依赖链;主包 UMD 同时导出核心、动画和组件。 + for (const name of ['vrender-core', 'vrender-kits', 'vrender-animate', 'vrender-components', 'vrender']) { + await runtime.run(process.execPath, [path.join(root, 'tools/bundler/bin/index.js'), '-f', name === 'vrender' ? 'umd' : 'es', '--minify=false', '--ignorePostTasks'], + path.join(root, 'packages', name), log, { code: 'BUILD_FAILED', env }); + } + try { + if (!(await fs.stat(path.join(root, output))).size) throw new Error('构建产物为空'); + await fs.copyFile(path.join(root, output), destination); + } catch (error) { + throw fault('BUILD_FAILED', `没有生成有效的新产物:${error.message}`, error); + } +} +/** 验证缓存内容;损坏视为 miss,权限等真实 I/O 错误继续抛出。 */ +export async function readCache(cache, key) { + try { + const metadata = JSON.parse(await fs.readFile(path.join(cache, 'metadata.json'), 'utf8')); + if (metadata.key !== key) return null; + const bundle = await fs.readFile(path.join(cache, 'bundle.js')); + return bundle.length && digest(bundle) === metadata.digest ? bundle : null; + } catch (error) { + if (error.code === 'ENOENT' || error instanceof SyntaxError) return null; + throw error; + } +} +/** 在持有运行锁时发布完整缓存;新目录准备成功前保留旧缓存。 */ +export async function publishCache(cache, key, bundle) { + const temporary = await fs.mkdtemp(`${cache}-next-`); + const old = `${cache}-previous`; + try { + await fs.writeFile(path.join(temporary, 'bundle.js'), bundle); + await atomicJson(path.join(temporary, 'metadata.json'), { key, digest: digest(bundle) }); + await fs.rm(old, { recursive: true, force: true }); + try { + await fs.rename(cache, old); + } catch (error) { + if (error.code !== 'ENOENT') throw error; + } + try { + await fs.rename(temporary, cache); + } catch (error) { + try { + await fs.rename(old, cache); + } catch {} + throw error; + } + await fs.rm(old, { recursive: true, force: true }); + } finally { + await fs.rm(temporary, { recursive: true, force: true }); + } +} +/** 基线缓存只取决于构建输入;报告修改不使缓存失效。 */ +export async function baselineBuild( + root, + runDir, + sha, + runtime, + report, + timed, + { buildBundle = build, buildKey = '', outputDirectory = '.vrender-visual' } = {} +) { + if (runtime.offline) await offlineConfiguration(root, sha); + const log = path.join(runDir, 'build.log'); + const key = digest( + JSON.stringify({ + sha, + lock: git(root, ['show', `${sha}:common/config/rush/pnpm-lock.yaml`]), + node: process.version, + platform: process.platform, + arch: process.arch, + recipe: digest(await fs.readFile(fileURLToPath(import.meta.url))), + buildEnv, + buildKey, + tools: git(root, ['show', `${sha}:rush.json`]) + }) + ); + const cache = path.join(root, outputDirectory, 'baseline-cache'); + const cached = await readCache(cache, key); + if (cached) { + await fs.writeFile(path.join(runDir, 'baseline.js'), cached); + report.baseline.cacheHit = true; + return; + } + const worktree = path.join(runDir, 'worktree'); + runtime.defer(async () => { + // 清理不经已中断的命令调度器,仍有独立超时和错误记录。 + if ( + await fs.stat(worktree).catch(error => { + if (error.code === 'ENOENT') return null; + throw error; + }) + ) + execFileSync('git', ['worktree', 'remove', '--force', worktree], { cwd: root, stdio: 'pipe', timeout: 60000 }); + }); + await runtime.run('git', ['worktree', 'add', '--detach', worktree, sha], root, log, { code: 'BUILD_FAILED' }); + await timed('baselineInstallMs', () => + runtime.offline + ? offlineDependencies(root, worktree, sha) + : runtime.run( + process.execPath, + ['common/scripts/install-run-rush.js', 'install', '--ignore-hooks'], + worktree, + log, + { + code: 'BUILD_FAILED', + env: { NODE_ENV: 'development' } + } + ) + ); + await timed('baselineCompileMs', () => buildBundle(worktree, path.join(runDir, 'baseline.js'), runtime, log)); + await publishCache(cache, key, await fs.readFile(path.join(runDir, 'baseline.js'))); +} diff --git a/packages/vrender/scripts/visual/runner.mjs b/packages/vrender/scripts/visual/runner.mjs new file mode 100644 index 000000000..8a3c4d128 --- /dev/null +++ b/packages/vrender/scripts/visual/runner.mjs @@ -0,0 +1,419 @@ +import fs from 'node:fs/promises'; +import path from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { createRequire } from 'node:module'; +import { randomUUID } from 'node:crypto'; +import { createRuntime, serve, fault, digest, atomicJson, fileManifest } from './runtime.mjs'; +import { + git, + workingTree, + resolveBaseline, + build, + baselineBuild, + official, + offlineConfiguration, + assertOfflineDependencyConfiguration +} from './build.mjs'; +import { saveReport } from '../../__tests__/visual/report.mjs'; + +/** 验证元数据和可执行契约,只导入实际使用的清单目录。 */ +export async function loadCases(suite, caseId) { + try { + // 列举也检查全部目录,导入前拒绝父目录和辅助资源中的符号链接。 + if ((await fs.lstat(path.join(suite, 'cases'))).isSymbolicLink()) throw new Error('cases 不能为符号链接'); + await fileManifest(path.join(suite, 'cases')); + const { cases, loadCase } = await import(pathToFileURL(path.join(suite, 'cases/index.mjs'))); + if (!Array.isArray(cases) || !cases.length) throw new Error('用例清单为空'); + const ids = new Set(); + for (const item of cases) { + if (!/^[a-z][a-z0-9-]*$/.test(item.id) || ids.has(item.id)) throw new Error(`非法或重复 ID:${item.id}`); + ids.add(item.id); + if ( + !item.purpose || + (item.sourceExample !== undefined && (typeof item.sourceExample !== 'string' || !item.sourceExample.trim())) || + typeof item.file !== 'string' || + !/^\.\/([a-z][a-z0-9-]*\/)*[a-z][a-z0-9-]*\.mjs$/.test(item.file) + ) + throw new Error(`非法用例元数据:${item.id}`); + const file = path.join(suite, 'cases', item.file); + if ((await fs.lstat(file)).isSymbolicLink()) throw new Error(`用例不能为符号链接:${item.id}`); + const module = await loadCase(item); + if ( + typeof module?.createSpec !== 'function' || + typeof module.verify !== 'function' || + (module.exercise !== undefined && typeof module.exercise !== 'function') + ) + throw new Error(`非法用例导出:${item.id}`); + } + return selectCases(cases, { case: caseId }); + } catch (error) { + throw fault('CASE_MANIFEST_INVALID', error.message, error); + } +} +/** 从已验证的冻结清单选择准确范围;目录按层级匹配,不自动扩大或发现文件。 */ +export function selectCases(cases, options = {}) { + if (options.case !== undefined && options.dir !== undefined) throw fault('INVALID_ARGUMENT', '--dir 与 --case 互斥'); + if (options.dir !== undefined && !/^[a-z][a-z0-9-]*(\/[a-z][a-z0-9-]*)*$/.test(options.dir)) + throw fault('INVALID_ARGUMENT', '非法用例目录'); + const selected = cases.filter(item => + options.case !== undefined + ? item.id === options.case + : options.dir !== undefined + ? item.file.startsWith(`./${options.dir}/`) + : true + ); + if (!selected.length) throw fault('CASE_MANIFEST_INVALID', `没有匹配用例:${options.dir ?? options.case ?? '全部'}`); + return selected; +} +/** 延迟加载 Playwright,确保帮助和列举不依赖浏览器安装。 */ +export function playwright(root) { + try { + return createRequire(path.join(root, 'packages/vrender/package.json'))('@playwright/test'); + } catch (error) { + throw fault('PREFLIGHT_FAILED', '缺少 Playwright,请先执行 Rush install', error); + } +} +/** 检查本机依赖及浏览器实际启动能力,不下载、不修改依赖。 */ +export async function preflight(root, runtime) { + if (![22, 24].includes(Number(process.versions.node.split('.')[0])) || !['darwin', 'linux'].includes(process.platform)) + throw fault('PREFLIGHT_FAILED', '需要 Node.js 22/24 和 macOS/Linux'); + try { + git(root, ['--version']); + for (const folder of ['tools/bundler', 'packages/vrender']) { + const require = createRequire(path.join(root, folder, 'package.json')); + for (const dependency of folder === 'tools/bundler' + ? ['typescript'] + : ['@internal/bundler/package.json', '@visactor/vutils']) + require.resolve(dependency); + } + playwright(root); + await runtime.run( + process.execPath, + [ + '-e', + 'const {chromium}=require(process.argv[1]);(async()=>{const browser=await chromium.launch();await browser.close();})().catch(e=>{console.error(e);process.exitCode=2;});', + createRequire(path.join(root, 'packages/vrender/package.json')).resolve('@playwright/test') + ], + root, + path.join(root, '.vrender-visual/preflight.log'), + { code: 'PREFLIGHT_FAILED', timeoutMs: 30000 } + ); + return { + playwright: createRequire(path.join(root, 'packages/vrender/package.json'))('@playwright/test/package.json') + .version + }; + } catch (error) { + throw fault( + runtime.interrupted ? 'RUN_INTERRUPTED' : 'PREFLIGHT_FAILED', + `环境未就绪:${error.message}。依赖使用 Rush install;浏览器使用 Playwright install chromium。`, + error + ); + } +} +/** 精确校验结果集合,而非仅以数量相等视为完整。 */ +export function validateResults(result, ids) { + const found = result.tests?.map(item => item.id) ?? []; + if (found.length !== ids.length || new Set(found).size !== found.length || found.some(id => !ids.includes(id))) + throw fault('RESULT_SET_MISMATCH', '阶段结果与选中用例集合不一致'); +} +/** 运行冻结套件的一个阶段,保留已落盘的原始结果供失败汇总。 */ +export async function executePhase(root, runDir, phase, url, ids, runtime) { + const require = createRequire(path.join(root, 'packages/vrender/package.json')); + await fs.rm(path.join(runDir, `${phase}-result.json`), { force: true }); + const code = await runtime.run( + process.execPath, + [require.resolve('@playwright/test/cli'), 'test', '--config', path.join(runDir, 'suite/playwright.config.mjs')], + root, + path.join(runDir, `${phase}.log`), + { + allowFailure: true, + code: 'EXECUTION_FAILED', + env: { VISUAL_RUN_DIR: runDir, VISUAL_BASE_URL: url, VISUAL_PHASE: phase, VISUAL_CASE_IDS: JSON.stringify(ids) } + } + ); + let result; + try { + result = JSON.parse(await fs.readFile(path.join(runDir, `${phase}-result.json`), 'utf8')); + } catch (error) { + throw fault('RESULT_SET_MISMATCH', `${phase} 缺少有效阶段结果`, error); + } + validateResults(result, ids); + // 只有正常结束的旧版业务失败可继续;阶段超时/中断不能被已完成用例掩盖。 + const baselineAssertionFailure = + phase === 'baseline' && + result.status === 'error' && + result.tests.some(test => test.status === 'error') && + result.tests.every( + test => + test.status === 'passed' || + (test.status === 'error' && + test.businessAssertion === true && + ['INTERACTION_ASSERTION_FAILED', 'CASE_ASSERTION_FAILED'].includes(test.code)) + ); + // 同时核对 reporter 原始终态和进程退出码,拒绝缺失终态及相互矛盾的成功结果。 + const normalExit = + (result.endedStatus === 'passed' && result.status === 'passed' && code === 0) || + (result.endedStatus === 'failed' && code === 1 && (result.status === 'diff' || baselineAssertionFailure)); + if (result.finalized !== true || result.errors?.length || !normalExit) + throw fault( + 'EXECUTION_FAILED', + `${phase} 阶段执行失败(结束状态 ${ + result.endedStatus ?? 'missing' + },退出码 ${code}),请查看 ${phase}-result.json 和 ${phase}.log` + ); + return result; +} +/** 持有锁的运行才能释放锁,避免误删另一次运行。 */ +export async function acquireLock(output, owner) { + const lock = path.join(output, 'running.lock'); + try { + await fs.mkdir(lock); + } catch (error) { + if (error.code === 'EEXIST') throw fault('RUN_LOCKED', `存在运行锁:${lock};检查 owner.json 后再处理陈旧锁`); + throw error; + } + try { + await atomicJson(path.join(lock, 'owner.json'), owner); + } catch (error) { + await fs.rm(lock, { recursive: true, force: true }); + throw error; + } + return async () => { + // 只有身份相同才能清理,陈旧或未知锁不自动接管。 + const current = JSON.parse(await fs.readFile(path.join(lock, 'owner.json'), 'utf8')); + if (current.runId !== owner.runId) throw fault('CLEANUP_FAILED', '运行锁所有权已改变'); + await fs.rm(lock, { recursive: true, force: true }); + }; +} +/** 编排一次完整对比;所有准备失败和清理失败尽可能进入统一报告。 */ +export async function runVisual(root, options, configuration = {}) { + const { + suitePath = 'packages/vrender/__tests__/visual', + outputDirectory = '.vrender-visual', + buildBundle = build + } = configuration; + const runtime = createRuntime({ offline: options.offline === true }); + const detach = runtime.listenSignals(); + const output = path.join(root, outputDirectory); + const runId = `${Date.now()}-${randomUUID().slice(0, 8)}`; + const runDir = path.join(output, 'runs', runId); + const report = { + runId, + finalized: false, + status: 'error', + startedAt: new Date().toISOString(), + request: options, + command: configuration.command, + environment: { node: process.version, platform: process.platform, arch: process.arch }, + timings: {}, + cases: [], + issues: [], + stage: 'preparation' + }; + const started = performance.now(); + let releaseLock; + async function timed(name, action) { + // 失败阶段也记录耗时,便于诊断冷启动和中断。 + const start = performance.now(); + try { + return await action(); + } finally { + report.timings[name] = Math.round(performance.now() - start); + } + } + try { + await fs.mkdir(runDir, { recursive: true }); + console.log(`运行目录:${runDir}`); + await atomicJson(path.join(runDir, 'summary.json'), { + ...report, + schemaVersion: 1, + complete: false, + issues: [{ code: 'RUN_INCOMPLETE', message: '运行尚未完成' }] + }); + releaseLock = await acquireLock(output, { runId, pid: process.pid, startedAt: report.startedAt, runDir }); + const suite = path.join(runDir, 'suite'); + const source = path.join(root, suitePath); + await fs.mkdir(suite, { recursive: true }); + for (const file of [ + 'settings.mjs', + 'playwright.config.mjs', + 'visual.spec.mjs', + 'reporter.mjs', + 'assertions.mjs', + 'page.html' + ]) { + await fs.copyFile(path.join(root, 'packages/vrender/__tests__/visual', file), path.join(suite, file)); + } + await fileManifest(source); + await fs.cp(source, suite, { recursive: true }); + report.frozenFiles = await fileManifest(suite); + report.suiteDigest = digest(JSON.stringify(report.frozenFiles)); + const { settings } = await import(pathToFileURL(path.join(suite, 'settings.mjs'))); + report.comparison = settings.comparison; + report.environment = { + ...report.environment, + viewport: settings.viewport, + deviceScaleFactor: settings.deviceScaleFactor, + locale: settings.locale, + timezoneId: settings.timezoneId, + fontFamily: settings.fontFamily + }; + const allCases = await loadCases(suite); + const selected = selectCases(allCases, options); + report.selection = { + mode: options.dir !== undefined ? 'directory' : options.case !== undefined ? 'case' : 'all', + value: options.dir ?? options.case ?? null, + selectedIds: selected.map(item => item.id), + selectedCount: selected.length, + totalCount: allCases.length + }; + console.log(`测试范围:${report.selection.value ?? '全部本地用例'};选中 ${selected.length} / ${allCases.length}`); + report.cases = selected.map(({ id, purpose, file, sourceExample }) => ({ + id, + purpose, + sourceExample, + source: { + path: `${suitePath}/cases/${file.slice(2)}`, + line: 1, + frozenPath: `suite/cases/${file.slice(2)}` + } + })); + // 离线依赖必须匹配实际工作区;提前保存快照也覆盖预检期间的源码变化。 + if (runtime.offline) { + report.local = await workingTree(root); + assertOfflineDependencyConfiguration(root); + if (process.env.VISUAL_HEAD_DEPENDENCIES) + await offlineConfiguration(root, report.local.head, process.env.VISUAL_HEAD_DEPENDENCIES); + } + report.environment = { ...report.environment, ...(await timed('preflightMs', () => preflight(root, runtime))) }; + await fs.symlink(path.join(root, 'packages/vrender/node_modules'), path.join(runDir, 'node_modules'), 'dir'); + runtime.defer(() => fs.rm(path.join(runDir, 'node_modules'), { force: true })); + report.local ??= await workingTree(root); + report.stage = 'fetch'; + const log = path.join(runDir, 'build.log'); + const sha = options['self-compare'] + ? report.local.head + : await timed('fetchMs', () => resolveBaseline(root, options.baseline, runtime, log)); + report.baseline = { + repository: options['self-compare'] ? 'working-tree' : official, + requestedRef: options.baseline ?? (options['self-compare'] ? 'working-tree' : 'refs/heads/develop'), + sha, + cacheHit: false + }; + report.stage = 'localBuild'; + console.log('构建当前工作区…'); + await timed('localBuildMs', () => buildBundle(root, path.join(runDir, 'current.js'), runtime, log)); + const after = await workingTree(root); + if (after.head !== report.local.head || after.digest !== report.local.digest) + throw fault('WORKSPACE_CHANGED', '构建期间工作区或 HEAD 发生变化,请重跑'); + report.stage = 'baselineBuild'; + if (options['self-compare']) await fs.copyFile(path.join(runDir, 'current.js'), path.join(runDir, 'baseline.js')); + else await timed('baselineBuildMs', () => baselineBuild(root, runDir, sha, runtime, report, timed, configuration)); + report.bundles = { + baseline: digest(await fs.readFile(path.join(runDir, 'baseline.js'))), + current: digest(await fs.readFile(path.join(runDir, 'current.js'))) + }; + const { server, url } = await serve(runDir); + runtime.defer(async () => { + server.closeAllConnections(); + await new Promise(resolve => server.close(resolve)); + }); + const ids = selected.map(item => item.id); + for (const phase of ['baseline', 'current']) { + report.stage = phase; + console.log(`${phase} 截图…`); + report[`${phase}Result`] = await timed(`${phase}ScreenshotsMs`, () => + executePhase(root, runDir, phase, url, ids, runtime) + ); + } + report.status = report.currentResult.status; + } catch (error) { + report.status = 'error'; + const errorCode = error.visualError + ? error.code + : report.stage.endsWith('Build') + ? 'BUILD_FAILED' + : 'EXECUTION_FAILED'; + report.issues.push({ + phase: report.stage, + stage: report.stage, + category: 'execution', + code: errorCode, + message: error.stack ?? String(error) + }); + console.error(`${errorCode}: ${error.message}`); + } finally { + const cleanup = await timed('cleanupMs', () => runtime.cleanup()); + report.issues.push(...cleanup.map(issue => ({ ...issue, phase: 'cleanup', category: 'execution' }))); + if (runtime.interrupted) + report.issues.push({ + phase: report.stage, + category: 'execution', + code: 'RUN_INTERRUPTED', + message: '运行已中断' + }); + if (releaseLock) { + try { + await releaseLock(); + } catch (error) { + report.issues.push({ phase: 'cleanup', category: 'execution', code: 'CLEANUP_FAILED', message: String(error) }); + } + } + // 截图及清理期间也可能发生编辑,结束快照必须与构建输入一致。 + if (report.local) { + try { + report.localAfter = await workingTree(root); + if (report.local.head !== report.localAfter.head || report.local.digest !== report.localAfter.digest) + report.issues.push({ + phase: 'source', + category: 'execution', + code: 'WORKSPACE_CHANGED', + message: '检查前后源码或 HEAD 发生变化,请重跑' + }); + } catch (error) { + report.issues.push({ + phase: 'source', + category: 'execution', + code: 'SOURCE_SNAPSHOT_FAILED', + message: error.message + }); + } + } + detach(); + report.finalized = true; + report.timings.totalMs = Math.round(performance.now() - started); + } + try { + const final = await saveReport(runDir, report); + console.log(`结果:${final.status}\n报告:${path.join(runDir, 'index.html')}`); + return final.status === 'passed' ? 0 : final.status === 'diff' ? 1 : 2; + } catch (error) { + console.error(`REPORT_FAILED: ${error.message};原始证据:${runDir}`); + try { + let evidence = report; + try { + evidence = JSON.parse(await fs.readFile(path.join(runDir, 'summary.json'), 'utf8')); + } catch {} + await atomicJson(path.join(runDir, 'summary.json'), { + ...evidence, + finalized: true, + schemaVersion: 1, + status: 'error', + issues: [ + ...(evidence.issues ?? []), + { phase: 'report', category: 'execution', code: 'REPORT_FAILED', message: String(error) } + ] + }); + } catch {} + try { + await fs.rm(path.join(runDir, 'index.html'), { force: true }); + } catch {} + try { + await fs.writeFile( + path.join(runDir, 'agent-summary.md'), + '# 报告生成失败\n\n状态:error;code:REPORT_FAILED。请读取 summary.json 和阶段日志。\n' + ); + } catch {} + return 2; + } +} diff --git a/packages/vrender/scripts/visual/runtime.mjs b/packages/vrender/scripts/visual/runtime.mjs new file mode 100644 index 000000000..79f1d7ddc --- /dev/null +++ b/packages/vrender/scripts/visual/runtime.mjs @@ -0,0 +1,174 @@ +import { spawn } from 'node:child_process'; +import { createHash, randomUUID } from 'node:crypto'; +import { createServer } from 'node:http'; +import fs from 'node:fs/promises'; +import path from 'node:path'; + +/** 携带稳定错误码;错误消息保留具体失败证据。 */ +export function fault(code, message, cause) { + return Object.assign(new Error(message, cause ? { cause } : undefined), { code, visualError: true }); +} +/** 计算输入、产物和缓存的 SHA-256 摘要。 */ +export function digest(value) { + return createHash('sha256').update(value).digest('hex'); +} +/** 同目录写临时文件后替换,避免读到半份结果。 */ +export async function atomicJson(file, value) { + const temporary = `${file}.${randomUUID()}.tmp`; + try { + await fs.writeFile(temporary, JSON.stringify(value, null, 2)); + await fs.rename(temporary, file); + } finally { + await fs.rm(temporary, { force: true }); + } +} +/** 顺序尝试所有清理动作,单项失败不阻断后续回收。 */ +export async function cleanupAll(actions) { + const errors = []; + for (const action of actions.reverse()) { + try { + await action(); + } catch (error) { + errors.push({ code: 'CLEANUP_FAILED', message: String(error) }); + } + } + return errors; +} + +/** 管理单次运行的进程组;只有入口显式调用 listenSignals 才注册处理器。 */ +export function createRuntime({ offline = false } = {}) { + const children = new Set(); + const cleanups = []; + let interrupted = false; + let killTimer; + function stop(signal) { + // 仅向本次创建的进程组发送信号。 + for (const child of children) { + if (!child.pid) continue; + try { + process.kill(-child.pid, signal); + } catch (error) { + if (error.code !== 'ESRCH') throw error; + } + } + } + function interrupt() { + // 首先通知退出,三秒后强制终止未退出的子进程。 + interrupted = true; + stop('SIGTERM'); + killTimer ??= setTimeout(() => stop('SIGKILL'), 3000); + killTimer.unref(); + } + return { + offline, + get interrupted() { + return interrupted; + }, + defer(action) { + cleanups.push(action); + }, + listenSignals() { + // 返回移除函数,导入和完成运行后均不留下信号监听器。 + process.on('SIGINT', interrupt); + process.on('SIGTERM', interrupt); + return () => { + process.off('SIGINT', interrupt); + process.off('SIGTERM', interrupt); + clearTimeout(killTimer); + }; + }, + async run(command, args, cwd, log, options = {}) { + // 使用参数数组启动命令,保存日志;逾时或中断均为执行错误。 + if (interrupted) throw fault('RUN_INTERRUPTED', '测试已中断'); + const handle = await fs.open(log, 'a'); + let child, timer; + try { + await handle.write(`\n$ ${command} ${args.join(' ')}\n`); + child = spawn(command, args, { + cwd, + env: { + ...process.env, + PATH: `${path.dirname(process.execPath)}:${process.env.PATH}`, + CI: '1', + ...options.env + }, + detached: true, + stdio: ['ignore', handle.fd, handle.fd] + }); + children.add(child); + const code = await new Promise((resolve, reject) => { + child.once('error', reject); + child.once('exit', (code, signal) => resolve(signal ? 2 : code)); + timer = setTimeout(() => reject(fault('TIMEOUT', `命令超时:${log}`)), options.timeoutMs ?? 1200000); + }); + if (interrupted) throw fault('RUN_INTERRUPTED', `运行已中断:${log}`); + if (code !== 0 && !options.allowFailure) + throw fault(options.code ?? 'EXECUTION_FAILED', `命令执行失败 (${code}),请查看 ${log}`); + return code; + } catch (error) { + if (error.visualError) throw error; + throw fault(options.code ?? 'EXECUTION_FAILED', `${error.message};日志:${log}`, error); + } finally { + clearTimeout(timer); + if (child?.pid) { + try { + process.kill(-child.pid, 'SIGKILL'); + } catch {} + } + children.delete(child); + await handle.close(); + } + }, + async cleanup() { + // 即使某个清理函数失败,也继续回收剩余资源。 + const errors = []; + try { + stop('SIGKILL'); + } catch (error) { + errors.push({ code: 'CLEANUP_FAILED', message: String(error) }); + } + errors.push(...(await cleanupAll(cleanups))); + cleanups.length = 0; + return errors; + } + }; +} + +/** 仅暴露冻结套件与两侧构建,使用回环地址及系统分配端口。 */ +export async function serve(runDir) { + const server = createServer(async (request, response) => { + try { + const relative = decodeURIComponent(new URL(request.url, 'http://localhost').pathname).slice(1); + if (!/^(suite\/|baseline\.js$|current\.js$)/.test(relative) || relative.split(/[\\/]/).includes('..')) + return response.writeHead(404).end(); + const resolved = await fs.realpath(path.join(runDir, relative)); + if (!resolved.startsWith(`${await fs.realpath(runDir)}${path.sep}`)) return response.writeHead(404).end(); + const content = await fs.readFile(resolved); + response.writeHead(200, { + 'Content-Type': relative.endsWith('.html') ? 'text/html' : 'text/javascript', + 'Cache-Control': 'no-store' + }); + response.end(content); + } catch { + response.writeHead(404).end(); + } + }); + await new Promise((resolve, reject) => { + server.once('error', reject); + server.listen(0, '127.0.0.1', resolve); + }); + return { server, url: `http://127.0.0.1:${server.address().port}` }; +} + +/** 按相对路径递归冻结代码资源,不跟随符号链接到工作区外。 */ +export async function fileManifest(directory, relative = '') { + const entries = []; + for (const name of (await fs.readdir(path.join(directory, relative))).sort()) { + const file = path.posix.join(relative, name); + const stat = await fs.lstat(path.join(directory, file)); + if (stat.isSymbolicLink()) throw fault('CASE_MANIFEST_INVALID', `冻结输入不能包含符号链接:${file}`); + if (stat.isDirectory()) entries.push(...(await fileManifest(directory, file))); + else if (stat.isFile()) entries.push({ path: file, digest: digest(await fs.readFile(path.join(directory, file))) }); + } + return entries; +}