Skip to main content
Version: Current

Getting started

Happo is a visual regression testing service with support for multiple browsers and accessibility testing. It helps you test the appearance of your application by automatically comparing the UI with a previous version. Set it up to run in CI and get build statuses posted directly to your pull requests.

Choose an integration​

The first thing you want to do is to set up a test suite for Happo. A test suite consists of a set of components and variants of those components. There are many ways to do this, and it all depends on your existing tech stack, your application, experience with other test frameworks, and more.

  • A Storybook application can serve as the test suite driver for Happo.
  • By integrating Happo with Cypress or Playwright, you can turn your end-to-end tests into a Happo test suite.
  • If you want to test an existing (public) website, you can use the pages option.
  • If you want to create a custom test suite for React or another JS framework, you can use the Custom bundle integration.
  • For native apps and others not running in a browser, use the API directly.

Basic setup​

Independently of how you end up integrating Happo in your project, there are some steps you always need to take care of.

In your project, install the happo package.

npm install --save-dev happo

You also need a configuration file. Save happo.config.ts (or .js) in the root directory of your project (right next to where the package.json file is located). 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,

  project: 'default',

  integration: {
    type: 'storybook',
  },

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

While you can specify apiKey and apiSecret directly as strings, this isn't something we recommend. Use environment variables instead.

The API tokens (apiKey, apiSecret) come from your account at happo.io. If you don't have an account already, you can sign up for a free trial at happo.io/signup

Note: If you're migrating from legacy Happo packages, see the migration guide for detailed instructions.

Each entry under targets runs your test suite across a different browser, screen size, or check. Adjust these to match the browsers and viewports you care about—see Supported browsers for a full list of browsers we support and Accessibility testing for more on accessibility targets. The integration option tells Happo where your test suite comes from; swap in Cypress, Playwright, or another integration as needed.

Creating your first report​

All integrations have their own way of executing the test suite. Refer to the docs for the integration of your choice for an example of how to proceed.