Healix

End-to-end AI test generation and QA automation, from your IDE.

Healix is a monorepo containing two packages:

• testbot-mcp/ — @healix/mcp (v2.0.0), an MCP server installed in developer IDEs. It orchestrates the full testing pipeline: auto-detect → explore → generate → execute → analyze → dashboard.
• webapp/ — A Next.js 16 / React 19 webapp deployed on Vercel. Hosts all AI calls (OpenAI server-side), the Supabase-backed dashboard, artifact storage, and the Inngest async generation pipeline.

Users only need a HEALIX_API_KEY. All AI calls are proxied server-side through the webapp — no OpenAI key needed on user machines.

Quick Start

1. Install the MCP server

npm install -g @healix/mcp

2. Configure your IDE

Add to your MCP settings (~/.cursor/mcp.json, Claude Code, or Windsurf):

{
  "mcpServers": {
    "healix": {
      "command": "npx",
      "args": ["@healix/mcp"],
      "env": {
        "HEALIX_API_KEY": "your-healix-api-key"
      }
    }
  }
}

Get your API key from the Healix dashboard → API Keys.

3. Run a test

In your IDE prompt:

"Test my app using the healix mcp"

The pipeline runs automatically:

1. Config UI — local HTTP form collects test type, base URL, start command, PRD file (optional), and role credentials
2. Auto-detect — port, framework, and start command inferred from the project when not supplied
3. Browser exploration — browser-use (Python subprocess) discovers real flows; falls back to a zero-dependency Playwright heuristic explorer if browser-use is unavailable
4. PRD/AC parse — structured acceptance-criteria extraction via /api/parse-prd; AC-less apps use exploration flows directly
5. Test generation — GPT-powered multi-agent fan-out via /api/generate-tests; each test tagged [REQ:F#.S#.AC#]
6. Credential injection — per-role Playwright storageState written to .healix/auth-state-{role}.json
7. Tiered execution — three Playwright projects run in sequence:
   • Tier A (tierA-public) — unauthenticated / public flows
   • Tier B (tierB-auth-{role}) — one project per role; marked blocked if login fails (A + C still run)
   • Tier C (tierC-backend) — API/backend contract tests
8. Artifact upload — screenshots, videos, and Playwright traces uploaded to Supabase Storage
9. Ingest — results POSTed to /api/test-runs/ingest
10. Dashboard deep-link — opens the run page with tier pills, failure analysis, and artifacts

MCP Tools

Tool	Description
healix_test_my_app	Full end-to-end pipeline. Accepts projectPath, baseURL, port, startCommand, testType (frontend/backend/both), prdFile, generateTests, openDashboard, credentials, codebaseContext, playwrightMcp, and more.
healix_configure	Opens the config UI and returns validated settings without running the pipeline. Useful for pre-flight checks.

Configuration

MCP environment variables

Set these in the env block of your MCP client config (Cursor, Claude Code, Windsurf):

Variable	Required	Description	Default
HEALIX_API_KEY	Yes	Authenticates MCP → webapp; meters token usage.	—
HEALIX_DASHBOARD_URL	No	Webapp base URL. Used for all API calls and dashboard deep-links.	Production Vercel URL
HEALIX_RUN_BUDGET_MS	No	Overall pipeline timeout (ms).	7200000 (120 min)
HEALIX_GEN_BUDGET_MS	No	Test-generation stage timeout (ms). Raise for large codebases; otherwise Healix expands it for large/xlarge discovered apps.	1800000 (30 min)
HEALIX_GENERATION_AGENT_CONCURRENCY	No	Number of generation agents to run at once. Lower for fragile local webapps, raise for stable production webapps.	3
HEALIX_GENERATION_AGENT_TIMEOUT_MS	No	Explicit per-agent generation transport timeout. By default Healix derives this from the remaining generation budget and codebase complexity.	derived
HEALIX_SKIP_PLANNER	No	Set 1 to bypass the pre-fan-out planner pass (emergency circuit breaker).	unset

Webapp environment variables

Copy .env.example to webapp/.env.local:

Variable	Description
DATABASE_URL	PostgreSQL connection string (Supabase pooler URI for production).
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL.
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key (public).
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key (server-side only — never expose).
OPENAI_API_KEY	OpenAI API key. Used only by webapp API routes — never by the MCP.
OPENAI_MODEL	Model override (default: gpt-5.5-mini).
HEALIX_GEN_ASYNC	true routes /api/generate-tests through Inngest background jobs. Default: false.
INNGEST_EVENT_KEY	Inngest event key (required only when HEALIX_GEN_ASYNC=true).
INNGEST_SIGNING_KEY	Inngest webhook signing key (required only when HEALIX_GEN_ASYNC=true).
INNGEST_DEV	Set 1 when running against the local inngest-cli.
HEALIX_PLANNER_AGENT	1 to enable LLM-driven planner. Default: 0 (rule-based).
AI_MAX_REQUESTS_PER_MINUTE	Per-user AI rate-limit ceiling. Default: 20.

See .env.example for the full annotated reference.

Async generation (Inngest)

The default sync generation path runs the full multi-agent fan-out inside the /api/generate-tests request. For very large codebases where a single agent call risks hitting Vercel's function timeout:

1. Set HEALIX_GEN_ASYNC=true on the webapp and configure INNGEST_EVENT_KEY + INNGEST_SIGNING_KEY.
2. No MCP change needed — @healix/mcp auto-detects the 202 response and polls /api/generate-tests/jobs/{jobId}.

Do not enable HEALIX_GEN_ASYNC=true for local dev. There is no function-timeout constraint on localhost; the async path adds Inngest setup and polling overhead for no benefit.

Development

# Start the webapp (Next.js dev server on port 3000)
npm run dev:webapp

# Start the MCP server (stdio transport)
npm run start:testbot

# Run MCP unit tests (26 test files via node --test)
npm run test:testbot

# Database — run from webapp/
npm run db:generate   # generate Drizzle migration from schema changes
npm run db:migrate    # apply pending migrations
npm run db:studio     # open Drizzle Studio

Architecture

User IDE (Cursor / Claude Code / Windsurf)
         │  stdio (MCP protocol)
         ▼
 @healix/mcp  ─── thin client, HEALIX_API_KEY only ───────────────┐
         │                                                         │
         │  Pipeline (pipeline-worker.js):                         │
         │  1. Config UI (local HTTP server)                       │
         │  2. Auto-detect port/framework/start-cmd                │
         │  3. Browser-use exploration (Python) or PW heuristic    │
         │  4. Parse PRD/AC  ───── HTTPS ──────────────────────────┤
         │  5. Generate tests ──── HTTPS ──────────────────────────┤
         │  6. Inject credentials (storageState per role)          │
         │  7. Run Playwright: Tier A / Tier B / Tier C            │
         │  8. Upload artifacts ─── HTTPS ─────────────────────────┤
         │  9. Ingest results ──── HTTPS ──────────────────────────┤
         │ 10. Open dashboard deep-link                            │
         │                                                         ▼
         └──────────────────── Healix webapp (Vercel / localhost) ──
                               │  Next.js 16 + React 19
                               │  Supabase (Auth + DB + Storage)
                               │  Drizzle ORM (PostgreSQL)
                               │  Inngest (async generation jobs)
                               └──────── OpenAI (server-side only)

Project Structure

TestBot_MCP/
├── testbot-mcp/                  # @healix/mcp — npm package (v2.0.0)
│   ├── bin/healix-mcp.js         # CLI entry point
│   ├── src/
│   │   ├── index.js              # MCP server + tool registration
│   │   ├── pipeline-worker.js    # End-to-end pipeline orchestration
│   │   ├── auto-detector.js      # Port/framework/start-cmd detection
│   │   ├── webapp-client.js      # All webapp API calls (HEALIX_API_KEY)
│   │   ├── config-ui-launcher.js # Local HTTP config form
│   │   ├── browser-use-driver.js # Python browser-use subprocess
│   │   ├── playwright-explorer.js # Zero-dep Playwright heuristic fallback
│   │   ├── playwright-integration.js # Tier A/B/C Playwright projects
│   │   ├── playwright-mcp-client.js  # @playwright/mcp integration
│   │   ├── credentials-injector.js   # Per-role storageState injection
│   │   ├── artifact-uploader.js  # Supabase Storage upload
│   │   ├── results-merger.js     # Merge tier results + blocked status
│   │   ├── report-generator.js   # Build ingest payload
│   │   ├── mcp-telemetry.js      # Background telemetry reporting
│   │   ├── multi-service-starter.js  # App-under-test launcher
│   │   ├── context-gatherer.js   # Codebase context extraction
│   │   ├── dashboard-launcher.js # Open dashboard deep-link
│   │   ├── logger.js
│   │   ├── ai-providers/
│   │   │   └── saas-client.js    # Proxy → Healix webapp
│   │   └── failure-triage/
│   │       ├── classifier.js           # Deterministic first-match rules
│   │       ├── agent-response.js       # AI failure analysis parsing
│   │       ├── error-remediations.js   # Patch suggestions
│   │       ├── evidence-bundler.js     # Test source + AC + trace evidence
│   │       ├── pipeline-error-classifier.js
│   │       └── trace-parser.js         # Playwright trace.zip parser
│   ├── scripts/
│   │   ├── browser_use_runner.py # Pinned browser-use driver
│   │   └── localhost-smoke.js    # Local smoke test helper
│   └── test/                     # 26 test files (node --test)
│
└── webapp/                       # Next.js 16 webapp (Vercel)
    ├── src/
    │   ├── app/
    │   │   ├── (auth)/           # Sign in / sign up / callback pages
    │   │   ├── (dashboard)/      # Authenticated dashboard pages
    │   │   │   ├── home/         # Overview + recent runs
    │   │   │   ├── create-tests/ # Manual test run creation
    │   │   │   ├── all-tests/    # Test run history
    │   │   │   ├── mcp-tests/    # MCP-originated runs
    │   │   │   ├── test-run/[id] # Live + historical run detail
    │   │   │   ├── import-tests/ # Groovy test import from Excel/CSV
    │   │   │   ├── monitoring/   # Live MCP telemetry + run monitoring
    │   │   │   ├── api-keys/     # API key management
    │   │   │   ├── plan-billing/ # Plan + credits
    │   │   │   └── profile/
    │   │   └── api/
    │   │       ├── generate-tests/    # Multi-agent AC-traced generation
    │   │       ├── parse-prd/         # PRD → structured AC extraction
    │   │       ├── exploration/plan/  # Flow prioritization
    │   │       ├── analyze-failures/  # AI failure triage
    │   │       ├── test-runs/         # CRUD + ingest + phase + SSE stream
    │   │       ├── import-tests/      # Excel/CSV → Groovy generation
    │   │       ├── mcp-telemetry/     # Telemetry ingest + summary
    │   │       ├── mcp-auth/validate/ # API key validation
    │   │       ├── artifacts/         # Supabase Storage proxy
    │   │       ├── upload-artifacts/  # Signed upload URLs
    │   │       ├── api-keys/          # Key CRUD
    │   │       ├── auth/              # Supabase Auth helpers
    │   │       ├── inngest/           # Inngest function registry
    │   │       └── profile/
    │   └── lib/
    │       ├── db/schema.ts           # Drizzle ORM schema (source of truth)
    │       ├── test-generation/       # GPT orchestration: planner + agents
    │       ├── inngest/functions/     # generate-tests-orchestrator + agent
    │       ├── types/database.ts      # Shared TypeScript interfaces
    │       ├── ai-guard.ts            # Per-user AI rate limiting
    │       ├── credits.ts             # Token accounting
    │       ├── mcp-live-runs.ts       # SSE live run state from telemetry
    │       ├── groovy-generator.ts    # Groovy test file generation
    │       └── excel-parser.ts        # Excel/CSV test case ingestion
    └── drizzle/                  # SQL migrations

Database Schema (key tables)

Table	Purpose
profiles	User accounts (plan, credits, tokens)
api_keys	Hashed API keys per user
test_runs	Execution results with tier results, pipeline errors, AI analysis
test_failures	Per-test failure verdicts with evidence and user overrides
mcp_telemetry_events	Pipeline event stream (powers live run monitoring)
generation_jobs	Inngest async generation job lifecycle
generation_plans	24h cached planner output per repo snapshot
test_artifacts	Screenshot / video / trace metadata + Supabase Storage paths
import_sessions	Groovy import sessions (Excel/CSV → test cases)
imported_test_cases	Parsed test cases from import
generated_groovy_files	Generated Groovy API test files

Migrating from @testbot/mcp

See MIGRATION.md for the full upgrade guide. Summary:

npm uninstall -g @testbot/mcp
npm install -g @healix/mcp

Remove OPENAI_API_KEY, AI_PROVIDER, and any other AI keys from your MCP config — they are ignored in v2.0.0. Only HEALIX_API_KEY is required.

License

MIT