Playwright Testing for Storybook Component Library Documentation

Modern web applications require thorough testing strategies that account for regional requirements, diverse user bases, and complex technical architectures. This guide provides actionable Playwright patterns for your specific context.

Introduction

Run Playwright tests against Storybook stories to validate interactive component behavior, accessibility, and visual consistency. This guide covers the essential patterns, configurations, and strategies to handle this scenario reliably in your Playwright test suite.

Understanding the nuances of this topic allows your team to ship with confidence, reduce flakiness, and maintain high-quality automation across different environments.

Architecture Overview

graph TD
    Storybook["Storybook Server :6006"] --> Story["Component Story"]
    Story --> Test["Playwright Test"]
    Test --> Visual["Visual Check"]
    Test --> A11y["Accessibility"]
    Test --> Behavior["Interaction"]

This structure ensures clean separation of concerns and maintainable test code.

Implementation Flow

sequenceDiagram
    participant Test as Playwright Test
    participant App as Application
    participant API as Backend / Mock API

    Test->>App: Navigate and interact
    App->>API: Trigger API call
    API-->>App: Return response
    App-->>Test: UI state updated
    Test->>Test: Assert outcome

Step-by-Step Guide

Follow this implementation to set up the pattern in your test suite.

1. Core Implementation

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

test('Button story renders all variants', async ({ page }) => {
  await page.goto('http://localhost:6006/iframe.html?id=components-button--primary');
  const button = page.getByRole('button', { name: 'Button' });
  await expect(button).toBeVisible();
  await expect(button).toHaveCSS('background-color', 'rgb(37, 99, 235)');
  // Test hover state
  await button.hover();
  await expect(button).toHaveCSS('background-color', 'rgb(29, 78, 216)');
});

2. Run and Verify

# Run this specific test file
npx playwright test --grep "Playwright Testing for"

Run with UI mode for debugging
npx playwright test --ui

Run across all browsers
npx playwright test --project=chromium --project=firefox --project=webkit

3. View Test Report

npx playwright show-report

Reference Table

Best Practices

Common Pitfalls

Frequently Asked Questions

How to test Storybook stories with Playwright?

Navigate to the Storybook iframe URL pattern /iframe.html?id=component-name--story-name and test as normal.

Can Playwright test Storybook Controls (args)?

Pass args via URL parameters like ?args=disabled:true and verify the component reflects the prop change.

How to test Storybook decorators?

Stories with decorators render in the full story page. Test the complete iframe URL to include decorator context.

Can I run Playwright tests against Chromatic?

Yes, Chromatic provides a story URL format. But Chromatic itself handles visual testing separately.

How to test Storybook accessibility for all stories?

Loop through story URLs and run axe-core checks on each one to catch component-level accessibility issues.

Summary

Run Playwright tests against Storybook stories to validate interactive component behavior, accessibility, and visual consistency. By following these patterns, your team can build a reliable, maintainable automation suite that works across environments and handles edge cases gracefully.

Related Articles