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 storycrawlerVerified import paths — ran on the pinned version, not inferred.
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.
Upgrade your Storybook project to version 7 or higher, or downgrade `storycrawler` to a compatible v4 release if maintaining older Storybook versions.
Upgrade your Node.js runtime environment to version 18 or newer. Check your `engines` field in `package.json`.
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.
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.
Replace `require()` statements with ES module `import` syntax. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
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.
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.
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.