Skip to main content

Getting started

Happo is a cross-browser screenshot testing service. It helps you test the visual 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 using the Static bundle integration, you can bring your own javascript bundle and have full control over the build phase and execution.
  • 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 other js framework apps, you can use Happo Examples.
  • 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. The first thing is to install the happo.io npm module:

npm install --save-dev happo.io

You also need a configuration file. Save .happo.js in the root directory of your project (right next to where the package.json file is located). This example is showing the minimum required configuration:

const { RemoteBrowserTarget } = require('happo.io');

module.exports = {
  apiKey: process.env.HAPPO_API_KEY,
  apiSecret: process.env.HAPPO_API_SECRET,

  targets: {
    'chrome-desktop': new RemoteBrowserTarget('chrome', {
      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

You can add more than one target if you want to run tests across multiple browsers and/or screen sizes. See Supported browsers for a full list of browsers we support.

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.