Happo

An open source library for integrating with happo.io - a visual and accessibility regression testing platform that helps you catch unintended changes in your applications.

📚 Documentation

For comprehensive documentation, visit docs.happo.io.

🚀 Features

• CLI Tool: Includes a command-line interface for easy integration
• Flexible Configuration: Support for multiple configuration file formats
• TypeScript Support: Built with TypeScript and provides full type definitions
• ES Modules: Uses modern ES modules for better tree-shaking and performance

📦 Installation

npm install happo --save-dev
# or
pnpm add happo --save-dev
# or
yarn add happo --dev

🛠️ Usage

Basic Configuration

Create a happo.config.ts file in your project root:

import { defineConfig } from 'happo';

export default defineConfig({
  apiKey: process.env.HAPPO_API_KEY!,
  apiSecret: process.env.HAPPO_API_SECRET!,
  targets: {
    'chrome-desktop': {
      type: 'chrome',
      viewport: '1280x720',
    },
    'firefox-desktop': {
      type: 'firefox',
      viewport: '1280x720',
    },
    'ios-safari': {
      type: 'ios-safari',
    },
  },
});

CLI Usage

Run Happo using the CLI:

npx happo

The CLI will automatically find your configuration file and run the visual regression test suite.

🔧 Configuration Options

Supported Configuration Files

The library automatically detects configuration files in the following order:

• happo.config.js
• happo.config.mjs
• happo.config.cjs
• happo.config.ts
• happo.config.mts
• happo.config.cts

Key Configuration Properties

• apiKey & apiSecret: Authentication credentials for happo.io
• integration: Set up the integration type
• targets: Target configurations, including regular browsers and accessibility targets
• project: Optional project name
• deepCompare: Optional settings for how diffs are computed
• blockApproval: Optional conditions that block a comparison from being approved

Blocking Approval

Use blockApproval to prevent a comparison from being approved until certain problems are resolved:

export default defineConfig({
  // ...
  blockApproval: {
    // Block when the report has examples that failed to render
    renderErrors: true,
    // Block when the comparison introduces new accessibility violations
    accessibilityViolations: true,
    // Block when a page starts to scroll sideways (needs a target with
    // `detectHorizontalOverflow`)
    horizontalOverflow: true,
  },
});

Since this lives in the config, you can enable a condition in a single pull request (and fix the problems there) without affecting other work in the repository.

Browser Targets

Supported browser types:

• Desktop: chrome, firefox, edge, safari, accessibility
• Mobile: ios-safari, ipad-safari

Each target supports advanced options like:

• Viewport sizing
• Maximum dimensions
• Color scheme preferences
• Settings for silencing animations
• Animated (APNG) snapshot capture via animate (experimental, not supported on ios-safari/ipad-safari)

🤝 Contributing

Issues are welcome at happo/happo. The package is developed in Happo's own repository now, so the code in happo/happo is no longer updated, and pull requests there can't be merged as they are.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• happo.io
• npm package
• Release notes

💡 Support

For support and questions:

• Check the documentation
• Open an issue in this GitHub repository
• Contact happo.io support at [email protected]