Note: Development of the happo package has moved to Happo's internal repository, and the code in this repository is no longer updated. The package is still published to npm as happo. Issues are still welcome here, but pull requests to this repository won't be merged.

Release notes for new versions are at happo.io/release-notes/happo. The releases in this repository end at v6.21.0.

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,
  },
});

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

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Clone the repository
2. Install dependencies: pnpm install
3. Build the project: pnpm build
4. Run all tests and checks: pnpm all

To run the tests you will need a .env.local file with some keys. Use .env.example as a starting point.

Code Style

• Uses ESLint for code linting
• Prettier for code formatting
• TypeScript for type safety

📄 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 support@happo.io