broxhq/qpilot
AI agent that runs your manual test cases in a real browser - broxhq/qpilot
6 stars · 1 forks · TypeScript
README
qpilot AI agent that runs your manual test cases in a real browser
If qpilot saved you time → ⭐ Star it on GitHub. It helps more than you'd think.
How it works
You paste a plain-text test case The agent opens Chrome and executes each step You watch results appear live — pass, fail, or warn per step If it hits a captcha or OTP, it pauses and asks you directly
No code. No Selenium. No config files.
Manual testing Selenium / Playwright scripts qpilot
Setup none write + maintain a test suite paste plain text
Survives UI changes n/a (a human adapts) breaks on selector/layout changes reads the page like a human, via ARIA semantics
Who can write a test anyone someone who codes anyone who can write a step-by-step description
OTP / captcha human handles it usually blocks the run pauses and asks you, then continues
Result you watched it yourself pass/fail, no narrative pass/fail/warn per step, with evidence
Quick start Requirements: Node.js 20.12+, Google Chrome, an Anthropic API key — or any OpenAI-compatible model endpoint (Qwen, vLLM, Ollama, corporate gateway) npx qpilot That's it. On first run qpilot walks you through a quick provider setup (arrow-key menu), then every launch shows your config and a Start menu. Browser opens automatically at http://localhost:3847.
Models & providers On first run qpilot asks which model to use. You can re-run setup anytime: npx qpilot config Two options:
Anthropic (Claude) — enter your sk-ant-… key. Default model is claude-haiku-4-5. Base URL is optional — set it if you reach Claude through a corporate proxy/gateway.
Custom — any OpenAI-compatible endpoint: Qwen, vLLM, Ollama, a corporate gateway, OpenRouter, or OpenAI itself. You provide a base URL, API token and model id, e.g.: Base URL: https://dashscope-intl.aliyuncs.com/compatible-mode/v1 Model id: qwen2.5-72b-instruct
Your choice is saved to ~/.qpilot/config.json (mode 600) and reused on every run.
The custom path speaks the OpenAI /chat/completions protocol with tool calling — so the model must support function/tool calling for the agent to drive the browser.
API key (Anthropic shortcut) For the Anthropic provider you can skip setup by supplying the key via env:
ANTHROPIC_API_KEY environment variable .env.local file in the current directory
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local The key is never stored except in ~/.qpilot/config.json when you run setup.
Options
Command Description
qpilot config Re-run provider setup (Anthropic or custom model)
npx qpilot config Browser visibility is a per-run choice in the UI, not a CLI flag: hit Run to stay headless, or Run with preview to watch Chrome click through the page.
Writing a test case TC-001 — Login and add item to cart URL: https://www.saucedemo.com/ Credentials: standard_user / secret_sauce
Steps: 1. Open the home page. Expected: login form with Username and Password fields is visible.
2. Enter credentials and click Login. Expected: Products page opens with 6 items.
3. Click "Add to cart" on "Sauce Labs Backpack". Expected: cart counter shows 1.
4. Click the cart icon. Expected: cart contains Sauce Labs Backpack at $29.99.
You can paste multiple test cases at once — the agent runs them in order.
Running a folder of test cases Click Choose folder to point qpilot at a directory of .md files (or Upload .md for a single file). Check the ones you want, then Run the batch — each file runs one after another with live status and timing, and you can Stop mid-batch. Finished runs (including past batches) show up under Recent runs on the home page.
Notes
API key is stored only in ~/.qpilot/config.json (file mode 600) — never sent anywhere except your chosen model provider Runs are in-memory and capped at the last 50 — restarting the server clears all of them Powered by Claude + Playwright