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.jshappo.config.mjshappo.config.cjshappo.config.tshappo.config.mtshappo.config.cts
Key Configuration Properties
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
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
- 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.
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
💡 Support
For support and questions:
