Skip to main content
Version: Current

Getting started

Happo is a visual regression testing service with support for multiple browsers and accessibility testing. It renders your UI in real browsers, takes screenshots, and compares them against a previous version so you can see exactly what changed before it ships. Set it up to run in CI and get build statuses posted directly to your pull requests.

This page walks you through a first-time setup, from account to first report.

How Happo works​

A few terms show up throughout these docs:

  • A snapshot is one screenshot of one component in one variant — for example Button / disabled.
  • A target is a browser and screen size (or an accessibility check) to render in. Every snapshot is rendered once per target.
  • A test suite is the full set of components and variants Happo renders. You don't write it from scratch — an integration turns something you already have (Storybook stories, Cypress or Playwright tests, a list of URLs) into one.
  • A report is everything produced by a single run of your test suite.
  • A comparison diffs two reports against each other, usually the report for your branch against the baseline report from your main branch.

A run looks like this: the happo CLI builds your test suite and uploads it, Happo renders every snapshot in every target on its own infrastructure, and the resulting report is compared against a baseline. You then review the diffs and accept or reject them.

Screenshots are taken asynchronously, outside of your test run. That means the CLI finishes before the screenshots are done, and prints a URL where you can follow along.

Before you begin​

  • A Happo account. If you don't have one, sign up for a free trial at happo.io/signup.
  • Your API tokens. apiKey and apiSecret are available at happo.io/account.
  • A project with a package.json. The happo CLI is an npm package. For native apps and other environments that don't run in a browser, use the API directly instead.

Migrating? If you're coming from the legacy happo.io, happo-cypress, or happo-playwright packages, follow the migration guide instead of this page.

Step 1: Choose an integration​

The integration decides where your test suite comes from. Pick the one that matches what your project already has — you generally only need one.

If your project has…Use
StorybookStorybook
Cypress end-to-end testsCypress
Playwright end-to-end testsPlaywright
A public website you want to screenshotPages
None of the above, or a custom setupCustom bundle

Storybook is the quickest path if you already have stories: every story becomes a snapshot without any extra test code. The Cypress and Playwright integrations reuse your existing end-to-end tests, and you add screenshot calls at the points you care about. The custom integration lets you build the test suite yourself with React or any other JS framework.

The rest of this page uses Storybook for its examples, but the setup steps are the same for every integration.

Step 2: Install the CLI​

In your project, install the happo package.

npm install --save-dev happo

Step 3: Add a configuration file​

Save happo.config.ts (or .js) in the root directory of your project, right next to package.json. Here's a complete example to get you started, using a Storybook integration with desktop and mobile screenshot targets plus an accessibility target:

happo.config.ts
import { defineConfig } from 'happo';

export default defineConfig({
  apiKey: process.env.HAPPO_API_KEY,
  apiSecret: process.env.HAPPO_API_SECRET,

  // Optional. Omit it and the default project is used.
  project: 'default',

  integration: {
    type: 'storybook',
  },

  targets: {
    'chrome-desktop': {
      type: 'chrome',
      viewport: '1024x768',
    },
    'chrome-mobile': {
      type: 'chrome',
      viewport: '375x667',
    },
    accessibility: {
      type: 'accessibility',
      viewport: '1024x768',
    },
  },
});

The integration option tells Happo where your test suite comes from — swap in Cypress, Playwright, or another integration as needed. Each integration page lists the extra setup it needs, such as the import 'happo/storybook/register' line Storybook expects in .storybook/preview.js.

Each entry under targets runs your test suite across a different browser, screen size, or check. Adjust these to match what you care about — see Supported browsers for the full list of browsers we support and Accessibility testing for more on accessibility targets.

Start small. Every target multiplies the number of screenshots taken (and the quota used), so it's easier to add targets later than to trim a slow suite.

Configuration has the full list of options.

Step 4: Provide your API tokens​

The example above reads the tokens from environment variables. Set them in your shell before running Happo locally:

export HAPPO_API_KEY=your-api-key
export HAPPO_API_SECRET=your-api-secret

While you can specify apiKey and apiSecret directly as strings in the config file, this isn't something we recommend — the tokens grant access to your Happo account, and config files tend to end up in version control. See apiKey and apiSecret for details.

If you leave both options out entirely, the CLI opens a browser and authenticates you interactively, which is convenient for a first local run. Interactive authentication does not work in CI, so you'll need real tokens there — see Continuous Integration.

Step 5: Create your first report​

Every integration has its own way of executing the test suite. For Storybook, Pages, and custom integrations, that's the happo command:

npx happo

Cypress and Playwright wrap your existing test command instead, for example npx happo -- playwright test. Refer to the docs for your integration for the exact command.

The CLI prints a couple of URLs when it's done:

[HAPPO] Async report URL: https://happo.io/a/8/async-reports/2387412
[HAPPO] Async comparison URL: https://happo.io/a/8/jobs/2233741

Open the async comparison URL to watch the screenshots come in.

Your first run has nothing to compare against, so there won't be any diffs — it establishes the baseline. The interesting part comes on the next run, once you've changed something. Make a small visual tweak to one of your components, run Happo again, and you should see it show up as a diff you can review.

If the first run doesn't look right — missing styles, unexpected diffs, or an error from the CLI — head to Debugging.

Step 6: Add Happo to CI​

Running Happo locally is useful while you iterate, but the real value comes from running it on every pull request, where Happo compares your branch against the baseline from your main branch and posts a status back to the PR.

Follow the Continuous Integration guide — it has ready-made examples for GitHub Actions, CircleCI, Travis CI, and Azure DevOps. Make sure the job also runs on pushes to your default branch, so PR builds have a baseline to compare against.

Next steps​

I need support!​

We're here to help — send an email to support@happo.io and we'll assist you.