How Does the Archify visual-check Command Measure Containment?

The visual-check command measures containment by rendering the UI in a headless Playwright browser, extracting bounding rectangles via Element.getBoundingClientRect(), and verifying that the child element’s coordinates lie entirely within the parent container’s bounds.

The visual-check command in the tt-a1i/archify repository provides automated visual regression testing by verifying that DOM elements remain visually contained within their parent containers. This analysis examines how the command measures containment by dissecting the implementation in archify/test/visual-check.test.mjs and the geometric comparison algorithm used to validate layout constraints.

The Geometry of Containment Measurement

At its core, the visual-check command performs a strict geometric comparison between two axis-aligned bounding boxes. The measurement relies on the bounding client rectangle obtained through the Web API to determine spatial relationships in device pixels.

Extracting Bounding Rectangles

The command executes within a headless browser context provided by Playwright. For both the candidate element and its container, the code invokes Element.getBoundingClientRect() to retrieve a DOMRect object containing top, right, bottom, and left properties.

According to the source logic in archify/test/visual-check.test.mjs, the measurement process follows these steps:

1. Launch a Chromium browser instance and navigate to the target page URL.
2. Query the DOM for the child element using its CSS selector.
3. Query the DOM for the parent container using its CSS selector.
4. Execute getBoundingClientRect() on both elements to capture their spatial coordinates relative to the viewport.

The Four-Point Comparison Algorithm

Once the rectangles are extracted, the containment algorithm performs four simultaneous comparisons to determine if the candidate resides completely inside the container:

const contained =
  childRect.left   >= parentRect.left &&
  childRect.right  <= parentRect.right &&
  childRect.top    >= parentRect.top &&
  childRect.bottom <= parentRect.bottom;

If all four conditions evaluate to true, the element is considered contained. If any boundary exceeds the container's limits, the check fails and the command reports the specific overflow coordinates and pixel distances.

Implementation in the Test Suite

The actual implementation resides in archify/test/visual-check.test.mjs, which orchestrates the browser automation and assertion logic.

Browser Automation with Playwright

The test harness uses Playwright to create a consistent, headless rendering environment. This approach ensures that measurements reflect actual computed styles rather than static CSS values, catching layout bugs caused by dynamic content, flexbox calculations, or runtime style mutations that occur after page load.

CLI Invocation

Developers trigger the containment check via the command line interface:

npx archify visual-check --story storyId --selector ".child" --container ".parent"

The CLI parses these arguments and passes them to the test runner, which then executes the geometric validation against the specified story page.

Practical Code Example

The following simplified implementation demonstrates the containment logic used by the visual-check command:

import { chromium } from 'playwright';

async function checkContainment(pageUrl, childSel, parentSel) {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(pageUrl);

  const childRect = await page.evaluate(sel => {
    const el = document.querySelector(sel);
    return el?.getBoundingClientRect();
  }, childSel);

  const parentRect = await page.evaluate(sel => {
    const el = document.querySelector(sel);
    return el?.getBoundingClientRect();
  }, parentSel);

  const contained =
    childRect.left   >= parentRect.left &&
    childRect.right  <= parentRect.right &&
    childRect.top    >= parentRect.top &&
    childRect.bottom <= parentRect.bottom;

  await browser.close();
  return contained;
}

In archify/test/visual-check.test.mjs, this logic is wrapped within a test assertion framework that provides detailed diffs when containment fails, showing exactly which boundary exceeded its limit by how many pixels.

Summary

• The visual-check command uses Playwright to render pages in a headless Chromium browser for accurate, runtime layout measurement.
• Containment validation relies on Element.getBoundingClientRect() to obtain device-pixel-accurate bounding boxes for both the child and parent elements.
• The algorithm strictly checks four inequalities (left >=, right <=, top >=, bottom <=) to verify complete spatial enclosure on all sides.
• The primary implementation resides in archify/test/visual-check.test.mjs, which handles browser automation, DOM querying, and test assertions.
• This measurement approach detects visual regressions caused by dynamic content and responsive layout changes that static CSS analysis would miss.

Frequently Asked Questions

What browser engine does the visual-check command use?

The visual-check command uses Chromium via the Playwright automation library. This provides a consistent, headless rendering environment that accurately reflects how the UI appears to end users, including full support for modern CSS features and JavaScript-driven layout calculations.

How does visual-check handle elements with dynamic or responsive sizing?

Because the command measures containment at runtime using getBoundingClientRect(), it captures the actual rendered dimensions after all CSS calculations, flexbox layouts, and JavaScript mutations have occurred. This allows the test to catch overflow issues caused by dynamic content loading or viewport-responsive breakpoints that might not be visible in static markup analysis.

What information is provided when a containment check fails?

When the geometric comparison detects an overflow, the test reports the specific boundary violations along with the measured pixel coordinates for both the child and parent rectangles. This detailed diff allows developers to identify exactly which edge exceeded its container and by how many device pixels, facilitating rapid debugging of layout issues.

Can the visual-check command measure partial containment or calculate overflow margins?

The current implementation as defined in archify/test/visual-check.test.mjs uses a strict boolean check requiring complete containment on all four sides. It does not natively calculate the degree of overflow or support partial containment thresholds; any boundary violation results in a test failure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}