agentleFS
HsuanYuLeeHsuanYuLee/polaris/.claude/skills/visual-regression/SKILL.md

visual-regression

Skill5 starsChanged 4 days agoMITView on GitHub

Standalone visual regression guard using before/after screenshot comparison. Two modes: SIT (compare staging vs local dev) or Local (compare git-stashed base vs current changes). No long-lived baselines — captures fresh screenshots each run and deletes after comparison. Config-driven from workspace-config.yaml. Use when: "跑 visual regression", "檢查畫面", "頁面有沒有壞", "visual test", "screenshot test", "畫面測試", "截圖比對", "有沒有跑版", "畫面壞了嗎", "UI 有沒有問題", "check if pages look right", for standalone manual investigation.

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. 0 are common, 2 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before/after screenshot comparison guard。每次執行都抓 fresh before / after screenshots,使用 Playwright diff,分析後刪除 temporary snapshots 與 test …

    line 38
  2. Distinctive:

    Always go through production-equivalent proxy;不可直接打 app dev port 迴避 routing。

    line 80

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Visual Regression

Before/after screenshot comparison guard。每次執行都抓 fresh before / after screenshots,使用 Playwright diff,分析後刪除 temporary snapshots 與 test results; 不維護 long-lived baselines。

Contract

VR 的測試單位是 domain,不是 repo。為一張單跑的時候,頁面與 viewport 取自那張單的 VR assertion; 沒有單的時候,取自 configured URL paths(見 visual-regression-preflight-flow.md〈頁面從哪裡來〉)。 不可因「頁面不在目前 repo」而 skip。合法 skip 僅限 config 缺漏、dependency declined、clean local tree、 smart-skip 判斷無 visual impact、fixture 未建立、已知 SSR hang、環境依賴缺失。

VR 在 quality chain 中回答:「既有頁面是否仍 visually intact?」它不取代 Local CI Mirror, 也不取代 feature behavior verification。

Reference Loading

依執行情境讀取:

SituationLoad
Any VR runvisual-regression-principles.md, visual-regression-preflight-flow.md, visual-regression-config.md, workspace-config.yaml
Screenshot executionvisual-regression-capture-flow.md, dependency-consent.md
Fixtures enabledapi-contract-guard.md, visual-regression-fixture-flow.md, vr-artifact-location.md
Analysis or JIRA reportvisual-regression-analysis-reporting.md

JIRA report、Slack summary,或任何 external write body 送出前,必須依 workspace-config.yaml 的 language 驗證語言。

Flow

  1. 解析 domain 與 company config,套用 root defaults inheritance。
  2. 檢查 visual regression 是否已設定;未設定則 stop,不 improvisation。
  3. 執行 smart skip、dependency consent、Playwright/toolchain readiness。
  4. 決定 SIT 或 Local comparison path;SIT 不可達時依 reference fallback。
  5. 透過 polaris-env.sh 啟動 production-equivalent proxy 與 dev environment。
  6. Fixtures active 時先跑 API contract guard。
  7. Capture before screenshots,capture after screenshots,讓 Playwright compare。
  8. 分析結果、套用 first-run quality gate、必要時上傳 artifacts 並寫 JIRA wiki report。
  9. 無論 pass/fail/error 都 cleanup,保護 git stash、server state、temporary snapshots。

Hard Rules

  • Always go through production-equivalent proxy;不可直接打 app dev port 迴避 routing。
  • CSR content 必須等 deterministic selector,不使用 fixed timeout 當 readiness。
  • UA-based mobile SSR 必須設定 mobile user agent,不只設 viewport。
  • Fixtures active 時為 strict mode:任何 diff 都不是 data variance。
  • First run after fixture setup/change 必須 human screenshot review;zero-diff 不代表截圖正確。
  • Playwright tests 必須 sequential,workers: 1。
  • JIRA inline screenshot report 使用 REST API v2 wiki markup,不使用 MCP markdown comment。

Completion

Standalone run 回報 domain、comparison path、pages count、diff summary、HTML report path、 cleanup status。

<!-- PROSE-EXTERNAL-PATHS: docs-manager/ — 動手對象:那是 specs 站台自己的 repo,這支 skill 往它寫東西、讀它的結構,不是我們抄一份放著的知識 -->

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.