A modern, self-hostable test management platform.

Organize test cases, run test plans, ingest CI automation results, and track quality across every project — all in one calm, fast workspace.

Quick Start · Features · Architecture · CI Automation · Contributing

---

✨ Why Checkmate?

Test management shouldn't feel like paperwork. Checkmate keeps the whole quality picture — manual cases, structured runs, CI automation, and exploratory sessions — in one place, with a UI that's quick to navigate and satisfying to use.

• 🧩 Everything in one workspace — cases, plans, runs, milestones, sessions, and automation, per project.
• 🤖 CI-native — pipe JUnit results from any CI in one command; flaky and slow tests surface automatically.
• 📈 Answers, not spreadsheets — pass-rate trends, coverage, and open-failure counts on every dashboard.
• 🔌 Plays well with your stack — Jira/issue-tracker links, Slack/Teams webhooks, and a REST API with Swagger docs.
• 🏠 Self-hostable — one docker compose up and you own your data.

🚀 Quick Start

Prerequisites: Docker (or OrbStack) with Compose.

git clone https://github.com/AlameerAshraf/Checkmate.git
cd Checkmate
docker compose up --build

Then seed a rich demo dataset (projects, cases, runs, automation, sessions):

docker compose exec api node dist/database/seed.js

Service	URL
🖥️ Web app	http://localhost:5173	React SPA
⚙️ API	http://localhost:3000	REST + Swagger at /docs
🍃 MongoDB	localhost:27018	data store

Demo login — admin@checkmate.dev / checkmate123

🧭 Features

Area	What you get
Test cases	Nested folders, step-by-step or text mode, priorities & types, revision history, CSV import
Test runs	Assign testers, record results (passed / failed / blocked / retest / skipped), close · reopen · clone
Test plans	Cross-browser / cross-OS configuration matrices generated into runs
Automation	JUnit ingestion from CI, flaky / slow / failing detection, a Kanban board & per-test history
Milestones	Group work toward a release with due dates and progress
Exploratory sessions	Charters, timeboxes, and notes (bug · idea · question) that convert into cases
Reports & dashboards	Pass-rate trends, automation coverage, open-failure counts
Integrations	Jira & generic issue trackers, HMAC-signed Slack / Teams webhooks
Access & auth	JWT auth, 2FA (TOTP), password reset, project roles (admin · lead · tester · viewer)
Extras	Per-instance branding, TestMo import, optional AI test-case generation, email digests

🏗️ Architecture

Three focused apps around a single API and database:

flowchart LR
    Dev([👩‍💻 Team]) -->|browser| Web
    CI([🔁 CI pipeline]) -->|JUnit XML via checkmate-cli| API

    subgraph Checkmate
        Web["🖥️ checkmate-web<br/>React · Vite · Tailwind"] -->|REST /api| API["⚙️ checkmate-api<br/>NestJS"]
        API --> DB[("🍃 MongoDB")]
    end

    API -->|webhooks| Chat([💬 Slack / Teams])
    API -->|issues| Jira([🐛 Jira / Trackers])

Loading

Package	Stack	Role
checkmate-api	NestJS 11 · MongoDB/Mongoose · JWT/Passport · Swagger · Pino	REST API, auth, business logic, automation ingestion
checkmate-web	React 18 · Vite · TypeScript · Tailwind · shadcn/Radix · TanStack Query · Zustand · Recharts	Single-page web client
checkmate-cli	Node.js (zero-dependency, ESM)	Submit CI test results from any pipeline

🤖 CI Automation

Push automated results from any CI in a single command with @checkmate/checkmate-cli:

npx @checkmate/checkmate-cli submit \
  --url    http://localhost:3000/api \
  --key    "$CHECKMATE_API_KEY" \
  --source e2e-playwright \
  --name   "CI #$BUILD_NUMBER" \
  --branch "$GIT_BRANCH" --commit "$GIT_SHA" \
  --report junit.xml

Create a project API key under Settings → API Keys, then wire the command into your pipeline. Checkmate parses the JUnit XML, tracks each test over time, and flags flaky and slow tests automatically.

📁 Project Structure

Checkmate/
├── checkmate-api/            # NestJS + MongoDB REST API
│   └── src/modules/          # auth, projects, cases, runs, automation, sessions, …
├── checkmate-web/            # React + Vite single-page app
│   └── src/features/         # per-feature UI (cases, runs, automation, reports, …)
├── checkmate-cli/            # zero-dependency CLI for CI result submission
├── docker-compose.yml        # base stack (mongo + api + web)
├── docker-compose.override.yml   # local dev host ports
├── docker-compose.prod.yml   # production (behind a gateway)
└── deploy.sh                 # one-shot deploy to a fresh host

🧑‍💻 Local Development

Run each app on its own for the fastest feedback loop:

# API  (http://localhost:3000, Swagger at /docs)
cd checkmate-api && cp .env.example .env && pnpm install && pnpm start:dev

# Web  (http://localhost:5173)
cd checkmate-web && pnpm install && pnpm dev

Key environment variables (see checkmate-api/.env.example)

Variable	Purpose
MONGODB_URI	MongoDB connection string
JWT_ACCESS_SECRET / JWT_REFRESH_SECRET	Token signing secrets
CORS_ORIGINS	Comma-separated allowed web origins
APP_URL	Public URL used in email links
SMTP_*	Optional SMTP (omit to log emails to console)
DEEPSEEK_API_KEY	Optional — enables AI test-case generation

🗺️ Roadmap

• Case ↔ automation coverage linking
• Native GitHub / GitLab CI recipes
• Public, shareable read-only reports
• Additional issue-tracker providers

🤝 Contributing

Contributions are welcome! Open an issue to discuss a change, or send a PR:

1. Fork and create a feature branch.
2. pnpm lint && pnpm typecheck && pnpm test in the package you touched.
3. Open a pull request describing the change.

📄 License

Released under the MIT License.

_{Built with ♟️ — testing that feels good.}