From a81a687cc773140329eecff23424614dd3ecfdab Mon Sep 17 00:00:00 2001 From: Rui-Sun Date: Fri, 6 Nov 2026 22:46:45 +0800 Subject: [PATCH 1/2] docs: complete VSeed workflow and contribution guides --- .github/PULL_REQUEST_TEMPLATE.md | 12 ++- .github/PULL_REQUEST_TEMPLATE/pr_cn.md | 10 ++- AGENTS.md | 9 +++ CONTRIBUTING.md | 80 +++++++++++++++++++ CONTRIBUTING.zh-CN.md | 80 +++++++++++++++++++ README.md | 4 + packages/vseed/README.md | 2 +- .../visual/BUGSERVER_CASE_WORKFLOW.md | 33 ++++++++ packages/vseed/__tests__/visual/README.md | 17 +++- .../vseed/__tests__/visual/cases/README.md | 32 ++++++++ 10 files changed, 273 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.zh-CN.md create mode 100644 packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md create mode 100644 packages/vseed/__tests__/visual/cases/README.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 2e1f16065d..a170ec3b4d 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,7 +6,7 @@ Your pull requests will be merged after one of the collaborators approve. Thank you! --> -[[中文版模板 / Chinese template](https://github.com/VisActor/VChart/blob/main/.github/PULL_REQUEST_TEMPLATE/pr_cn.md?plain=1)] +[中文版模板 / Chinese template](./PULL_REQUEST_TEMPLATE/pr_cn.md) ### 🤔 This is a ... @@ -40,7 +40,7 @@ Thank you! ### 🐞 Bugserver case id - +Only provide confirmed, public-safe case IDs. If unavailable, state that a product administrator must supply them. Only that product’s administrators may create cases; never use empty, placeholder or invented IDs. [Collaboration guide](../packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md) (Chinese). ### 💡 Background and solution @@ -52,6 +52,14 @@ Thank you! ### ☑️ Self-Check before Merge +Read [PR checks and merge process](../CONTRIBUTING.md#pr-checks-and-merge-process). Target `main`; the advisory workflow accepts eligible same-repository, non-draft PRs created after 2026-11-06 22:05 Asia/Shanghai and touching packages/vseed/. + +- [ ] Reported actual commands, outcomes, report scope and skipped checks/reasons. +- [ ] Ran relevant unit tests and full official-baseline comparison for product/dependency/case changes, or explained documentation-only applicability. Self-comparison is not a two-sided pass. +- [ ] Described expected visual changes and regression coverage; retained execution errors and blockers. + +Photo needs maintainer review. Report-only/completed is not an all-Photo pass; approval is tied to the current commit and never automatically merges or updates baselines. + ⚠️ Please check all items below before requesting a reviewing. ⚠️ - [ ] Doc is updated/provided or not needed diff --git a/.github/PULL_REQUEST_TEMPLATE/pr_cn.md b/.github/PULL_REQUEST_TEMPLATE/pr_cn.md index 3ce2677743..333fa17c29 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pr_cn.md +++ b/.github/PULL_REQUEST_TEMPLATE/pr_cn.md @@ -38,7 +38,7 @@ ### 🐞 Bugserver 用例 id - +仅填写已确认存在且可公开的真实caseId;无权限或未创建时注明“待项目管理员补充”。只有对应产品管理员可新增,禁止空值/占位/虚构ID。[协作流程](../../packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md)。 ### 💡 问题的背景&解决方案 @@ -50,6 +50,14 @@ ### ☑️ 自测 +请阅读[PR检查与合入流程](../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程)。目标为main;同仓、涉及packages/vseed/且在2026-11-06 22:05北京时间起点后新建的非Draft PR可接入。 + +- [ ] 已填写实际测试命令、结果、报告范围和未运行项/原因。 +- [ ] 产品/依赖/用例变更已完成相关单测及默认全量基线比较;纯文档说明不适用。自比较不能代替双侧通过。 +- [ ] 已说明预期视觉变化及新增/修改的回归用例;执行错误和阻断如实保留。 + +Photo由维护者人工核查,report-only/流程完成不等于Photo全通过;批准绑定当前提交,不自动Merge或更新基准。 + ⚠️ 在提交 PR 之前,请检查一下内容. ⚠️ - [ ] 文档提供了,或者更新,或者不需要 diff --git a/AGENTS.md b/AGENTS.md index bd4157843e..50fc6cbcc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,3 +25,12 @@ Use `.agents/skills/development/SKILL.md` for code, test, build, or dependency c Skip it for changes limited to skills, prompts, or agent instructions. Skill documents and references describe current capabilities, usage, and constraints without narrating past changes, removals, or migrations. + +## PR and visual verification + +- Read [Contributing](./CONTRIBUTING.md#pr-checks-and-merge-process) before submitting. The VSeed advisory workflow is enabled for eligible new same-repository main PRs touching `packages/vseed/`; stable CR has a wider scope. +- Product, dependency and visual-case changes require relevant unit tests and the default full official-main visual comparison: `node packages/vseed/scripts/visual-test.mjs`. Preserve the development skill's coverage, generation and website checks. Markdown/agent-guidance-only changes require document/link validation and an explicit not-run explanation. +- Add or strengthen deterministic regression cases for features, fixes and gaps. Follow the [case guide](./packages/vseed/__tests__/visual/cases/README.md); real interactions need semantic assertions. Self-comparison is not a baseline pass. Do not relax thresholds, skip cases or hide errors. +- Follow the [Photo collaboration guide](./packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md). Local cases do not sync to BugServer; only product administrators create platform cases, and IDs must be real. +- Check current head/base and report scope before using Bot results. Photo is report-only and manually reviewed; completed does not mean all Photo tests passed. Never approve/merge, edit managed summaries/markers, automatically update baselines or bypass unknown-request deduplication. +- Stop test servers, browsers and child processes you started when finished. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..4e6aec5e86 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing + +[简体中文](./CONTRIBUTING.zh-CN.md) + +The canonical repository is [VisActor/VBI](https://github.com/VisActor/VBI); VSeed lives in `packages/vseed`. The old VisActor/VSeed address is not a second workflow entry. Branch from `main` and target `main`. Use [Issues](https://github.com/VisActor/VBI/issues) for problems and proposals, the English/Chinese PR templates for submissions, and Conventional Commits. + +## Local development and validation + +Use Node.js >=24.12.0 and pnpm10.26.1 as specified by root package.json. Code, test, build and dependency changes follow the [development guidelines](.agents/skills/development/SKILL.md), including existing coverage, generation and website acceptance requirements. + +```sh +pnpm install --frozen-lockfile +# Record affected-package unit coverage before changes; VSeed example: +pnpm --filter @visactor/vseed run test:unit:coverage +# After changes, generate and run complete tests, coverage and checks: +pnpm --filter @visactor/vseed run g +pnpm --filter @visactor/vseed run test:coverage +pnpm --filter @visactor/vseed run test:unit:coverage +pnpm run format:check +pnpm run lint:check +pnpm run typecheck +``` + +Include all affected packages and consumers; use `pnpm run g` for repository-wide generation. Compare statements, branches, functions and lines per package with the same source scope. No metric may decrease; full-suite coverage does not replace the unit-only baseline. VBI/VQuery retain 100% in all four metrics. Inspect generated and snapshot diffs rather than accepting behavior changes blindly. Product CI runs `pnpm run build` and `pnpm run test:coverage`; existing Lint, Typecheck and changeset checks also apply. + +For code changes, follow the development guidelines to inspect the website home page and affected examples, exercise real interactions, and check console/network errors. Stop the `pnpm dev` server afterward. Website acceptance does not replace VSeed's frozen two-sided comparison below. Markdown/agent-guidance-only changes require document and link checks, not product builds, coverage reruns or a website server; changes to generators, examples or site behavior require the corresponding development checks. + +## PR checks and merge process + +**Activation snapshot (2026-11-06):** the advisory workflow was enabled at **2026-11-06 22:05 Asia/Shanghai (UTC+8)**. Integration: [#595](https://github.com/VisActor/VBI/pull/595). Activation and a designated PR validation do not establish long-term reliability; the first natural PR and at least 24 hours/3 natural executions remain to be observed. + +### Scope + +The workflow handles non-draft PRs created after initialization and strictly after the cutoff, with both branches in `VisActor/VBI`, targeting `main` and whose complete diff touches `packages/vseed/` (including renames or deletions). “Internal” means same-repository branches, not employee status. Eligible new drafts enter after Ready for review. Existing PRs, forks and out-of-scope PRs are not backfilled by updates, reopening or changing draft status. Do not recreate a PR to bypass this boundary. + +Stable CR and GitHub Actions have independent scopes. Stable CR covers new and revised non-draft PRs across the repository after its initial baseline; the advisory workflow's branch and path restrictions do not narrow CR. Missing workflow output does not waive tests or human review. Legacy Photo CI handles unclaimed PRs and push events only under its existing triggers; maintainers coordinate screenshot ownership, so do not dispatch a duplicate batch. + +### Before submitting + +- Run relevant unit tests, build/type and style checks. For features, fixes or coverage gaps, add deterministic regression cases or strengthen existing ones. Interactions must exercise real actions and assert the resulting state. +- For product, rendering, interaction, dependency or visual-case changes, run the default full comparison in the [visual guide](packages/vseed/__tests__/visual/README.md) before submitting. Focused cases/directories help during development; self-comparison only checks determinism and cannot replace the official baseline comparison. “Full” means the current manifest, not all product behavior. +- For documentation-only changes, check links, commands, versions and actual behavior. Explain why product tests were not run; do not manually rerun models or dispatch Photo just for documentation. Existing CI and automated workflow triggers still apply after submission. +- Report commands, outcomes, report scope, head/base when available, expected visual changes, skipped checks and blockers. Errors are not passes. Do not skip assertions, relax thresholds or replace baselines to hide failures. +- Follow the [case authoring guide](packages/vseed/__tests__/visual/cases/README.md). Only administrators of the corresponding product may create platform cases; other contributors supply reproduction material. Never invent IDs. See [BugServer case collaboration](packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md) (Chinese). + +### After submitting + +Check the current head, comparison base and report version before reading the Bot Review, Actions runs and PR summary. The three automated recommendations are CR, unit tests and Playwright; other repository CI checks may also apply. + +| Result | Action | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| CR Review | Fix findings or provide evidence; closing a discussion does not prove a fix | +| Unit tests | Check `test.yml`, the `Tests` job and `Run tests and enforce coverage thresholds`; also check Lint and Typecheck; missing, skipped, running or failed results are not passes | +| Playwright | Inspect full comparison images, assertions and difference analysis; execution errors are not acceptable visual changes | +| BugServer Photo | Automatically executed, manually reviewed, report-only; differences, missing baselines, errors and incomplete results remain visible without blocking the three recommendations | + +Passing all three checks or reaching completed does not mean every Photo test passed. Contributors without platform access should request maintainer help; do not publish internal reports, business data, private logs or credentials. + +### Status and next action + +| Summary status | Action | +| --------------------------------- | ---------------------------------------------------------------------------------------------- | +| Queued / running | Wait for the current stage; no result is not a pass | +| Changes or investigation needed | Fix the issue, add coverage or provide verifiable evidence | +| Blocked | Read the action item; ask maintainers about permissions, services or recovery | +| Awaiting approval | Maintainer checks all three results and manually reviews Photo for the current revision | +| Awaiting merge | A valid current-commit approval was recognized; a maintainer merges manually | +| Merged / baseline processing | Wait for cleanup; skipping automatic baseline updates is expected in report-only mode | +| Completed | Workflow cleanup finished; original Photo differences and errors remain | +| Superseded / closed without merge | Read the new revision's result, or treat the PR as unmerged; neither implies a baseline update | + +A new head or comparison base requires version checks and necessary reruns. Old results cannot prove the new revision passed; a new commit needs its own valid approval. If a summary is missing, check repository, target, creation time, draft status and changed paths before contacting maintainers. + +### Approval, merge and recovery + +The workflow recognizes a valid GitHub Approve from a repository Maintain/Admin user for the **current commit**, including their manual Photo verification. The Bot never approves or merges. GitHub protection rules and other checks still apply; the workflow does not add required Checks or change branch protection. + +Automatic Photo difference assessment and baseline updates are paused. Approve/Merge does not authorize automatic adoption of screenshots. Early merge does not turn incomplete or failed checks into passes. Shared baseline changes require separate explicit authorization, administrator review and a new verification; retain original reports. + +For help, provide the PR, current SHA, Review/CI links and a public-safe error description. Do not edit managed summaries or hidden markers, repeatedly reopen PRs, delete state, change request IDs or dispatch duplicate batches. Maintainers recover the original task. Stop test servers, browsers and child processes you started when finished. diff --git a/CONTRIBUTING.zh-CN.md b/CONTRIBUTING.zh-CN.md new file mode 100644 index 0000000000..a5371ead93 --- /dev/null +++ b/CONTRIBUTING.zh-CN.md @@ -0,0 +1,80 @@ +# 贡献指南 + +[English](./CONTRIBUTING.md) + +规范仓库为 [VisActor/VBI](https://github.com/VisActor/VBI),VSeed 是其中 `packages/vseed` 包;旧 VisActor/VSeed 地址不作为第二个工作流入口。从 `main` 创建分支,PR 目标为 `main`。问题与功能讨论使用 [Issues](https://github.com/VisActor/VBI/issues),PR 遵循中英文模板,使用 Conventional Commits。 + +## 本地开发与验证 + +使用根 package.json 指定的 Node.js >=24.12.0 和 pnpm10.26.1。代码、测试、构建及依赖变更遵循[开发规范](.agents/skills/development/SKILL.md),本指南不降低既有覆盖率、生成和网站验收要求。 + +```sh +pnpm install --frozen-lockfile +# 修改前记录受影响包的单测覆盖率;以下为 VSeed 示例 +pnpm --filter @visactor/vseed run test:unit:coverage +# 修改后执行生成、完整测试、覆盖率和代码检查 +pnpm --filter @visactor/vseed run g +pnpm --filter @visactor/vseed run test:coverage +pnpm --filter @visactor/vseed run test:unit:coverage +pnpm run format:check +pnpm run lint:check +pnpm run typecheck +``` + +按改动选择所有受影响包及消费者,仓库范围生成使用 `pnpm run g`。逐包比较同一源码范围的 statements/branches/functions/lines,不能降低覆盖率;完整测试不能替代单测基线比较。VBI/VQuery保留四项100%要求。检查生成和快照diff,不用自动更新快照掩盖行为变化。产品CI使用 `pnpm run build` 和 `pnpm run test:coverage`;现有Lint、Typecheck和changeset检查也须满足。 + +代码变更还需按开发规范检查网站首页及相关示例,执行真实交互并核对控制台和请求;启动的 `pnpm dev` 服务在完成后停止。网站验收不替代下面的VSeed冻结双侧视觉比较。纯Markdown/Agent说明变更检查文档本身及链接,无需重跑产品构建、覆盖率或启动网站;若同时修改生成器、示例或网站行为,按开发规范执行对应验收。 + +## PR 检查与合入流程 + +**正式启用快照(2026-11-06)**:本仓独立 PR 工作流已于北京时间 **2026-11-06 22:05** 启用。接入代码见 [#595](https://github.com/VisActor/VBI/pull/595)。启用和指定 PR 验证不等于长期稳定性验收,首条自然 PR 及至少24小时/3次执行观察仍待完成。 + +### 适用范围 + +仅接管完成初始化后、创建时间严格晚于起点、源分支和目标分支均属于 `VisActor/VBI`、目标为 `main`且完整差异涉及 `packages/vseed/`(包括改名或删除)的非 Draft PR。“内部”指同仓分支,不以作者是否为员工判断。符合条件的新 Draft 转为 Ready for review 后进入流程;初始化前的存量 PR、fork 和范围外 PR 不因更新、重开或转 Ready 而自动补跑。不要重新创建相同 PR 来绕过存量边界。 + +稳定 CR 与 GitHub Actions 有独立范围:稳定 CR 已启用全仓非 Draft PR 的新建及后续版本自动审查,首次建立存量基线;它不受独立工作流的目标分支和路径范围限制。没有工作流摘要不代表不需要测试或人工评审。旧 Photo CI 仅按自己的触发条件处理未交接 PR 和 push;同一版本的截图所有权由维护者协调,不手动重复派发。 + +### 提交前检查 + +- 完成改动相关的单测、构建/类型及代码风格检查。新增功能、修复缺陷或发现覆盖空缺时,补充确定性回归用例或加强已有用例;交互必须验证真实动作和目标状态。 +- 涉及产品代码、渲染、交互、依赖或视觉用例时,提交 PR 前运行[视觉指南](packages/vseed/__tests__/visual/README.md)中的默认全量双侧比较。开发过程中可运行单例/相关目录;`--self-compare` 只检查稳定性,不能替代官方基线比较。全量仅指当前用例清单,不代表全产品覆盖。 +- 纯文档改动核对链接、命令、版本和实际行为即可;在 PR 中说明未运行产品测试及原因,无需手动启动模型或派发 Photo;提交后仍按仓库既有 CI 和自动工作流执行。 +- 写清实际命令、结果、报告范围、head/base(如已生成报告)、预期视觉变化、未运行项及阻断。执行错误不能算通过,不跳过断言、放宽阈值或替换基准来消除失败。 +- 新增本地用例见[用例指南](packages/vseed/__tests__/visual/cases/README.md)。新增平台 Photo 用例仅限对应项目管理员;无权限者提供复现材料,不能编造 ID,流程见[BugServer 用例协作](packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md)。 + +### 提交后检查结果 + +先核对当前 head、比较基线和报告版本,再检查 Bot Review、GitHub Actions 和 PR 工作流摘要。三项自动建议分别为 CR、单测和 Playwright;CI 仍可能有其他必须满足的仓库检查。 + +| 检查项 | 开发者和维护者的动作 | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| CR Review | 阅读对应源码位置,修复或补充证据;关闭讨论不等于已验证修复 | +| 单测 | 核对 `test.yml` 的 `Tests` job 和 `Run tests and enforce coverage thresholds` 步骤;同时检查 Lint、Typecheck;缺失、跳过、运行中或失败不能算通过 | +| Playwright | 查看全量比较及图像、业务断言和差异调查;执行错误不能归为可接受视觉变化 | +| BugServer Photo | 自动执行、人工核查,保留差异、缺基准、错误和未完成状态;当前 report-only,不阻断三项自动建议 | + +三项检查通过或流程 completed 都不表示 Photo 全部通过。无平台权限的贡献者由维护者协助核查,不公开内部报告、业务数据、日志或凭据。 + +### PR 状态与下一步 + +| 摘要状态 | 应采取的行动 | +| ------------------------ | ---------------------------------------------------- | +| 等待执行/执行中 | 等待当前阶段,不把暂无结果当通过 | +| 存在待修复或待调查项 | 阅读问题,修复代码、补用例或提供可验证证据 | +| 流程受阻 | 查看具体待办;权限、服务或任务恢复问题交由维护者处理 | +| 等待人工批准 | 维护者核对当前版本的三项结果,并人工核查 Photo | +| 等待人工合入 | 当前提交的有效批准已识别,由维护者人工 Merge | +| 已合入/核对基准阶段 | 等待收尾;report-only 下跳过自动基准更新是预期行为 | +| 流程已完成 | 表示流程收尾,不改写原 Photo 差异或错误 | +| 被新版本替代/未合入关闭 | 前者查看新版本结果,后者不表示已合入或基准已更新 | + +推送新提交或 base 变化后重新核对版本并执行必要检查;旧结果不能证明新版本通过,新提交需要对应的有效批准。缺少摘要时先检查同仓、目标、创建时间、Draft和路径范围,再联系维护者。 + +### 批准、合入和异常恢复 + +工作流识别具有仓库 Maintain/Admin 权限的维护者对**当前提交**作出的有效 GitHub Approve,该批准同时表示已人工核查 Photo。Bot 不自动 Approve/Merge;GitHub 分支保护和其他检查仍适用,工作流不新增强制 Checks 或修改仓库规则。 + +Photo 自动差异评估及标准图自动更新暂停。Approve/Merge 不授权自动采用测试图;提前合入不会使未完成或失败的检查变为通过。新增/修改共享基准需管理员另行获得明确授权、人工核查并安排复验,原报告保留。 + +请求帮助时提供 PR、当前 SHA、Review/CI 链接和可公开的错误说明。不要编辑 Bot 受管摘要或隐藏标记,不通过反复开关 PR、删除状态、换请求 ID 或另派批次绕过去重;由维护者回读和恢复原任务。结束时停止本次启动的测试服务、浏览器和子进程。 diff --git a/README.md b/README.md index 55e225f954..09a8734b70 100644 --- a/README.md +++ b/README.md @@ -35,3 +35,7 @@ Install the VBI skill for coding agents: ```bash npx skills add visactor/vbi ``` + +## Contributing and PR workflow + +Read [Contributing](./CONTRIBUTING.md) / [贡献指南](./CONTRIBUTING.zh-CN.md) for local checks, VSeed case authoring, the enabled workflow's scope and cutoff, PR states, manual Photo review, and approval/merge. Start visual testing from the [VSeed guide](./packages/vseed/__tests__/visual/README.md). diff --git a/packages/vseed/README.md b/packages/vseed/README.md index f8db06a7c1..c3ca84d195 100644 --- a/packages/vseed/README.md +++ b/packages/vseed/README.md @@ -1,3 +1,3 @@ # VSeed -[视觉回归与 AI 工作流接入](./__tests__/visual/README.md) +[视觉回归与用例编写](./__tests__/visual/README.md) · [PR检查与合入流程](../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程) diff --git a/packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md b/packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md new file mode 100644 index 0000000000..b62d2bfca6 --- /dev/null +++ b/packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md @@ -0,0 +1,33 @@ +# BugServer Photo 用例协作 + +只有对应 BugServer 产品的项目管理员可新增平台用例;GitHub写权限、平台登录或报告读取权限不等于创建权限。无权限的贡献者提供复现材料,由管理员处理,不共享账号或令牌。本地Playwright与平台Photo是两套用例,不自动同步。 + +## 1. 提供材料并检查已有覆盖 + +按[本地用例指南](./cases/README.md)补充可复现测试,提供关联PR/issue、当前提交SHA、验证目的、固定公开数据、动作顺序、预期状态、本地用例路径与实际结果。管理员查找对应产品的已有目录和相似case,优先复用。未创建时在PR注明“待项目管理员补充”,不编造caseId。 + +## 2. 管理员创建并回读 + +本仓产品为 `VSeed`,规范GitHub仓库为 `VisActor/VBI`。管理员先核对产品、环境和自身权限,通过团队支持的平台或CLI创建。将场景适配为平台浏览器环境的JavaScript;不能直接上传含Playwright/Jest API的本地模块。保留必要动作和状态验证,等待资源及目标状态就绪后再请求截图;需要交互时按平台交互配置维护。 + +创建后保存真实caseId、目录、请求标识和返回链接,回读核对内容。创建成功只表示已保存,不代表已运行或已有标准图。结果未知时保留同一请求标识和输入,联系管理员回读原请求;不要换ID重复创建。公开仓库只保存可公开的材料、ID和链接,内部内容通过受限渠道交接。 + +## 3. 回填并在新版本验证 + +确认创建成功后,在相关本地用例的追溯注释及PR中填写真实ID,并提交必要的用例/说明变更,形成真实新版本。平台caseId仅供追溯,不建立同步关系,也不按PR填写的ID筛选Photo。 + +只有符合[正式准入范围](../../../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程)的PR由工作流自动推进。Photo阶段冻结对应产品全部Photo用例及其交互;已冻结集合/旧批次不会因新增case扩容。刷新页面或重试旧批次不能证明新增case已执行。前置检查或构建受阻时先处理阻断,不手动另派批次冒充工作流结果。存量、fork、范围外或已合入PR,由管理员安排独立验证或后续真实变更PR。 + +## 4. 人工核查结果 + +在PR摘要关联的工作流和Photo报告中核对当前head/base、测试版本、原批次、真实caseId及其交互,确认执行终结后检查实际图、基准图、差异和错误。当前case内容不证明历史批次运行了该内容。无读取权限者由管理员提供可公开结论。 + +Photo保持report-only:差异、缺基准、错误、未完成状态如实保留,不阻断三项自动建议;流程completed不代表Photo全量通过。图片相似也不能替代本地语义断言。 + +## 5. 首次基准与后续更新 + +新case缺基准时先核对本轮执行成功、目标状态和测试图正确;缺图、执行错误和未完成结果不能采用。Approve/Merge不授权自动采用图片,工作流不自动建立或更新基准。 + +具有基准写权限的管理员另行取得本次更新授权,核对准确产品、case/interaction、报告及task,读取现有标准引用后按平台支持的条件更新执行;只在明确无基准时使用“无基准”条件,不能把未知当空或无条件覆盖。结果未知保留原请求标识与输入,回读恢复,不换ID。 + +共享基准不按PR、分支或commit隔离,修改影响后续测试。保存授权及回执,再安排新的Photo执行复验;设置成功不代表测试通过,原缺基准/差异报告保留。PR分别记录本轮测试事实、基准处理和未完成复验。 diff --git a/packages/vseed/__tests__/visual/README.md b/packages/vseed/__tests__/visual/README.md index 8649d6609c..07a4d7f7f7 100644 --- a/packages/vseed/__tests__/visual/README.md +++ b/packages/vseed/__tests__/visual/README.md @@ -6,6 +6,9 @@ pnpm --filter @visactor/vseed test:visual --self-compare node packages/vseed/scripts/visual-test.mjs --baseline <完整40位SHA> node packages/vseed/scripts/visual-test.mjs --list +node packages/vseed/scripts/visual-test.mjs --check +# 默认全量比较当前工作区与官方 main +node packages/vseed/scripts/visual-test.mjs node --test packages/vseed/scripts/visual-test.test.mjs ``` @@ -13,8 +16,18 @@ node --test packages/vseed/scripts/visual-test.test.mjs 默认基线为官方 VisActor/VBI main;两侧独立构建 VSeed,并使用各侧锁定的 VChart/VTable UMD。Playwright 固定1.63.0、单worker、800×600、DPR1,截图需连续两次完全稳定,原生比较 threshold=0.1/maxDiffPixels=0;不访问CDN。报告保留两侧提交、源码摘要、SDK摘要、冻结套件、PNG和差异图,写入 .vseed-visual/runs。退出0表示所选范围通过,1表示差异,2表示执行错误;子集或自比较不等于全量双侧验收。 -Bot只在无网络隔离中使用 --offline 和逐侧准备的依赖。根pnpm-lock.yaml、workspace、包清单和配置均与冻结提交比较;缺失依赖不临时联网。宿主为Node22,独立产品CI为Node24,两套工具链证据分别记录。 +Bot只在无网络隔离中使用 --offline 和逐侧准备的依赖。根pnpm-lock.yaml、workspace、包清单和配置均与冻结提交比较;缺失依赖不临时联网。Bot控制器使用Node22;VSeed隔离执行使用独立Node24.12.0运行包,产品CI使用Node24,两类执行证据分别记录。 真实负对照消费已经通过的本地报告:设置 VSEED_VISUAL_FIXTURE 为报告绝对目录,再运行 node --test packages/vseed/scripts/visual-negative.test.mjs。只在临时副本加入可见标记和业务断言失败;验证差异三图与错误分类,不写基准。 -旧 Bug Server CI 继续处理main push及未交接的PR。VISACTOR_WORKFLOW_INTERNAL_SINCE未设置时行为保持;正式交接只针对该起点后、内部main且涉及packages/vseed/\*\*的新PR,Draft等待ready。Bot完整分页核验改名/删除和head/base,服务端独立复核。合入此入口不代表正式准入启用;切流需协调CI、Bot和服务身份共同起点及存量快照。 +## 正式 PR 工作流 + +本仓已于 **2026-11-06 22:05(北京时间,UTC+8)** 正式启用。准入、提交前检查、状态处理、Photo人工核查和批准/合入统一见[贡献指南](../../../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程)。稳定CR范围与独立工作流不同;本页不作为服务配置入口。 + +新增或修改用例见[用例编写指南](./cases/README.md),平台用例见[BugServer管理员协作](./BUGSERVER_CASE_WORKFLOW.md)。产品/依赖/用例变更提交前运行默认全量比较;纯文档检查链接和说明即可,并如实声明未运行项。 + +## 报告与回收 + +`.vseed-visual/runs//index.html` 展示三图,`agent-summary.md` 和 `summary.json` 保存问题、两侧SHA及范围;构建日志、两侧Playwright报告和失败trace用于定位。整体复制报告目录以保留相对链接,不提交运行产物。 + +正常、异常和Ctrl+C后检查本轮浏览器、HTTP服务、子进程和基线worktree已退出。SIGKILL/断电后先核对 `git worktree list` 和 `.vseed-visual/running.lock/owner.json` 的归属及进程状态,再由维护者处理本轮残留,不能盲删锁或他人资源。 diff --git a/packages/vseed/__tests__/visual/cases/README.md b/packages/vseed/__tests__/visual/cases/README.md new file mode 100644 index 0000000000..38d1ba39c3 --- /dev/null +++ b/packages/vseed/__tests__/visual/cases/README.md @@ -0,0 +1,32 @@ +# VSeed 视觉用例编写 + +## 何时补用例 + +新增功能、修复缺陷或发现覆盖空缺时,先找相近用例,优先补强目标场景。影响公共渲染、布局、数据、更新或生命周期时检查相关调用方;每例有明确目的,首批四例不是全功能覆盖。运行与报告见[视觉指南](../README.md),提交要求见[贡献指南](../../../../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程)。 + +## 模块和登记 + +1. 在 `cases/` 新增 `.mjs` 模块,或扩充已有近邻。核心方法使用中文功能说明,输入固定、可公开、无外网和随机依赖。 +2. 导出 `createSpec()` 返回 VSeed DSL,运行器通过 Builder 生成配置并创建真实 VChart/VTable 实例。参考 [column.mjs](./column.mjs)、[table.mjs](./table.mjs) 和 [chart-update.mjs](./chart-update.mjs)。不要把它写成直接返回 VChart spec 的 VChart 用例接口。 +3. 必须导出 `verify(page)`,需要交互时另导出 `exercise(page)`。执行真实鼠标/键盘动作或公开API更新,并验证实际状态、数值、事件或生命周期结果;仅等待截图、检查 canvas 存在不够。 +4. 在 [index.mjs](./index.mjs) 显式登记唯一稳定的 `id`、中文 `purpose` 和模块 `file`。未登记文件不会执行。用 `--list` 确认清单及范围;不要为绕过失败删除已有登记。 +5. 仅明确的业务状态不符调用 [assertionError](../assertions.mjs)。资源、浏览器、加载、脚本或超时错误原样失败,不捕获整段逻辑统一改成业务差异。基线不支持新API也必须如实报告。 + +## 验证新增或修改用例 + +从仓库根目录运行,`--case` 使用已登记的真实ID: + +```sh +node packages/vseed/scripts/visual-test.mjs --list +node packages/vseed/scripts/visual-test.mjs --self-compare --case table-select +node packages/vseed/scripts/visual-test.mjs --case table-select +node packages/vseed/scripts/visual-test.mjs +``` + +单例确认稳定后检查受影响范围,提交产品/用例变更前执行默认全量官方 `main` 比较;有子目录时可用 `--dir `,不能与 `--case` 合用。自比较仅验证确定性,不是双侧通过。核对基线、当前、差异三图及业务断言;稳定性问题应修复等待/资源/动画,不提高像素容差。 + +新增场景还需证明错误确实能被检测:在临时副本中做最小可见变化或破坏目标状态,确认差异或业务断言失败,再恢复副本。运行器已有负对照见视觉指南;通用负对照不替代新场景本身的业务断言。不得将故意失败代码或产物提交到仓库,不写标准图。 + +## 与 BugServer 的关系 + +独立新增的本地用例省略 `BugServer case IDs` 行,不写空值、占位或虚构ID。仅已确认的真实平台来源可添加追溯注释;改写保留来源,合并保留全部真实ID。本地Playwright和平台Photo不会自动同步,新增平台用例见[管理员协作流程](../BUGSERVER_CASE_WORKFLOW.md)。不把内部业务代码、数据、截图、地址或凭据复制到公开用例。 From 4fa5417af39394dc407264771a4edb2aa6b3ecb9 Mon Sep 17 00:00:00 2001 From: Rui-Sun Date: Tue, 10 Nov 2026 11:25:10 +0800 Subject: [PATCH 2/2] docs: use absolute links in PR templates --- .github/PULL_REQUEST_TEMPLATE.md | 6 +++--- .github/PULL_REQUEST_TEMPLATE/pr_cn.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a170ec3b4d..3ab163451f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,7 +6,7 @@ Your pull requests will be merged after one of the collaborators approve. Thank you! --> -[中文版模板 / Chinese template](./PULL_REQUEST_TEMPLATE/pr_cn.md) +[中文版模板 / Chinese template](https://github.com/VisActor/VBI/blob/main/.github/PULL_REQUEST_TEMPLATE/pr_cn.md) ### 🤔 This is a ... @@ -40,7 +40,7 @@ Thank you! ### 🐞 Bugserver case id -Only provide confirmed, public-safe case IDs. If unavailable, state that a product administrator must supply them. Only that product’s administrators may create cases; never use empty, placeholder or invented IDs. [Collaboration guide](../packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md) (Chinese). +Only provide confirmed, public-safe case IDs. If unavailable, state that a product administrator must supply them. Only that product’s administrators may create cases; never use empty, placeholder or invented IDs. [Collaboration guide](https://github.com/VisActor/VBI/blob/main/packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md) (Chinese). ### 💡 Background and solution @@ -52,7 +52,7 @@ Only provide confirmed, public-safe case IDs. If unavailable, state that a produ ### ☑️ Self-Check before Merge -Read [PR checks and merge process](../CONTRIBUTING.md#pr-checks-and-merge-process). Target `main`; the advisory workflow accepts eligible same-repository, non-draft PRs created after 2026-11-06 22:05 Asia/Shanghai and touching packages/vseed/. +Read [PR checks and merge process](https://github.com/VisActor/VBI/blob/main/CONTRIBUTING.md#pr-checks-and-merge-process). Target `main`; the advisory workflow accepts eligible same-repository, non-draft PRs created after 2026-11-06 22:05 Asia/Shanghai and touching packages/vseed/. - [ ] Reported actual commands, outcomes, report scope and skipped checks/reasons. - [ ] Ran relevant unit tests and full official-baseline comparison for product/dependency/case changes, or explained documentation-only applicability. Self-comparison is not a two-sided pass. diff --git a/.github/PULL_REQUEST_TEMPLATE/pr_cn.md b/.github/PULL_REQUEST_TEMPLATE/pr_cn.md index 333fa17c29..88a52906e2 100644 --- a/.github/PULL_REQUEST_TEMPLATE/pr_cn.md +++ b/.github/PULL_REQUEST_TEMPLATE/pr_cn.md @@ -38,7 +38,7 @@ ### 🐞 Bugserver 用例 id -仅填写已确认存在且可公开的真实caseId;无权限或未创建时注明“待项目管理员补充”。只有对应产品管理员可新增,禁止空值/占位/虚构ID。[协作流程](../../packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md)。 +仅填写已确认存在且可公开的真实caseId;无权限或未创建时注明“待项目管理员补充”。只有对应产品管理员可新增,禁止空值/占位/虚构ID。[协作流程](https://github.com/VisActor/VBI/blob/main/packages/vseed/__tests__/visual/BUGSERVER_CASE_WORKFLOW.md)。 ### 💡 问题的背景&解决方案 @@ -50,7 +50,7 @@ ### ☑️ 自测 -请阅读[PR检查与合入流程](../../CONTRIBUTING.zh-CN.md#pr-检查与合入流程)。目标为main;同仓、涉及packages/vseed/且在2026-11-06 22:05北京时间起点后新建的非Draft PR可接入。 +请阅读[PR检查与合入流程](https://github.com/VisActor/VBI/blob/main/CONTRIBUTING.zh-CN.md#pr-检查与合入流程)。目标为main;同仓、涉及packages/vseed/且在2026-11-06 22:05北京时间起点后新建的非Draft PR可接入。 - [ ] 已填写实际测试命令、结果、报告范围和未运行项/原因。 - [ ] 产品/依赖/用例变更已完成相关单测及默认全量基线比较;纯文档说明不适用。自比较不能代替双侧通过。