How to Run the Storybook Test Runner in CI

The Storybook test-runner drives Playwright against a running Storybook, so CI must build it, serve it, and wait for it before tests start.

The @storybook/test-runner executes each story as a test using Playwright Chromium. The recurring CI work is building a static Storybook, serving it, and gating the runner on the server being ready.

Why it fails in CI

The runner starts before Storybook is serving → connection refused.
Playwright browsers were never installed → launch fails.
A long-rendering story exceeds the default timeout.

Install and run it reliably

Build a static Storybook, serve it, install Playwright Chromium, and use a wait-on helper so the runner only starts once the server responds.

Terminal

npm ci
npx playwright install --with-deps chromium
npm run build-storybook

npx concurrently -k -s first -n SB,TEST \
  "npx http-server storybook-static --port 6006 --silent" \
  "npx wait-on tcp:6006 && npx test-storybook --url http://127.0.0.1:6006"

Cache & speed

Cache the Playwright browser cache keyed on the Playwright version, and reuse a built storybook-static artifact across jobs. Browser launches can be flaky; auto-retry and larger managed runners help.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/ms-playwright
    key: playwright-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}

Common errors

connect ECONNREFUSED 127.0.0.1:6006 → wait for the static server before running tests.
Executable doesn't exist → run playwright install --with-deps chromium.
Test timed out → raise the per-test timeout for heavy stories.

Key takeaways

Build and serve a static Storybook, then wait for it before tests.
Install Playwright Chromium for the test-runner.
Use wait-on to avoid racing the static server.