https://github.com/kkiwior/kouma
Pixel-based screenshot comparison solution for visual regression testing.
https://github.com/kkiwior/kouma
comparison-tool regression-testing visual-testing
Last synced: 15 days ago
JSON representation
Pixel-based screenshot comparison solution for visual regression testing.
- Host: GitHub
- URL: https://github.com/kkiwior/kouma
- Owner: kkiwior
- License: mit
- Created: 2026-03-15T21:40:26.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-03-28T13:34:48.000Z (20 days ago)
- Last Synced: 2026-03-28T13:58:17.101Z (20 days ago)
- Topics: comparison-tool, regression-testing, visual-testing
- Language: TypeScript
- Homepage: https://kkiwior.github.io/kouma/
- Size: 1.97 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
- License: LICENSE
Awesome Lists containing this project
README
# Kouma
Kouma is a **pixel-based screenshot comparison solution** for visual regression testing. It helps you catch unintended visual changes in your application by comparing screenshots against a known baseline.
## What Kouma Offers
- **Pixel-Based Comparison:** Precise visual regression detection comparing screenshots pixel-by-pixel with configurable color thresholds and antialiasing support.
- **Web Dashboard:** Inspect test results, review visual mismatches, and maintain baseline builds through an intuitive interface.
- **Go Engine:** High-performance comparison engine written in Go with concurrent goroutine processing for fast results.
- **CLI & Client Library:** Zero-dependency TypeScript client with CLI, programmatic API, and built-in Cypress and Playwright integration to upload screenshots and trigger comparisons.
- **Docker Ready:** Quick local setup with Docker Compose and production-ready Kubernetes deployment via Helm charts.
- **Flexible Authentication:** Supports passcode, Microsoft OAuth, and Google OAuth with optional domain restriction.
## How It Works
1. **Take screenshots** in your tests using any framework (Cypress, Playwright, Selenium, etc.).
2. **Upload screenshots** to Kouma using the CLI, client library, or Cypress/Playwright plugin.
3. **Kouma compares** each screenshot against the baseline pixel-by-pixel.
4. **Review results** in the web dashboard — approve changes or flag regressions.
5. **Maintain baselines** by rebasing builds when visual changes are intentional.
## Architecture Overview
Kouma consists of four main services running as Docker containers and communicating through an internal network:
| Service | Technology | Purpose |
| ------------- | ----------- | ------------------------------ |
| **Dashboard** | Bun + Vue 3 | Web UI and REST API |
| **Engine** | Go | Screenshot comparison |
| **MongoDB** | MongoDB | Data storage |
## Quick Start
### Docker Compose
```bash
git clone https://github.com/kkiwior/kouma.git
cd kouma
docker-compose up
```
Open [http://localhost:3001](http://localhost:3001) in your browser.
### Kubernetes with Helm
```bash
helm install kouma oci://ghcr.io/kkiwior/charts/kouma
```
## Packages
| Package | Address |
| --- | --- |
| Dashboard image | `ghcr.io/kkiwior/kouma/dashboard` |
| Engine image | `ghcr.io/kkiwior/kouma/engine` |
| Helm chart | `oci://ghcr.io/kkiwior/charts/kouma` |
| npm client | [`kouma-client`](https://www.npmjs.com/package/kouma-client) |
## Screenshots
## Documentation
For more information, installation instructions, and guides, please refer to the documentation in the `docs/` directory or [docs page](https://kkiwior.github.io/kouma/).
## Credits
This project is a fork of [Micoo](https://github.com/Mikuu/Micoo).