<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for Mistral: scripts/model-profiles.json -->

#How to apply this file

Each section opens with one imperative line; apply every rule in the section it introduces. Do not summarise or skip a section.

---

#Purpose

Rules for catching unintended visual change by comparing rendered output against approved baselines.

Visual tests catch what assertions cannot: a CSS change that breaks an unrelated page, a font fallback, a component overlapping at one breakpoint. They fail badly when non-determinism makes them noisy — the common outcome is a suite that is always slightly red and therefore approved without looking, which is worse than having none.

---

#Determinism is the whole problem

[INST] Apply every rule in this section: Determinism is the whole problem. [/INST]

Every source of variation must be removed or masked before the first baseline.

css
/* Loaded only in visual tests: nothing may be mid-animation at capture time */
*, *::before, *::after {
  animation: none !important;
  transition: none !important;
  caret-color: transparent !important;
  scroll-behavior: auto !important;
}

Never generate baselines on a developer laptop and compare them in CI. Font hinting and GPU rasterisation differ, so every screenshot differs. Generate and compare in the same container image, pinned by digest.

---

Tooling: @playwright/test toHaveScreenshot, percy, chromatic, argos-ci, backstopjs, loki. Playwright's built-in comparison needs no service and stores baselines in the repository; hosted tools add review workflows and cross-browser rendering at a cost.

Pin the runner explicitly — mcr.microsoft.com/playwright:v1.49.0-jammy by digest, not :latest. A browser or font-package update inside the image invalidates every baseline at once.

#Capture

[INST] Apply every rule in this section: Capture. [/INST]

js
test("invoice card renders", async ({ page }) => {
  await page.goto("/components/invoice-card");
  await page.evaluate(() => document.fonts.ready);      // fonts settled

  await expect(page.getByTestId("invoice-card")).toHaveScreenshot("invoice-card.png", {
    maxDiffPixelRatio: 0.01,        // absorb sub-pixel noise, catch real change
    animations: "disabled",
    mask: [page.getByTestId("relative-time")],   // dynamic region excluded
  });
});

• Screenshot the component, not the page, where possible. A page-level baseline fails for every unrelated change and tells you nothing about which.
• Set a small but non-zero diff tolerance. Zero is brittle; anything above a percent or two hides real regressions.
• Mask genuinely dynamic regions rather than trying to freeze them.
• Cover the states that break in production: empty, loading, error, overflow and long-text. A component tested only with a two-word label passes forever and breaks on the first real customer name.
• Test the breakpoints that matter — typically 375px, 768px and 1280px — plus dark mode if you support it. Every extra viewport is another baseline to review.

---

yaml
# Pin the image by digest. A font or browser update inside :latest silently
# invalidates every baseline in the repository.
jobs:
  visual:
    container:
      image: mcr.microsoft.com/playwright@sha256:<digest>
    steps:
      - run: npx playwright test --grep @visual
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: visual-diffs
          path: test-results/**/*-diff.png    # reviewers need the diff image

#Reviewing diffs

[INST] Apply every rule in this section: Reviewing diffs. [/INST]

This is where the practice succeeds or fails.

• Every baseline update is a code review. The diff image goes in the pull request and someone looks at it.

• Never run the update command to make CI green. Doing so commits the regression as the new expected appearance — the exact failure mode this suite exists to prevent.

• Approvals belong to the person who owns the visual change, not whoever is unblocking the build. Commands worth knowing: --update-snapshots regenerates (dangerous — see above), --grep @visual runs only this tier, and --reporter=html produces the side-by-side expected / actual / diff view that makes review possible at all.

• Store baselines in the repository (Git LFS if they grow) or in the tool's managed store — but they must be versioned with the code, so checking out an old commit gives its correct baselines.

---

#Scope

[INST] Apply every rule in this section: Scope. [/INST]

Component-level baselines in a Storybook-style harness give the best ratio: they are stable, fast, and the failure points directly at the component.

Never treat a visual test as an accessibility check. Identical pixels can hide a missing label or an unreachable control → Testing/accessibility.

---

#Anti-patterns

[INST] Apply every rule in this section: Anti-patterns. [/INST]

---

#Checklist

• Verify: Baselines are generated and compared in the same pinned container image
• Verify: Animations, transitions and carets are disabled during capture
• Verify: Clocks are frozen and random data seeded
• Verify: Fonts are self-hosted and awaited before capture
• Verify: Dynamic regions are masked rather than left to vary
• Verify: Captures target components; page-level shots are reserved for key pages
• Verify: Diff tolerance is small but non-zero
• Verify: Key breakpoints and dark mode are covered
• Verify: Every baseline update is reviewed as a diff image by the change owner
• Verify: Baselines are versioned with the code
• Verify: Accessibility is tested separately, never inferred from pixels