@syngrisi/syngrisi

Syngrisi

Open-source Visual Testing Platform — catch visual regressions before your users do.

An open-source visual regression testing platform to capture screenshots from your automated tests, compare them against approved baselines, and review every pixel change in a fast, self-hosted web UI.

Demo

https://github.com/user-attachments/assets/24a666f0-6dc5-439d-be9a-8d7b2e411655

Why Syngrisi?

Visual bugs — a broken layout, a clipped chart, a shifted button — slip straight through unit tests and code review. Dedicated visual testing clouds catch them, but they are expensive, send your screenshots to someone else's servers, and lock you in.

Syngrisi gives you the same workflow, open-source and self-hosted:

• Free & MIT-licensed — no per-screenshot pricing, no seat limits.
• Your data stays yours — runs entirely on your own infrastructure.
• Drop-in SDKs for Playwright, WebdriverIO and Cucumber, plus a REST API.
• Up in one command with Docker.

Features

• Pixel-perfect comparison — powered by a Resemble.js-based engine with nothing / antialiasing / colors match modes.
• Tolerance threshold — let checks pass within a configurable mismatch budget (per-baseline or per-check).
• Ignore regions & vertical-shift handling — mask dynamic areas and absorb scroll offsets.
• Cross-browser, OS & viewport — capture and group results by browser, platform, viewport and git branch.
• Review workflow — accept/reject baselines, mark checks as bugs, batch-accept, and share single checks via link.
• Powerful filtering & grouping — group by run, suite, browser, platform or status; build nested AND/OR filters.
• AI Triage (beta) — a vision-LLM classifies each failed check (intended change / likely bug / noise) with a confidence score; auto-accept policies, per-project prompts & verdicts, and a fully self-hosted local-model option via Ollama.
• AI Match (beta) — from one failed check, instantly find the same visual change on every other resolution and browser, ranked by a similarity score — review the whole cluster of "one bug, many viewports" in a single pass. 100% local, no model required.
• Root Cause Analysis (beta) — captures a DOM snapshot alongside each screenshot to help explain why a check changed.
• Auth, roles & SSO — username/password, API keys, plus OAuth2 / SAML 2.0 single sign-on and an admin panel.
• Plugin system & rich configuration — extend behaviour and tune everything through environment variables.
• Self-hosted & Docker-ready — Express + MongoDB backend, React + Mantine UI.

Screenshots

Side-by-side compare — drag the slider between baseline and actual.	Root Cause Analysis — the DOM-level changes behind a diff, ranked by severity.
Pinpoint diffs — exactly what changed, down to a single chart point.	Per-test checks — every check at a glance, with a customizable UI (dark theme, layouts, fields).

_{Difference highlighting — a 0.09% change across a handful of points becomes impossible to miss.}

NEW: AI Triage — let AI sort the red from the real (beta)

Stop drowning in red diffs. A wall of failed checks after a refactor is the worst part of visual testing. Syngrisi now puts a vision-LLM on triage duty: it looks at the baseline, the actual and the diff, and tells you what each change actually is.

• Every failed check gets a verdict — intended change, likely bug, noise or uncertain, with a confidence score and a one-line reason ("header overlaps content", "image failed to load", "dynamic timestamp updated").
• Auto-accept the boring stuff — let intended changes and rendering noise accept themselves above a confidence threshold; real bugs are always kept for a human.
• Triage at a glance — group and filter the grid by AI verdict, so "9 noise, 3 real regressions" replaces "47 red checks". Verdicts update live, no reload.
• 100% private — bring your own model — point it at a local model via Ollama (Qwen-VL, Gemma…) and your screenshots never leave your machine. Or use any OpenAI-compatible / Anthropic / Gemini endpoint.
• Yours to tune — per-project verdicts, fully editable prompt with {{placeholders}}, few-shot example images, and a manual queue (restart / cancel) grouped by run.

Enabled per project, off by default. See AI Triage docs.

Provider & per-project config — a known provider or a self-hosted model; custom verdicts and auto-accept threshold.	Filter by verdict — focus on likely bugs; hide intended changes and noise.
Group by AI verdict — triage a wall of red at a glance.	Analysis queue — grouped by run, with manual restart / cancel.

NEW: AI Match — one bug, every viewport, one click (beta)

A single layout regression rarely fails just once. Bump a header and it breaks on mobile, tablet, desktop and in every browser you capture — a dozen red checks for one root cause. AI Match collapses that noise: open any failed check, hit the AI Match icon, and Syngrisi pulls up every other check with the same visual change.

https://github.com/user-attachments/assets/3dca7b0f-5056-423d-bef7-81d2ac6f6125

• Same change, everywhere — finds the identical diff across other resolutions and other browsers in the run, not just look-alikes by name.
• Ranked by similarity — each match shows a ~NN% score so the closest siblings sort to the top; the main grid filters down to just the cluster, auto-expanded.
• Instant & 100% local — built on a lightweight colour-histogram change descriptor, no ML model and no network required. Matching is computed once per check in the background.
• Review the cluster, not the chaos — accept or reject the whole "one bug across N viewports" group in a single pass, using the same per-check controls you already know.
• Tunable per project — set the match threshold (stricter = fewer, surer matches) under Admin → AI → Projects settings.

Enabled per project, off by default.

Quick Start

Scaffold a new project (recommended)

npm init sy@latest

The interactive CLI sets up a ready-to-run project with Syngrisi and your chosen test framework. Prefer a template? The Playwright BDD boilerplate is the recommended starting point for the fastest start — Gherkin/BDD with ~150 ready-made steps, first-class Syngrisi visual checks, and AI-agent tooling out of the box. You can also start from the plain Playwright or Cucumber boilerplate ( open in Gitpod). Testing in another language? There are also Playwright + Python and Playwright + Java boilerplates.

Run the server with Docker

mkdir my-syngrisi && cd my-syngrisi
curl -LO https://raw.githubusercontent.com/syngrisi/syngrisi/main/packages/syngrisi/syngrisi-app.dockerfile
curl -LO https://raw.githubusercontent.com/syngrisi/syngrisi/main/packages/syngrisi/docker-compose.yml
docker compose up

Then open http://localhost:3000. See the main app README for native (non-Docker) setup.

Use it in your tests

Playwright (via @syngrisi/playwright-sdk):

import { test } from '@playwright/test';
import { PlaywrightDriver } from '@syngrisi/playwright-sdk';

test('homepage looks right', async ({ page }) => {
  const driver = new PlaywrightDriver({
    page,
    url: 'http://localhost:3000/',
    apiKey: process.env.SYNGRISI_API_KEY,
  });

  await driver.startTestSession({ params: { app: 'My App', test: 'Homepage', branch: 'main' } });
  await page.goto('https://example.com');
  await driver.check({ checkName: 'Homepage', imageBuffer: await page.screenshot() });
  await driver.stopTestSession();
});

Also available: @syngrisi/wdio-sdk for WebdriverIO, wdio-syngrisi-cucumber-service for Cucumber, and the framework-agnostic @syngrisi/core-api REST client.

How it compares

Syngrisi trades a managed cloud and a large hosted feature set for being free, open-source and fully under your control. If you want to own your visual testing stack, it's built for you.

Monorepo

packages/
├── syngrisi/                              # Main application (Express + React)
├── core-api/                              # Framework-agnostic REST client
├── playwright-sdk/                        # Playwright SDK
├── wdio-sdk/                              # WebdriverIO SDK
├── wdio-syngrisi-cucumber-service/        # WebdriverIO + Cucumber service
├── wdio-cucumber-viewport-logger-service/ # In-viewport step logger
├── node-resemble.js/                      # Image comparison library
└── create-sy/                             # `npm init sy` project scaffolder

• Just running tests? Install the SDK for your framework (@syngrisi/playwright-sdk or @syngrisi/wdio-sdk).
• Hosting the server? Use the @syngrisi/syngrisi app (Docker or native).
• Starting from scratch? Run npm init sy@latest.

Documentation

• Main App Guide
• AI Features · Root Cause Analysis
• Plugins
• Environment Variables
• Development Guide · Release Cycle
• API reference: Swagger UI at /swagger/ on a running instance.

yarn install:all   # install server + UI dependencies
yarn build         # build all packages
yarn start         # start the main application
yarn test          # run the E2E suite (from packages/syngrisi)

Contributing

Contributions are welcome! Please open an issue to discuss substantial changes first. See AGENTS.md and the Release Cycle for repo conventions, then send a PR.

License

MIT Syngrisi contributors