Assert CSS Pseudo-Elements with Playwright

Playwright toHaveCSS pseudo element assertion support reads computed styles from ::before or ::after while retaining Playwright's retrying matcher behavior. Locate the originating element, pass { pseudo: 'before' } or { pseudo: 'after' }, and assert one requirement-bearing property. The first failure boundary is the cascade: generated content exists only when the final computed style creates it.

This removes the need for a one-off getComputedStyle polling loop, but it does not make every decorative flourish worth testing. Use the option for a visible state or cue that the product explicitly owns, such as a required marker, status badge, or overlay. Pair it with semantic and behavioral assertions whenever users need the same information without relying on generated pixels.

Define the Visual Contract First

Pseudo-elements are generated boxes associated with a real element. They can add text, icons, underlines, badges, or overlays without adding another DOM node. That makes them useful for presentation and awkward for element-centric tests: there is no independent pseudo-element locator to click, count, or inspect as ordinary HTML.

Name the requirement before the property. "Required fields display the approved red marker in the default form theme" is a testable product contract. "The label has a ::after rule" is an implementation detail and can remain true even when another rule overrides its content, color, or display. Computed-style assertion belongs at the end of the cascade, where the user-facing result is decided.

Do not let the marker carry the only meaning. The input should still use the native required attribute or an appropriate semantic state, and the label should identify the control. The Playwright ARIA snapshot accessibility guide helps verify semantic output, while this CSS assertion protects the chosen visual treatment.

The first observable assertion should establish the application state that activates the style. If an error icon appears only after blur, blur the field and assert the validation state before checking ::after. Otherwise a CSS timeout may really be a missing validation transition.

Use the Exact 1.61.1 Signature

The Playwright release notes list the pseudo option for expect(locator).toHaveCSS() as a Playwright 1.60 addition. In the installed 1.61.1 TypeScript declarations, the matcher signature accepts a CSS property name, a string or regular expression expected value, and options containing pseudo?: "before" | "after" plus an optional timeout.

Pass before or after without colons. These are API enum values, not CSS selector strings. { pseudo: '::before' } is a type error and does not match the runtime contract. Other pseudo-elements such as ::marker, ::placeholder, and ::selection are outside this option's 1.61.1 type surface.

toHaveCSS reads a computed value and retries until it matches or times out. Computed values may differ in form from authored declarations. A hex color can be returned as an rgb(...) string. Generated content is serialized as a CSS value, including quotes for a string. Shorthand properties may be expanded or normalized by the browser.

The matcher still receives a locator for the originating DOM element. Use the official locator guidance to keep that element specific and stable. A pseudo option changes where the computed property is read; it does not alter locator scope or strictness.

Create a Fixture with Semantic and Visual State

The fixture below marks a required email label with generated content while preserving native form semantics. The marker is a visual enhancement, not the accessible source of required state.

Fixture: required marker generated by ::after

<form aria-label="Create account">
  <label class="required-label" for="email">Email</label>
  <input id="email" name="email" type="email" required>
  <button type="submit">Create account</button>
</form>

<style>
  .required-label::after {
    content: "Required";
    margin-inline-start: 0.375rem;
    color: rgb(180, 35, 35);
    font-size: 0.75rem;
  }
</style>

Plain text keeps the example independent from icon fonts and operating-system glyph rendering. A production design may use a symbol, but tests should not infer meaning from a private-use character or font ligature. If the marker must be understandable, visible nearby text and native semantics are easier to validate and translate.

The label has no ARIA role, so a precise CSS locator such as label[for="email"] is reasonable for the styling assertion. The input itself should still be found by role and accessible name for interaction. The Playwright locators article explains why the best locator can differ between a user action and a styling target.

Implement the Assertion in an Observable Sequence

Keep pseudo-element tests chronological:

1. Configure the viewport, theme, locale, reduced-motion preference, and deterministic fonts required by the style contract.
2. Navigate to the form and wait for the application state that applies the relevant class or data state.
3. Locate the real DOM element that owns ::before or ::after and assert that the locator resolves uniquely.
4. Assert the semantic property independently, such as required, invalid state, accessible name, or status text.
5. Assert one or two computed pseudo-element properties that express the visible requirement.
6. Capture a focused screenshot only when pixels are needed to diagnose placement, clipping, or overlap.
7. Classify a failure as product cascade, state setup, browser environment, or test-contract drift before changing expectations.

Playwright 1.61.1 example: semantic state plus computed style

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

test('required email has semantic and visual indicators', async ({ page }) => {
  await page.goto('/signup');

  const email = page.getByRole('textbox', { name: 'Email' });
  const emailLabel = page.locator('label[for="email"]');

  await expect(email).toHaveAttribute('required');
  await expect(emailLabel).toHaveCSS('content', '"Required"', {
    pseudo: 'after',
  });
  await expect(emailLabel).toHaveCSS('color', 'rgb(180, 35, 35)', {
    pseudo: 'after',
  });
});

The first matcher protects semantics. The second protects generated text. The third protects an owned color token, though color alone must never carry the requirement. If the product contract cares only that a marker exists, asserting font size, margin, and every other computed property adds maintenance without more confidence.

Use regular expressions for computed values only when variability is defined. A pattern that accepts any nonempty content can let the wrong warning pass. Exact values are preferable for controlled text; a narrow expression may help when the browser serializes a URL or escaped string in a documented range.

Choose CSS, Screenshot, or Semantic Evidence

The following decision table keeps computed style in its proper role.

An ARIA snapshot can include composed content in some semantic outputs, but it is not a CSS declaration test. The official ARIA snapshot documentation notes that generated content can contribute to represented link text. That is another reason not to assume decoration is isolated from accessible naming across every component and browser.

The visual accessibility scenarios demonstrate why semantic, computed-style, and screenshot evidence complement each other. Choose the smallest combination that protects the actual risk instead of collecting all three for every component.

Understand Computed Content and Cascade Boundaries

A pseudo-element is generated only when its computed content creates it. A selector can match and still produce no visible pseudo box because a later rule sets content: none, the state class is absent, or a media query disables it. Inspect selector match and cascade order before changing the expected string.

Computed content strings are especially easy to misread in JavaScript. The CSS value for the word Required is commonly returned with quotes, so the JavaScript expected string is written as '"Required"'. Let the first matcher failure show the received value in the target browsers, then encode the product contract. Do not strip all quotes and escapes in a helper that could make distinct values appear equal.

Inheritance can also surprise. Many properties on ::before and ::after inherit from the originating element unless the pseudo rule overrides them. A color assertion may pass because the label color changed, not because the pseudo selector contains the expected declaration. That still proves the final appearance at the computed-value level, but it does not prove which stylesheet rule supplied it. Use browser developer tools when rule ownership matters.

Pseudo-elements can participate in layout without changing the originating element's text content. toHaveText is therefore the wrong assertion for generated marker content. Conversely, toHaveCSS('content', ...) says nothing about the input's value or label. Keep each matcher aligned with the browser surface it actually observes.

Test Stateful Pseudo-Elements without Timing Guesses

Many useful pseudo-elements are conditional. A field can add an error icon under [aria-invalid="true"], a disclosure can rotate an arrow under [aria-expanded="true"], and a navigation link can draw an underline on focus or hover. The test must first create and prove the selector state, then inspect the generated style. Reversing that order turns a missing product transition into an opaque CSS timeout.

For focus-driven styles, move focus through the same path a user takes and assert toBeFocused on the originating control. Then read the pseudo style. Programmatic focus can be appropriate for a component unit, but a journey test should use Tab when focus order is part of the risk. Keep the focus behavior and focus-ring presentation as separate assertions so either failure has a clear owner.

Hover requires a project decision. A desktop browser with a fine pointer can apply a hover rule that has no counterpart on a touch project. Do not force the same expectation across both. Tag or configure the projects that own hover behavior, perform locator.hover(), and assert the pseudo result there. The locator guide covers actionability for the originating element; the pseudo-element itself is never the hover target.

Validation styles should follow a durable state marker. Submit or blur the form, assert aria-invalid, an error message, or the component's documented state, and only then check generated content. Avoid waiting for a class name when that class is merely one implementation of the state. The semantic assertion should survive a stylesheet or component refactor even if the pseudo locator needs review.

Transitions create a subtle false positive. Because toHaveCSS retries, it passes when the computed value matches during the polling window. If an animated property briefly crosses the expected value and then continues, a passing assertion does not prove the final resting style. Prefer reduced motion for deterministic suites or wait for a product-owned end condition before reading the final property. Avoid asserting intermediate transform matrices unless animation behavior itself is the requirement.

Theme switches need the same chronology. Trigger the supported theme control, assert the applied theme state, then verify the pseudo color or content. Reading immediately after changing storage or a root attribute can race stylesheet application. A retrying matcher helps with asynchronous cascade updates, but the preceding theme assertion tells a reviewer which state was requested and whether the failure belongs to the control or the visual rule.

Negative checks should target dangerous persistence. After correcting an invalid value, assert the semantic error clears and the generated error content becomes none or the approved empty value. Do not rely only on .not.toHaveCSS with one old string, because a different incorrect marker could still pass. Positive assertion of the clean state is easier to understand and maintain.

When placement matters, capture the screenshot immediately after the computed-style assertion. This aligns the cascade state with the pixels under review. If the screenshot later differs while the style still matches, follow the visual snapshot CI debugging guide to inspect layout, fonts, and environment instead of adding more unrelated property assertions.

Design a Boundary and Failure Matrix

Build cases around the cascade, originating element, runtime environment, and semantic fallback.

The dangerous false positive is a perfect marker on a semantically optional field. That is why the semantic assertion appears before the CSS check. Another false positive is asserting only content while the pseudo-element is clipped, transparent, or behind another layer. Add a focused visual check when the risk is actual presentation.

Compare those boundaries with the wider accessibility testing tools guide. Automated rule scans can catch some missing form semantics or contrast issues, but they do not know that this specific generated marker is part of an approved component contract.

Debug Pseudo-Element Failures by Layer

First confirm the originating locator resolves to exactly one expected element. Inspect the DOM element, its state class or attribute, and the active stylesheet rules. Then read getComputedStyle(element, '::after') in browser developer tools if necessary. The Playwright assertion already performs the computed-value check with retries; manual evaluation is for diagnosis, not the first replacement.

If the received value is none, verify the content property and state selector. If content matches but color does not, inspect inheritance, theme variables, forced-color settings, and cascade order. If local and CI results differ, compare browser build, viewport, color scheme, locale, fonts, and animation preferences before accepting a more permissive value.

Use the process for debugging Playwright visual snapshot CI diffs when a style passes but the marker is misplaced or clipped. Computed style can prove margin-inline-start without proving the final inline layout under every translation. A focused screenshot can expose wrapping and overlap that property-by-property assertions miss.

Keep matcher context intact. Playwright's TestInfoError.errorContext, described in the official API reference, may add ARIA context to failed locator assertions. It does not replace the computed CSS expected and received values. Preserve both rather than wrapping the error in a message that discards the original matcher detail.

For keyboard-dependent states such as focus rings implemented with pseudo-elements, assert focus first through toBeFocused, then assert the pseudo style. Continue with the relevant action and outcome. The keyboard navigation guide covers focus order and activation, which a focus-ring color assertion cannot prove.

Govern Pseudo-Element Assertions in CI

Pin the runtime inputs that affect CSS: Playwright and browser versions, viewport, color scheme, reduced motion, forced colors when in scope, locale, device scale, and font assets. Record those settings in the project name or failure metadata. A color mismatch without theme information is slow to triage and easy to mislabel.

Limit assertions to requirement-bearing properties. Generated text, visibility mechanism, one critical color, or a defined geometric relation may deserve protection. Testing every margin, font weight, transform matrix, and transition duration copies the stylesheet into the test suite and turns ordinary refactoring into noise.

Separate release policies by failure class. Missing required semantics should block immediately. A lost required visual cue should block the supported theme or viewport. A browser-only serialization difference needs investigation and an owned compatibility decision. An unavailable font or stylesheet is an environment or asset failure, not permission to update expected values.

Review changes with before-and-after evidence. If generated wording changes, include localization and semantic impact. If only color changes, include the design token and contrast review. If the originating element changes, show that the interaction locator still reflects user-facing semantics. The AI-generated Playwright evidence checklist can prevent generated tests from asserting arbitrary CSS that happened to appear in one run.

Centralize only stable policy. A small custom assertion can combine native required state with the approved marker, but it should retain Playwright's expected, received, locator, and timeout detail. Use the custom matcher guide before introducing a wrapper that every form test will depend on.

Frequently Asked Questions

How do I assert a CSS pseudo-element in Playwright?

Locate the real element that owns the pseudo-element, then call expect(locator).toHaveCSS with the property, expected computed value, and { pseudo: 'before' } or { pseudo: 'after' }. Playwright retries the assertion. The option values omit the CSS colons, so do not pass ::before or ::after.

Which pseudo-elements does toHaveCSS support?

In Playwright 1.61.1, the typed pseudo option accepts only before and after. It does not accept marker, placeholder, selection, or arbitrary pseudo selectors. For an unsupported pseudo-element, choose a targeted screenshot or a carefully wrapped getComputedStyle evaluation, then document the narrower diagnostics and retry behavior.

Why does the CSS content value include quotation marks?

toHaveCSS compares the browser's computed value, not the authored stylesheet token. For generated content, computed style commonly returns a serialized string such as "Required" with quotes represented in the JavaScript value. Inspect the received value in the matcher failure and use an exact string or purposeful regular expression based on the contract.

Can a pseudo-element assertion prove accessibility?

No. It proves a computed style on generated before or after content. It does not prove that the information has a reliable accessible name, description, error relation, focus behavior, or announcement. Keep semantic requirements in HTML and ARIA, then test them with role locators, accessibility assertions, keyboard flows, and audits.

How can CI keep pseudo-element assertions stable?

Pin Playwright and browser versions, set viewport and color scheme, control fonts and animation, and wait for the product state that activates the pseudo-element. Assert only styles tied to an owned requirement. Separate browser or environment drift from product failures, and retain a focused screenshot plus matcher context when diagnosis needs pixels.

Apply the Layered Check in QABattle

Choose one visual cue and write three claims: the user state that activates it, the semantic property that carries its meaning, and the computed pseudo style that renders it. Break each layer separately. The resulting failures should identify state, semantics, or cascade without relying on a full-page screenshot to explain everything.

Practice that separation in QABattle battles. Use a form or interaction challenge, assert the behavior first, then add one before or after style check that protects a real requirement. This produces a focused regression test and a reviewable failure instead of a brittle copy of the component stylesheet.