Buddy Visual Tests for Storybook (@buddy-works/storybook)

Visual regression testing for your Storybook, powered by Buddy and the bdy CLI.

@buddy-works/storybook is a thin proxy around bdy, packaged and documented specifically for Storybook workflows:

• Visual regression testing — upload your built Storybook to Buddy; every story becomes a snapshot that is rendered, compared against the baseline, and queued for review with visual diffs.
• Instant sharing — expose your local Storybook dev server through a public tunnel URL for quick reviews, without deploying anything.
• CI-ready — works in any CI provider (commit, branch, and PR metadata are detected automatically) and authenticates with a single token.

Installation

npm install --save-dev @buddy-works/storybook

This installs the bdy command into your project.

Authentication

Uploading requires your visual test suite token — there are two ways to provide it.

Option A — suite token in an environment variable

Copy the token from your visual test suite settings in Buddy and expose it as BUDDY_VT_TOKEN:

export BUDDY_VT_TOKEN=<your-suite-token>

Option B — sign in and link a suite

Sign in once, then link your project to a visual test suite. From the project root:

npx bdy login
npx bdy tests visual link

npx bdy tests visual link -w my-workspace -p my-project -s my-suite

link stores the selection in a .bdy/project.json file in the current directory, and upload resolves the suite token from it automatically. Run upload from the same directory, passing the path to the built Storybook.

Quick start

1. Build your Storybook

npm run build-storybook

2. Upload it

Pass the path to the built Storybook directory (the one containing index.html, iframe.html, and index.json — storybook-static by default):

npx bdy tests visual upload ./storybook-static

Without the path, upload expects the current directory to be the built Storybook.

The CLI reads the story index, uploads the build, and creates a visual test session in Buddy. Open the session in Buddy to review per-story diffs and approve or reject changes.

Running in CI

In CI, use Option A: provide the suite token via the BUDDY_VT_TOKEN environment variable.

Example GitHub Actions job:

visual-tests:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with:
        node-version: 24
    - run: npm ci
    - run: npm run build-storybook
    - run: npx bdy tests visual upload ./storybook-static
      env:
        BUDDY_VT_TOKEN: ${{ secrets.BUDDY_VT_TOKEN }}

The same pattern works in Buddy pipelines, GitLab CI, CircleCI, Jenkins, and others — CI and git metadata (branch, commit, pull request) are detected automatically.

Suggested package.json scripts

{
  "scripts": {
    "build-storybook": "storybook build",
    "visual-tests": "npm run build-storybook && bdy tests visual upload ./storybook-static"
  }
}

Share your local Storybook

Expose the Storybook dev server through a public HTTPS tunnel:

npm run storybook            # serves on http://localhost:6006
npx bdy tunnel http 6006

You get a public URL you can send to anyone. Restrict access when needed:

npx bdy tunnel http 6006 -a user:pass   # basic auth
npx bdy tunnel http 6006 -w 1.1.1.1     # IP allowlist

You can also serve an already-built Storybook directly from disk:

npx bdy tunnel http -n my-storybook -s ./storybook-static

License

MIT