Storybook Component Test Runner (Experimental)

Common errors

• Error: Cannot find module 'test-runner-with-snap-speed-exp' from '<your-project-path>'

  cause The package might not be installed, or there's a problem with module resolution (e.g., trying to `require` an ESM-only package in a CommonJS context).
  fix Ensure the package is installed: `npm install test-runner-with-snap-speed-exp`. If using `import`, ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• Error: Playwright browser did not launch correctly. Make sure you have installed browser binaries.

  cause Playwright binaries are not installed or are corrupted, or a `playwright install` command was missed after installation.
  fix Run `npx playwright install` to download the necessary browser binaries. Ensure your environment has sufficient disk space and network access for the download.

• Error: Storybook URL 'http://localhost:6006' is not reachable or returned a non-200 status.

  cause The Storybook instance is not running or is accessible on a different port/URL than configured in the test runner.
  fix Verify your Storybook server is running (`npm run storybook` or equivalent). Check the port and host. Update the `storybookUrl` in your `test-runner-with-snap-speed-exp` configuration to match the actual Storybook URL.

Warnings

• breaking As a `0.0.1` package, the API is highly unstable and subject to frequent breaking changes without prior notice. Expect `import` paths, function signatures, and configuration options to change between minor or even patch versions.
  Fix: Always refer to the latest (or your installed) package documentation. Pin specific patch versions (`0.0.1`) and review `CHANGELOG.md` or `package.json` for updates.
• gotcha This package relies heavily on external tools like Storybook and Playwright. Version incompatibilities between these dependencies can lead to unexpected failures, especially with Playwright's rapid release cycle.
  Fix: Ensure that your `storybook`, `playwright`, and `test-runner-with-snap-speed-exp` versions are compatible. Check their respective documentation or GitHub issues for known compatibility matrices. Use `npm list <package>` to check installed versions.
• gotcha Performance (`snap-speed`) claims are likely experimental. Large Storybook setups or complex components might experience slow test execution or high resource consumption, negating the 'speed' aspect.
  Fix: Start with a small subset of stories. Profile test runs using Playwright's tracing tools. Consider optimizing Storybook build performance or splitting large test suites.

Install

• npm install test-runner-with-snap-speed-exp npm
• yarn add test-runner-with-snap-speed-exp yarn
• pnpm add test-runner-with-snap-speed-exp pnpm

Imports

• runStoriesTests
  wrong:

  const runStoriesTests = require('test-runner-with-snap-speed-exp');

  correct:

  import { runStoriesTests } from 'test-runner-with-snap-speed-exp';

  The library is likely ESM-first given modern JavaScript trends and its experimental nature. CommonJS `require` might not work or require specific configuration.
• Config

  import type { Config } from 'test-runner-with-snap-speed-exp';

  Type imports are crucial for TypeScript users to get correct type inference for configuration objects or test definitions.
• toHaveNoViolations

  import { toHaveNoViolations } from 'test-runner-with-snap-speed-exp/matchers';

  Assuming a common pattern where matchers for assertions are exported from a subpath, similar to Jest or Playwright expectations.

Quickstart

This quickstart demonstrates how to configure and run tests against a Storybook instance using the `test-runner-with-snap-speed-exp`. It sets up a basic Playwright environment, navigates to individual stories, and performs a visual snapshot test for each. It's designed to be run as part of a CI/CD pipeline or local development process.

import { runStoriesTests } from 'test-runner-with-snap-speed-exp';
import { expect } from '@playwright/test';

// Assuming a Storybook instance is running at http://localhost:6006
const storybookUrl = process.env.STORYBOOK_URL ?? 'http://localhost:6006';

const config = {
  storybookUrl: storybookUrl,
  /**
   * Function to execute before all stories are loaded.
   * Useful for global setup like custom Playwright setup or mocking.
   */
  setup: async ({ page }) => {
    await page.goto(storybookUrl);
    console.log(`Navigated to Storybook at ${storybookUrl}`);
  },
  testMatch: ['**/*.stories.ts?(x)', '**/*.stories.js?(x)'],
  /**
   * Define custom test logic for each story.
   * This example performs a basic snapshot comparison.
   */
  test: async ({ page, story, test }) => {
    test(`Story: ${story.title} - ${story.name}`, async () => {
      await page.goto(story.url);
      // Wait for the story to fully render and stabilize
      await page.waitForSelector('#root div');

      // Simple visual snapshot test using Playwright's API
      // In a real scenario, a more robust snapshot library would be integrated.
      const screenshotPath = `screenshots/${story.title.replace(/ /g, '_')}-${story.name.replace(/ /g, '_')}.png`;
      await expect(page).toHaveScreenshot(screenshotPath, { maxDiffPixelRatio: 0.05 });
      console.log(`Snapshot taken for ${story.title}/${story.name}`);
    });
  },
};

// Execute the test runner
runStoriesTests(config).catch(error => {
  console.error('Test runner failed:', error);
  process.exit(1);
});