How to Use Happo with Next.js and Storybook

Short answer: In a Next.js project that already uses Storybook, use Storybook stories to define isolated component states, then configure Happo’s Storybook integration to capture those stories and compare them with a baseline. Run the capture in CI so pull requests include visual results for review. Storybook supplies the component states; Happo checks how they look. Interaction tests can help reach transient states such as an open menu or an error message before capture.

This is a Storybook-based visual testing workflow for a Next.js codebase. The available Happo documentation does not establish a dedicated Next.js plugin, a required Next.js build mode, or a tested version pairing, so use Happo’s current setup instructions for exact installation commands and configuration: Happo’s Storybook screenshot testing guide.

1. Start with the components and states you need to protect

Storybook is the source of the rendered examples. Before configuring visual comparisons, check that important components and their meaningful visual variants already have stories. A page in the running Next.js application is not automatically covered just because it uses those components.

Cover high-use components and visually sensitive shared components.
Represent important variants such as disabled, loading, error, selected, and responsive states.
Use realistic content, including long labels or empty values where they can affect layout.
Keep each story focused enough that a visual difference has a clear owner and cause.

Happo’s integration article describes a working Storybook and stories as the starting point. It names the happo.io and happo-plugin-storybook packages, but exact current versions and setup syntax should be taken from Happo’s live setup instructions because package details can change. See Happo’s Storybook integration article.

2. Configure Happo to capture the Storybook

Follow Happo’s current Storybook setup for installing and configuring its integration. Connect the configuration to the Storybook instance or build used by your project, and make sure the CI job can access any required credentials through your CI provider’s secret mechanism.

The sources available for this guide do not verify current package versions, exact command-line flags, configuration-file syntax, environment variable names, or a Next.js and Storybook compatibility matrix. Avoid copying stale configuration from an older tutorial. Validate the instructions against Happo’s current docs and the versions in your repository.

Next.js matters here as the application framework that owns the components and their dependencies. Happo’s documented integration path in this workflow is through Storybook; do not infer that a particular Next.js export or server mode is required.

3. Capture transient states with interaction tests

A story can render a stable state directly. Some states require an action, such as opening a menu, hovering a control, or submitting a form to reveal an error. Storybook interaction tests can drive the component into those states so the screenshot captures the intended result.

Use visual comparisons to catch appearance changes, and keep interaction assertions for behavior. A screenshot can show that an error message is present and positioned correctly; it does not by itself prove that submitting invalid input triggers the right validation logic.

Happo’s Storybook offering describes capturing interaction-driven states and also lists automated accessibility regression checks as an option for the same screenshot runs. Treat accessibility checks as an additional check, not a replacement for accessible component implementation and testing.

4. Pick browser and viewport coverage deliberately

Choose targets based on the browsers and screen sizes your product supports and the layout risks in the component. Happo’s Storybook page lists Chrome, Firefox, Safari, Edge, and iOS Safari, as well as responsive viewport coverage. That does not mean every project needs every browser and viewport combination.

Coverage decision	Practical approach
Browsers	Include the browsers that matter to your supported audience and the components with browser-specific styling risk.
Viewports	Choose representative widths around the layouts and breakpoints your UI actually supports.
State combinations	Prioritize states that materially change layout or user understanding; avoid multiplying every state by every target without a reason.

A broad matrix can reveal more issues but also produces more snapshots to review. Expand coverage when it addresses a real compatibility risk.

5. Run visual comparisons in CI

Add the Happo capture to your continuous integration workflow so pull requests produce reviewable visual comparisons. Happo describes pull-request feedback and review links. The exact CI configuration depends on your provider and current Happo instructions, so use those sources rather than assuming a particular script or integration syntax.

Make sure CI can build or serve the Storybook in the way Happo’s current setup expects.
Provide required credentials as protected CI secrets.
Run the visual capture for relevant changes and expose the resulting review link on the pull request.
Have a reviewer inspect differences and decide whether each one is intended.

Happo announced GitLab support in September 2026 and described it as experimental at publication. Check the current status before treating it as a supported production integration: Happo’s GitLab announcement.

6. Review diffs and reduce noisy changes

Happo describes side-by-side, highlighted-diff, and swipe comparison views. It also documents controls intended to reduce noise, including color-delta tolerance, silencing animations, and waiting for fonts and asynchronous assets. These help make comparisons easier to review, but a tolerance setting should not hide changes your team needs to detect.

Review whether a difference is a desired design change, a regression, or an unstable dependency.
Keep animation and asynchronous asset behavior consistent with the test’s purpose.
Set color tolerance conservatively and check that it does not obscure meaningful small changes.
When a failure is intermittent, investigate external assets and timing before simply accepting a new baseline.

Happo’s September 2026 article describes restricting snapshot network requests with per-target allowedHostnames. It says the option was off by default at publication and that a future major-version change was planned; check current behavior and configuration before relying on it. Add only the hosts needed for fonts and images, then confirm those resources still load. Happo reported one customer’s flaky variants falling from about 2,000 to about 20 after rollout; that is a customer-specific report, not a general expected result. See Happo’s network request guidance.

7. Use partial runs carefully

Happo documents an --only feature that can limit a run to story files selected by a team’s dependency analysis. This can reduce snapshot volume, but it is only as safe as the logic that identifies affected stories.

Prefer a full run when a change has broad or uncertain impact, including changes to shared packages or Storybook configuration. Dynamic loading and implicit dependencies can make static dependency analysis miss affected stories, so validate the selector against real changes and retain a full-run fallback.

Happo reported that wiring --only into its own Storybook build reduced snapshot volume by 40%. That is Happo’s internal result, not a promise about another repository’s runtime or bill. Details: Happo’s coverage and snapshot volume article.

8. Troubleshooting

Symptom	Likely cause	What to check
A component or state is missing from the report	It has no Storybook story, is excluded by configuration, or was omitted from a partial run.	Confirm the story exists and is included; run the full set to determine whether dependency selection is responsible.
A transient state never appears	The state requires an interaction that the story does not perform, or the action does not complete before capture.	Use a Storybook interaction test to reach the state and confirm its assertions independently.
Images or fonts differ between runs	Asynchronous assets, external requests, or timing vary between captures.	Check Happo’s settling behavior, required asset hosts, and current network restriction settings; remove unnecessary external dependencies where practical.
Only some browser or viewport captures fail	The target exposes a browser-specific layout issue, unsupported assumption, or target-specific configuration problem.	Inspect the failing target and reproduce the relevant story at that browser and viewport before changing the baseline.
Every pull request produces too many snapshots	The run captures unnecessary story and target combinations.	Prioritize meaningful state and browser coverage; consider Happo’s `--only` flow only after validating dependency selection and keeping a full-run fallback.
The CI integration cannot connect or authorize	Credentials, permissions, or setup instructions do not match the current integration.	Recheck Happo’s current setup documentation and CI secret configuration; do not assume old environment variable names remain valid.
GitLab setup behaves differently from expected	The announcement described GitLab support as experimental at publication, and support status may have changed.	Verify Happo’s current GitLab documentation and status before relying on the integration.

9. Performance, reliability, and cost

Capture volume grows with the number of stories, browser targets, viewport sizes, and runs. Keep the matrix tied to user impact, and use affected-story selection only when the dependency analysis is trustworthy. External requests can add variability; Happo’s documented hostname controls are one way to constrain them, subject to the current configuration and defaults.

Happo’s May 2026 article says pricing is per snapshot, with visual and accessibility snapshots combined. The research available for this article does not establish current plan prices or thresholds, so check Happo’s current pricing information for your expected volume. Estimate using the stories, targets, and run frequency in your own CI workflow rather than extrapolating from Happo’s internal or customer examples.

10. Or skip the browser setup

For a website screenshot outside your component test workflow, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. One GET request returns a PNG, JPEG, WebP, or PDF. It complements a Storybook visual test suite; it does not replace story-level component coverage.

See the ScreenshotNeo API documentation. cURL example:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, popups, and chat widgets are removed before the shot, with each cleanup step configurable.
Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

FAQ

Does Happo need a special Next.js plugin?

The documented workflow here uses Happo’s Storybook integration. The available sources do not establish a separate Next.js plugin.

Do visual tests replace Storybook interaction tests?

No. Visual comparisons check appearance; interaction tests exercise behavior and can prepare transient states for capture.

Should every story run in every browser?

Choose browser and viewport combinations based on supported users and layout risk. A larger matrix is useful when it covers a real risk, but it also creates more snapshots to review.

Can partial runs be trusted for every change?

Only if dependency selection accounts for the project’s relationships. Use full runs when impact is global or uncertain, and validate partial selection against changes that should affect shared stories.