CSS container queries solve a real problem that viewport-based responsive design never handled cleanly, components often need to adapt to the size of their parent, not the size of the browser window. That shift is powerful, but it changes how you test. A card, sidebar, or toolbar can look correct at one viewport and still break when its container changes width inside a grid, split pane, or resizable panel.

If your test strategy still treats responsiveness as a set of viewport breakpoints, you will miss bugs. The component may pass a full-page screenshot at 1440px, then fail inside a narrower column where the container query activates a different layout. To test CSS container queries well, you need to verify both behavior and appearance at the container level, and you need to do it without turning your visual regression suite into a pile of noisy diffs.

This article walks through a practical way to test CSS container queries using browser assertions, targeted visual checks, and a few patterns that keep tests stable over time.

What container queries change in testing

Container queries let styles depend on the dimensions of a containing element, usually declared with container-type: inline-size or container-type: size. That means the trigger for the layout is no longer the viewport, it is the container box.

That sounds like a CSS detail, but it changes the test surface in a few ways:

  • One page can contain multiple instances of the same component, each in a different width context.
  • A component can switch layout without any browser resize.
  • Visual regression failures often come from layout transitions, not from broken selectors.
  • The same component may be correct in isolation and wrong when embedded in a real layout.

A traditional responsive test that checks mobile, tablet, and desktop viewports is still useful, but it is not enough. For responsive UI testing with container queries, the key unit is the container, not the window.

A good container query test asks, “Did the component choose the right layout for this parent size?”, not, “Does the whole page look fine at this viewport?”

What to assert in browser tests

Before you reach for screenshots, define the behavior you expect. Container query tests should verify the style state that matters to users, not every pixel.

Typical assertions include:

  • The query-triggered layout mode is active or inactive at a given container width.
  • Important elements move from stacked to horizontal layout, or vice versa.
  • The number of visible columns changes.
  • Text truncation, wrapping, or overflow behavior stays acceptable.
  • Buttons and actions remain reachable after layout changes.
  • Hidden elements do not become accidentally visible.

You can check these in Playwright, Cypress, or Selenium. The mechanics differ, but the idea is the same, resize or render a container, then assert on the computed result.

A simple component example

Imagine a product card that becomes a two-column layout once its parent container is wide enough.

<div class="product-card" data-testid="product-card">
  <img class="product-card__image" alt="Product" />
  <div class="product-card__content">
    <h2>Wireless Headphones</h2>
    <p>Noise cancelling over-ear headphones.</p>
    <button>Add to cart</button>
  </div>
</div>

.product-card {
  container-type: inline-size;
  display: grid;
  gap: 16px;
  grid-template-columns: 1fr;
}

@container (min-width: 480px) { .product-card { grid-template-columns: 160px 1fr; align-items: center; } }

A browser test should not only check that the card renders, it should check which layout rule is active at each container size.

Playwright example, checking layout behavior

With Playwright, the easiest approach is usually to control the container width via inline styles or a test harness wrapper, then read computed styles or element geometry.

import { test, expect } from '@playwright/test';

test('product card switches to two columns at container width', async ({ page }) => {
  await page.setContent(`
    <div style="width: 420px; border: 1px solid #ccc;">
      <div class="product-card" data-testid="product-card">
        <img class="product-card__image" alt="Product" />
        <div class="product-card__content">Content</div>
      </div>
    </div>
  `);

const card = page.getByTestId(‘product-card’); await expect(card).toHaveCSS(‘grid-template-columns’, ‘420px’); });

That example is intentionally simple, but in real tests you will usually want a stronger assertion than a raw CSS string. A better pattern is to compare element positions.

typescript

const image = page.locator('.product-card__image');
const content = page.locator('.product-card__content');

const imageBox = await image.boundingBox();

const contentBox = await content.boundingBox();

expect(imageBox && contentBox).not.toBeNull(); expect(contentBox!.x).toBeGreaterThan(imageBox!.x);

This verifies that the layout actually changed into a horizontal arrangement. It is less brittle than checking every CSS value and more meaningful than a screenshot alone.

Resizing the container, not just the viewport

A common mistake is to use page.setViewportSize() and assume you are exercising the container query. That works only if the container width is directly tied to the viewport. In many apps, it is not.

Consider a split layout with a main content area and a sidebar. The component might live in a column that is 360px wide on desktop and 100% wide on mobile. The viewport could be huge while the container stays narrow.

A better test harness makes container width explicit:

typescript

async function renderWithWidth(page, width: number) {
  await page.setContent(`
    <div style="width: ${width}px; border: 1px solid transparent;">
      <div class="product-card" data-testid="product-card">
        <img class="product-card__image" alt="Product" />
        <div class="product-card__content">Content</div>
      </div>
    </div>
  `);
}

Then run the same assertions at multiple widths.

typescript

test('product card is one column below the threshold', async ({ page }) => {
  await renderWithWidth(page, 320);
  const content = page.locator('.product-card__content');
  const image = page.locator('.product-card__image');

const imageBox = await image.boundingBox(); const contentBox = await content.boundingBox();

expect(contentBox!.y).toBeGreaterThan(imageBox!.y); });

This style of testing is useful for any component that adapts to its parent, including navigation rows, article lists, data tables, and dashboards.

Visual regression for CSS, when to use it

Visual regression is still valuable for container queries, but it should be used with a narrower purpose than “compare everything.” The main risk is noise. If a container query changes layout, a screenshot diff can be large, even when the change is expected. That makes it harder to notice accidental regressions.

Use visual regression for CSS when the layout change has visual consequences that are hard to assert directly, such as:

  • spacing and alignment between elements,
  • typography wrapping and truncation,
  • card density and balance,
  • icon and label alignment,
  • overflow clipping,
  • unexpected wrapping in action bars.

For visual regression for CSS, the best practice is to scope the screenshot to the component or a small test page, not to the full application shell. A small diff is easier to review and less likely to hide unrelated changes.

The “two layers” strategy

For container query testing, think in two layers:

  1. Browser assertions for state and structure.
  2. Visual regression for layout fidelity.

The browser test answers, “Did the component switch to the expected mode?” The screenshot test answers, “Does that mode look correct?”

This division keeps your suite maintainable. If a screenshot fails, the browser assertions can tell you whether the query threshold triggered properly. If the browser assertions fail but the screenshot passes, you may have a hidden state bug that is not visible yet.

Make screenshot tests less brittle

Container-query-heavy components can produce noisy screenshots if you are not careful. A few practices help a lot.

1. Isolate the component

Render the component inside a minimal test harness with only the styles it needs. Avoid entire pages unless the behavior depends on surrounding layout.

2. Control fonts and assets

Use deterministic fonts and local assets in CI. Remote font loading and image decoding can change text metrics or introduce delays.

3. Wait for layout, not arbitrary time

Do not sleep and hope the page settles. Wait for the state you care about.

typescript

await expect(page.locator('[data-testid="product-card"]')).toHaveScreenshot('product-card-wide.png');

If your framework allows it, wait for network idle only when external data is involved. For pure CSS behavior, layout assertions are usually enough.

4. Test only the relevant widths

You do not need screenshots at every pixel. Pick widths around the query threshold, for example just below, at, and just above the break point. That is where bugs usually hide.

5. Mask volatile regions

If timestamps, avatars, or random IDs appear near the component, mask them or remove them from the test fixture.

Edge cases that break container queries

Several bugs show up repeatedly in container-query testing.

Nested containers

A child component may use its nearest ancestor container, not the one you expected. This matters when you have nested cards, nested grids, or reusable panels.

A test should verify that the component is responding to the right container, especially if there are multiple container-type elements in the tree.

Overflow and clipped width

Sometimes the element’s visual width does not match its content width because of padding, borders, or overflow settings. Your test should account for the actual border box if that is what the query uses.

Flex and grid interactions

A component inside a flex item or grid item can shrink in ways that make the query threshold hard to reason about. If a test unexpectedly fails, inspect the computed width of the container, not just the outer wrapper.

Font loading and line wrapping

A style change that only affects line wrapping can create large visual diffs. This is especially common in headings and buttons. If the layout is sensitive to text width, pin fonts in the test environment.

Orientation and writing modes

When using container-type: size, remember that both dimensions can matter. Vertical layouts, internationalization, and writing mode changes can make width-only assumptions invalid.

A practical matrix for test coverage

You do not need a huge matrix, but you do need enough coverage to catch boundary issues.

A useful starting point:

  • one test below the smallest query threshold,
  • one test just above each threshold,
  • one visual regression snapshot for each distinct layout mode,
  • one integration test inside a realistic parent layout,
  • one regression test for a nested container scenario.

For example, if a component has breakpoints at 360px and 560px, test at 320px, 380px, 540px, and 600px. The goal is not exhaustive width coverage, it is confidence around the transition points.

Example, checking a sidebar panel in a real layout

Here is a more realistic Playwright pattern. The component sits inside a main layout, and the query should respond to the panel width, not the browser viewport.

import { test, expect } from '@playwright/test';

test('settings panel stays compact inside a narrow column', async ({ page }) => {
  await page.setContent(`
    <div style="display:grid; grid-template-columns: 280px 1fr; gap: 24px;">
      <aside>
        <section class="settings-panel" data-testid="settings-panel">
          <div class="row">Profile</div>
          <div class="row">Security</div>
        </section>
      </aside>
    </div>
  `);

const rows = page.locator(‘[data-testid=”settings-panel”] .row’); await expect(rows).toHaveCount(2);

const first = await rows.nth(0).boundingBox(); const second = await rows.nth(1).boundingBox(); expect(second!.y).toBeGreaterThan(first!.y); });

This checks the stacking behavior that a narrow panel should preserve. If the panel were expected to turn into a denser inline layout at a wider container size, you would add a second test with a wider column and assert the opposite geometry.

Where Cypress and Selenium still fit

Playwright is often the cleanest choice for container-query tests because it exposes robust geometry and screenshot tooling. That said, Cypress and Selenium still work well when your team already uses them.

With Selenium, the pattern is similar, render the component in a controlled container, then inspect location and size. The main difference is that geometry APIs and screenshot support are usually more verbose. If you already have a Selenium stack, do not rewrite everything just for container queries. Add a few targeted tests around the components most likely to break.

The bigger decision is not the framework, it is the test granularity. Whether you use test automation in Playwright, Cypress, or Selenium, the test must simulate the parent size that actually drives the query.

CI strategy for container query coverage

Container-query tests fit well into Continuous integration, but only if you keep them deterministic. A sensible setup is:

  • run fast browser assertion tests on every pull request,
  • run component screenshot tests on changed UI packages or stories,
  • run a broader visual suite on main branch merges,
  • keep a separate job for tests that depend on external fonts or data.

If you use GitHub Actions, a small matrix can cover different browser engines or viewport sizes. For many teams, Chromium-only screenshot tests are enough for component-level regression detection, then a smaller compatibility matrix can run less frequently.

name: ui-tests
on: [pull_request]

jobs: playwright: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - run: npm ci - run: npx playwright install –with-deps chromium - run: npm test

The important part is not the exact YAML, it is that the test fixture and rendering environment stay stable enough for visual diffs to mean something.

Debugging a failing container query test

When a test fails, do not start by updating snapshots. First answer these questions:

  1. What is the actual width of the container?
  2. Which container is the element responding to?
  3. Did the layout mode change, or only the visual presentation?
  4. Is the failure caused by fonts, assets, or timing, or by CSS logic?
  5. Is the screenshot diff localized to the intended region?

A quick debugging trick is to print the relevant sizes before the assertion.

typescript

const box = await page.locator('[data-testid="product-card"]').boundingBox();
console.log('card width', box?.width);

If the width is not what you expect, the bug may be in the test setup, not the component.

What not to test

Not every CSS change deserves a dedicated container query test. Avoid over-testing implementation details that are unlikely to matter to users.

Do not assert every computed style property. Do not snapshot every page at every width. Do not encode the exact grid template strings unless that string is the contract you truly care about.

Instead, focus on visible outcomes:

  • does the content stack or align correctly,
  • are controls still usable,
  • does the component overflow,
  • does the layout trigger at the intended threshold,
  • does the component remain readable and stable.

That keeps your suite useful when the CSS evolves.

A good rule of thumb

If a container query changes the structure of the component, test it with browser assertions. If it changes the visual balance, test it with a small screenshot. If it changes both, do both, but keep the scope narrow.

The strongest container query test suites are small, intentional, and centered on the transition points, not broad screenshot farms.

Final checklist

Before you merge a component that uses container queries, check that you have:

  • at least one browser assertion per meaningful layout mode,
  • coverage for widths near each threshold,
  • a realistic parent container in the test harness,
  • one or two component-level visual regression snapshots,
  • stable fonts and assets in CI,
  • no dependency on the viewport when the query depends on a parent.

Container queries are one of the best improvements in modern CSS, but they only pay off if you test them correctly. The mindset shift is simple, stop asking whether the page is responsive, and start asking whether the component responds to the space it actually lives in.

If you build your tests around that question, you can test CSS container queries with enough precision to catch real regressions, without drowning in brittle screenshots.