Registry / testing / storycrawler

storycrawler

JSON →
library5.0.1jsnpmunverified

Storycrawler is a TypeScript-first utility library designed for creating tools to crawl and interact with Storybook instances using Puppeteer. It enables developers to automate tasks such as visual regression testing, accessibility audits, and data extraction from Storybook stories by providing a structured API to manage connections to Storybook, launch and control Puppeteer browser instances, and execute tasks against individual stories. The current stable version is 5.0.1. Development is active with frequent releases, often aligning with major Storybook and Node.js LTS updates. Its key differentiators include a specialized API for managing Storybook connections, handling multiple browser workers for parallel story processing, and providing utilities like `MetricsWatcher` to ensure UI stability before interaction or data extraction. This abstracts much of the complexity typically associated with direct Puppeteer usage in a Storybook environment, making it a robust choice for build-time Storybook automation.

npm install storycrawler
INSTALL
IMPORT
SIG · STORYCRAWLER
S
storycrawler
testingjavascriptv5.0.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

StorybookConnection
import { StorybookConnection } from 'storycrawler'
const StorybookConnection = require('storycrawler').StorybookConnection
Storycrawler is an ESM-only package since v5.0.0. Named imports are the standard.
StoriesBrowser
import { StoriesBrowser } from 'storycrawler'
import StoriesBrowser from 'storycrawler/StoriesBrowser'
All core classes and functions are named exports from the main package entry point.
createExecutionService
import { createExecutionService } from 'storycrawler'
const createExecutionService = require('storycrawler').createExecutionService
This factory function is a named export for creating the story execution queue. CommonJS `require` is not supported in v5+.
MetricsWatcher
import { MetricsWatcher } from 'storycrawler'
import * as storycrawler from 'storycrawler'; new storycrawler.MetricsWatcher(...)
MetricsWatcher is a class used for observing and waiting for UI stability within a Storybook preview. It should be imported directly as a named export.

This example demonstrates how to connect to a Storybook instance, fetch its stories, launch multiple Puppeteer browser workers to process each story concurrently, wait for UI stability, and extract metrics like node count using the `storycrawler` API.

import { StorybookConnection, StoriesBrowser, StoryPreviewBrowser, MetricsWatcher, createExecutionService, } from 'storycrawler'; (async function () { // Connect to the target Storybook server. const storybookUrl = 'https://storybookjs.netlify.app/vue-kitchen-sink'; const connection = await new StorybookConnection({ storybookUrl }).connect(); // Launch Puppeteer process to fetch stories info. const storiesBrowser = await new StoriesBrowser(connection).boot(); // Item in stories has name, kind and id of the corresponding story const stories = await storiesBrowser.getStories(); // Launce Puppeteer browsers to visit each story's preview window(iframe.html) const workers = await Promise.all([0, 1, 2, 3].map(i => new StoryPreviewBrowser(connection, i).boot())); try { // `createExecutionService` creates a queue of the tasks for each story. const service = createExecutionService(workers, stories, story => async worker => { // Display story in the worker's preview window await worker.setCurrentStory(story); // Wait for UI framework updating DOM await new MetricsWatcher(worker.page).waitForStable(); // Extract information from the preview window. // You can access Puppeteer's page instance via `worker.page`. const m = await worker.page.metrics(); return { story, nodesCount: m.Nodes }; }); // `createExecutionService` register tasks but does not kick them. // Tasks in queue start via calling `.execute()`. const results = await service.execute(); results.forEach(({ story, nodesCount }) => console.log(`${story.id}: ${nodesCount}`)); } finally { await storiesBrowser.close(); await Promise.all(workers.map(worker => worker.close())); await connection.disconnect(); } })();
Debug
Known issues
breakingVersion 5.0.0 dropped support for Storybook versions 6 and older. Ensure your Storybook instance is on version 7 or newer for compatibility with `storycrawler` v5+.
fix
Upgrade your Storybook project to version 7 or higher, or downgrade `storycrawler` to a compatible v4 release if maintaining older Storybook versions.
affects: >=5.0.0
breakingVersion 5.0.0 changed the minimum supported Node.js version to 18.x. Previous major versions supported Node.js 12.x and above.
fix
Upgrade your Node.js runtime environment to version 18 or newer. Check your `engines` field in `package.json`.
affects: >=5.0.0
breakingVersion 5.0.0 transitioned `storycrawler` to be an ESM-only package. CommonJS `require()` statements are no longer supported for importing `storycrawler` modules.
fix
Migrate your consuming JavaScript/TypeScript project to use ES modules (`import`/`export` syntax). Ensure your `package.json` specifies `"type": "module"` or uses `.mjs` file extensions for module files.
affects: >=5.0.0
gotchaCompatibility with `puppeteer` versions is critical. `storycrawler` relies heavily on `puppeteer` for browser automation; ensure the installed `puppeteer` version is compatible with your Node.js version and the specific `storycrawler` major version.
fix
Refer to `storycrawler` and `puppeteer` documentation for recommended version pairings. Generally, updating both `storycrawler` and `puppeteer` to their latest stable versions often resolves compatibility issues.
affects: >=4.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax with `storycrawler` v5+, which is an ESM-only package.
fix
Replace `require()` statements with ES module `import` syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
Error: Storybook connection timed out
`storycrawler` failed to establish a connection with the target Storybook server, possibly due to an incorrect URL, the server not running, or network configuration issues.
fix
Verify that the `storybookUrl` provided to `StorybookConnection` is correct and that your Storybook server is running and accessible. Check any firewall or network proxy settings, or consider increasing the `serverTimeout` option if the server is slow to start.
Error: Failed to find element matching selector "[data-story-id='some-story-id']"
A CSS selector used within Puppeteer methods (`worker.page.$()`, `worker.page.click()`, etc.) could not locate the intended DOM element in the Storybook preview iframe. This often indicates a timing issue, an incorrect selector, or a change in Storybook's DOM structure.
fix
Implement robust waiting strategies using `MetricsWatcher.waitForStable()`, `worker.page.waitForSelector()`, or `worker.page.waitForFunction()` before interacting with elements. Double-check your CSS selectors for accuracy and specificity against the Storybook version you are targeting.
Error: Navigation to preview HTML timed out or failed.
The Storybook preview iframe failed to load or navigate to the story's HTML within the expected timeout, potentially due to a slow Storybook server, complex story rendering, or a network issue.
fix
Increase the navigation timeout via Puppeteer options. Review the story for any blocking resources or extremely long rendering times. Ensure the Storybook server is performing optimally.
Upgrade
Version history
5.0.1latest on npm
Audit
Dependencies
puppeteerrequiredCore dependency for browser automation; `storycrawler` uses it internally and exposes Puppeteer `Page` instances for direct interaction.
storybookrequiredThe target framework this library is built to interact with. Version compatibility between `storycrawler` and the Storybook instance is crucial for correct operation.
Agent activity
8 hits · last 30 days
node
6
OpenAI (training)
1
Resources
storycrawler — npm install storycrawler · libregistry