Why not vanilla Playwright?
expect(page).toHaveScreenshot()
excels for static pages with reliable baselines. For highly dynamic UIs, Stably’s prompt assertions cover intent-based validation that Playwright’s pixel diffing cannot reliably express.Installation
Install the Stably Playwright test integration and import it in place of the Playwright test runner:toMatchScreenshotPrompt
Use prompt-based visual assertions to validate your UI without maintaining golden screenshots.Basic Usage
How It Works
toMatchScreenshotPrompt
performs intelligent visual validation in three steps:
- Stabilization: Waits for the page to stabilize and captures the screenshot.
- AI Analysis: Evaluates the screenshot against your prompt using Stably’s vision model.
- Assertion Outcome: If the prompt is satisfied, the assertion resolves. Otherwise it throws with a natural-language explanation describing what the AI found missing or inconsistent.
Method Signature
prompt
- Human-readable description of what should appear on screenoptions
- Standard Playwright screenshot options (fullPage, animations, etc.)
Common Use Cases
Validate PersonalizationAdvanced Options
All standard Playwright screenshot options are supported:fullPage
- Capture the full scrollable pageanimations
- Set to'disabled'
to disable CSS animationsclip
- Capture a specific rectangular areatimeout
- Maximum time to wait for stabilization
Scoping with Locators
Combine with Playwright locators to scope assertions to specific components:When to Use
-
Use
toMatchScreenshotPrompt
when:- The page can change materially between runs while maintaining semantic intent
- You need to validate invariants (e.g., “shows revenue chart”) even when the UI layout or styling changes
- You have dynamic content (personalized data, A/B tests, real-time updates)
- Layout and styling evolve frequently and describing intent is easier than maintaining golden snapshots
-
Use
expect(page).toHaveScreenshot()
when:- You have a stable, non-dynamic screen
- Minor rendering differences are acceptable (Stably’s auto-heal handles font rendering, anti-aliasing, and subtle visual variations)
- Pixel-perfect matching is important and the page structure rarely changes
Stably offers auto-heal for
toHaveScreenshot()
that handles minor rendering differences like font anti-aliasing and subtle layout shifts. However, for pages where major structural changes are acceptable as long as semantic invariants remain valid, use toMatchScreenshotPrompt
instead. Prompt-driven assertions tolerate variance, provide contextual reasoning, and continue to work even when UI components are re-arranged or re-styled.Upcoming Features
Model Configuration Select the vision model per project or per suite (coming soon). Prompt Result Caching Avoid repeat AI calls when the captured screenshot matches a stored cache key—AI evaluation will only run when the image actually changes (coming soon).Future versions will let you provide a cache name or enable caching globally. When cached, the SDK will only call AI if the newly captured frame differs from the previous cached copy.
toMatchAriaPrompt (Coming Soon)
Stably is expanding prompt assertions beyond screenshots to support semantic validation directly on accessibility trees.Method Signature
Best Practices
- Write intent-focused prompts: Mention critical UI elements (primary CTA, key metrics, legal copy) rather than pixel-perfect descriptions.
- Stabilize before capture: Pair assertions with network and animation stabilization waits to reduce UI churn.
- Scope assertions: Use Playwright locators to focus on components that matter.
- Be specific: Provide enough detail in prompts for the AI to differentiate success states.
Troubleshooting
Prompt is too vague Refine the description with salient visual cues. The AI needs enough detail to differentiate success states.References
- Stably Playwright SDK:
@stablyai/playwright-test
- Playwright screenshot options: Playwright PageAssertions
- Related feature: Auto-heal for Playwright tests