Healix

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

1. Artifact upload — screenshots, videos, and Playwright traces uploaded to Supabase Storage
2. Ingest — results POSTed to /api/test-runs/ingest
3. 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