Expose Playwright media and environment emulation APIs

[schalkneethling]

Summary

Expose first-class css-expect API support for Playwright media and environment emulation so CSS custom function and future mixin expectations can be tested under realistic user/browser conditions.

Context

Playwright supports emulating CSS-relevant media features via page.emulateMedia(), including:

• prefers-color-scheme via colorScheme
• prefers-reduced-motion via reducedMotion
• forced-colors via forcedColors
• prefers-contrast via contrast
• screen / print media via media

These would be especially useful for testing responsive/adaptive CSS custom functions today and native mixins later. For example, a function might return different tokens depending on color scheme, forced colors mode, reduced motion preferences, contrast preferences, or print media.

Possible API

Expose an environment/emulation method on the runtime, potentially alongside the viewport resize API:

const css = await createCssExpect({ css: source });

await css.emulate({
  viewport: { width: 1440, height: 900 },
  colorScheme: "light",
  reducedMotion: "no-preference",
});

await css.function("--responsive-space", ["2rem"]).as("padding-top").equals("32px");

await css.emulate({
  viewport: { width: 390, height: 844 },
  colorScheme: "dark",
  reducedMotion: "reduce",
  forcedColors: "active",
  contrast: "more",
});

await css.function("--responsive-space", ["2rem"]).as("padding-top").equals("16px");

Alternative names: environment(), setEnvironment(), media(), emulateMedia(), or separate focused methods such as viewport() and media().

Acceptance criteria

• Runtime API can emulate colorScheme, reducedMotion, forcedColors, contrast, and media where supported by Playwright.
• The API can be used after createCssExpect() and before expectation calls.
• Existing viewport creation option continues to work.
• The API design composes cleanly with the proposed first-class viewport resize support.
• Tests cover at least one media-query-sensitive CSS function expectation.
• README documents examples for color scheme, reduced motion, forced colors, contrast, and print/screen media where practical.
• Diagnostics include active emulation state when practical, so failures are easier to interpret.

Notes

Some Playwright options are context-level or creation-time concerns rather than dynamic page-level emulation. This issue should start with the CSS media features exposed through page.emulateMedia() and avoid over-promising dynamic support for unrelated context options until investigated.