@botbuddy/react

Draggable, translucent test coordination widgets for React. Drop into any app for human-in-the-loop QA powered by BotBuddy.

Install

npm install @botbuddy/react

Quick Start

import { TestRunWidget } from "@botbuddy/react";

function App() {
  return (
    <>
      {/* Your app */}
      <TestRunWidget
        config={{
          serverUrl: "https://your-project.supabase.co/functions/v1/mcp-server",
          anonKey: "your-supabase-anon-key",
        }}
        appSlug="my-app"
        environment="staging"
        targetUrl={window.location.origin}
        onNavigate={(path) => (window.location.href = path)}
      />
    </>
  );
}

Widget Modes

| Mode | Shows | |------|-------| | Mini | Pill with pass/total count + clickable PR & ticket links | | Expanded | Title, environment badge, stats, description, links | | Max | Full test case list with verdict buttons + fail reason input |

Click the pill to cycle through modes. Drag to reposition anywhere on screen.

Props

| Prop | Type | Description | |------|------|-------------| | config | BotBuddyConfig | Server URL and anon key (required) | | appSlug | string | App identifier (required) | | environment | string | local, preview, staging, production, custom (required) | | testRunId | string | Direct test run ID lookup | | targetUrl | string | Match by deployed URL (e.g. window.location.origin) | | version | string | Match by version | | commitSha | string | Match by commit SHA | | branchName | string | Match by branch name | | onNavigate | (path: string) => void | Called when user clicks a test case URL | | displayName | string | Attribution name for verdicts (default: "human") | | defaultMode | WidgetMode | Initial mode: "mini", "expanded", or "max" | | defaultPosition | { x: number; y: number } | Initial pixel position |

Resolution Priority

The widget finds the active test run by checking (in order):

1. testRunId — exact match
2. targetUrl — matches target_url on the run
3. appSlug + environment + version
4. commitSha
5. branchName

Hooks

Use the hooks directly for custom UIs:

import { useTestRun, useDraggable } from "@botbuddy/react";

const { run, widgetState, setVerdict, markComplete } = useTestRun({
  config: { serverUrl: "...", anonKey: "..." },
  appSlug: "my-app",
  environment: "staging",
});

const { pos, onPointerDown, onPointerMove, onPointerUp } = useDraggable(16, 600);

Zero Dependencies

The widget uses inline styles and inline SVG icons — no Tailwind, no icon library, no CSS imports needed. Just React.

License

MIT