Note: Development of the
happopackage has moved to Happo's internal repository, and the code in this repository is no longer updated. The package is still published to npm ashappo. 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.
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.
For comprehensive documentation, visit docs.happo.io.
- 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
npm install happo --save-dev
# or
pnpm add happo --save-dev
# or
yarn add happo --devCreate 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',
},
},
});Run Happo using the CLI:
npx happoThe CLI will automatically find your configuration file and run the visual regression test suite.
The library automatically detects configuration files in the following order:
happo.config.jshappo.config.mjshappo.config.cjshappo.config.tshappo.config.mtshappo.config.cts
apiKey&apiSecret: Authentication credentials for happo.iointegration: Set up the integration typetargets: Target configurations, including regular browsers and accessibility targetsproject: Optional project namedeepCompare: Optional settings for how diffs are computedblockApproval: Optional conditions that block a comparison from being approved
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.
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 onios-safari/ipad-safari)
Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.
- Clone the repository
- Install dependencies:
pnpm install - Build the project:
pnpm build - 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.
- Uses ESLint for code linting
- Prettier for code formatting
- TypeScript for type safety
This project is licensed under the MIT License - see the LICENSE file for details.
For support and questions:
- Check the documentation
- Open an issue in this GitHub repository
- Contact happo.io support at support@happo.io