TestGator

Repositories: testgator_client ( frontend) · testgator_server ( backend) · testgator-cli (agent-facing CLI)

TestGator helps teams organize software testing to fight back against bugs.

Built for non-technical testers — no setup, no jargon. Just clear testing plans, simple feedback, and results everyone can understand. Instead of asking testers to file bug reports through a dev tool, TestGator lets them sign in with nothing but their email: they enter it, get a one-time code, and land straight in their assigned testing plan. They work through it step by step, calling each one PASS / PASS (with bug) / FAILED with comments, screenshots, and files where it helps — while TestGator quietly captures browser, OS, screen resolution, and geolocation in the background, so devs get context instead of "it's broken, trust me."

Testing plans · Releases · Feedback · Open source

Why TestGator

• Reduce testing chaos — bring structure to testing so teams can focus on building great software instead of chasing testers for status updates.
• Make feedback simple — testers share clear, structured feedback with files and context, without learning a dev tool.
• Keep quality visible — progress stays transparent and collaboration effortless, for testers and developers alike.

Features

• Interactive testing plans — dev teams build structured, step-by-step test plans.
• Email OTP login for testers — testers sign in with their email and a one-time code, no password or account setup.
• Simple feedback — PASS / PASS (with bug) / FAILED, plus comments and file/screenshot uploads.
• Automatic environment capture — browser, OS, screen resolution, geolocation, no manual reporting.
• Projects & releases — plans are organized under releases, releases under projects.
• Role-based tester assignment — reuse testers across plans or assign fresh ones.
• Two auth modes for the product/dev team — local database accounts or LDAP, selectable per deployment (testers always use email OTP, separate from this).

Architecture

TestGator ships as two independently deployed applications:

Component	Path	Stack
Client	testgator_client	React 19 + Vite, served as a static build via Nginx
Server	testgator_server	Symfony 7.2 + API Platform 4 (PHP ≥8.4), running on FrankenPHP/Caddy

The server also expects a PostgreSQL database and, for file uploads, an S3-compatible bucket. Team/dev logins can run against the server's own internal user database (default) or against an LDAP server — LDAP is optional, not required. A Mercure hub is bundled into the FrankenPHP image for future realtime updates, but it's currently disabled (commented out in docker/frankenphp/Caddyfile) — nothing publishes or subscribes to it yet.

Built for AI agents too

TestGator's REST API is the same one an AI coding agent can drive directly — two pieces make that practical instead of asking an agent to speak raw JSON-LD:

• testgator-cli — an agent-facing command-line client. Same public API testgator_client already uses, no MCP server, no backend changes. It authenticates once, unwraps every response down to plain compact JSON, and exposes the project → release → plan → question → tester → answer hierarchy as one command per resource (plus composite commands like plan duplicate and test-invite). Run testgator-cli guide after installing it for a full, always-current orientation.
• agent/skills/app-testing-manager — a portable skill (in this repo) that teaches an agent how to use TestGator well: what to test and when, how to phrase questions a non-technical tester can actually answer, how to drive testgator-cli end to end, and what to do with the results — hand it back to the user as a summary, or use it to go fix the bug.

Together they let an agent set up a test plan, invite real testers, and read structured feedback back — the same loop a human dev team already gets from the web client, just callable from a shell.

Repository layout

• testgator_client — the tester/dev-facing web GUI.
• testgator_server — the REST API: projects, releases, plans, feedback, auth, file uploads.
• testgator-cli — agent-facing CLI client of the same REST API (separate repository).
• agent/skills — portable skills for AI agents working with TestGator (e.g. app-testing-manager).

Local development

Prerequisites: Docker, PostgreSQL (or use the bundled dev DB in the server's compose.yml).

# server
cd testgator_server
cp .env .env.local   # then edit secrets
make up               # docker compose up, dev image with hot reload

# client
cd testgator_client
npm install
npm run dev

See each package's own docs for details — this file focuses on shipping the published Docker images.

License

TestGator is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only) — see testgator_server/LICENSE / testgator_client/LICENSE.

In short: you're free to use, modify, and redistribute the code, including running it as a hosted service — but the AGPL's network clause applies. If you run a modified version and make it available to users over a network, you must offer those users the corresponding modified source code.

A couple of things the AGPL does not grant, per the project's NOTICE file:

• The TestGator name, logo, and branding aren't covered by the license — you can't present a fork or self-hosted instance as the official project without arkdevuk's permission.
• "Official" TestGator releases, hosted services, support, and docs come only from arkdevuk or parties they explicitly authorize.

If you fork or self-host, keep the LICENSE/NOTICE files intact and identify your instance as independent/unofficial.

---

Deploying TestGator

Pick a guide based on how you want to run it:

• docker-swarm/ — Docker Swarm cluster
• k8s/ — Kubernetes cluster
• docker-single-node/ — a single server with plain Docker

Each folder has its own step-by-step readme and a ready-to-edit example manifest.