{"id":31934360,"url":"https://github.com/testomatio/explorbot","last_synced_at":"2026-04-08T04:00:17.263Z","repository":{"id":310421467,"uuid":"1022534530","full_name":"testomatio/explorbot","owner":"testomatio","description":"AI Agent for Explorotary Browser Testing","archived":false,"fork":false,"pushed_at":"2026-04-06T01:03:15.000Z","size":5400,"stargazers_count":11,"open_issues_count":4,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T02:31:22.928Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testomatio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-07-19T09:28:10.000Z","updated_at":"2026-04-06T01:03:18.000Z","dependencies_parsed_at":"2025-08-18T02:35:43.553Z","dependency_job_id":"94ce5199-a092-4579-a0b8-47920b5b0fe0","html_url":"https://github.com/testomatio/explorbot","commit_stats":null,"previous_names":["testomatio/explorbot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/testomatio/explorbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fexplorbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fexplorbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fexplorbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fexplorbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testomatio","download_url":"https://codeload.github.com/testomatio/explorbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testomatio%2Fexplorbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31539229,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-14T06:25:49.321Z","updated_at":"2026-04-08T04:00:17.243Z","avatar_url":"https://github.com/testomatio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Explorbot\n\n**The vibe-testing agent for web applications.**\n\n![Explorbot Terminal UI](https://github.com/testomatio/explorbot/blob/main/assets/screenshot.png)\n\nExplorbot explores your web app like a curious human would — clicking around, filling forms, finding bugs, and learning as it goes. No test scripts required. Just point it at your app and let it work.\n\n```bash\nnpx explorbot start https://your-app.com\n```\n\nExplorbot is your first assitant in testing.\nIt will do its best to use your application with no babysitting. It will use application and provide you valuable feedback.\n\n## Use Cases\n\n* Autonomously test web application or its parts\n* Discover test scenarios and get automated tests for them\n* Write manual test cases from exploring website\n* 24h/7d of monkey-testing for web application that can reveal hidden errors\n* Quick-test for MVPs and prototypes\n\nExplorbot can start testing features which were not covered by unit tests or browser tests.\n\n## Demo\n\n![Explorbot in action](https://github.com/testomatio/explorbot/blob/main/assets/demo.gif)\n\n## Requirements\n\n- NodeJS 24+ or **Bun**\n- **AI provider API key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, or others via [Vercel AI SDK](https://sdk.vercel.ai/providers)\n- **Modern terminal** — iTerm2, WARP, Kitty, Ghostty. WSL if running on Windows\n- **Compatible web app** — Check [docs/prerequisites.md](docs/prerequisites.md) to verify your app works with Explorbot\n\n## Quick Start\n\n**1. Install dependencies**\n\n```bash\nnpm i explorbot --save\nnpx playwright install\n```\n\n**2. Initialize config**\n\n```bash\nnpx explorbot init\n```\n\n**3. Edit `explorbot.config.js`** — set your app URL and AI provider:\n\n\u003e [!IMPORTANT]\n\u003e **Explorbot uses three types of models:**\n\u003e\n\u003e | Type | Config key | Purpose | Recommendation |\n\u003e |------|-----------|---------|----------------|\n\u003e | **model** | `ai.model` | Standard model for HTML/ARIA processing. Used by Tester, Navigator, Researcher. Should be fast and cheap — these agents are token-hungry. | e.g. `openai/gpt-oss-20b` |\n\u003e | **visionModel** | `ai.visionModel` | Screenshot analysis. Used when agents need to visually inspect the page. | e.g. `meta-llama/llama-4-scout-17b-16e-instruct` |\n\u003e | **agenticModel** | `ai.agenticModel` | Exceptional decision making. Used by Captain and Pilot — agents that read compact action logs and make high-level decisions. Benefits from a smarter model. | Strong agentic models but fast (MiniMax 2.5, Grok Fast, Qwen, …) |\n\u003e\n\u003e See [OpenRouter](https://openrouter.ai/rankings#performance) for latency-focused model picks.\n\nThis example uses **OpenRouter** (one API key, many providers). Any Vercel AI SDK provider works; see [docs/providers.md](docs/providers.md).\n\n```javascript\nimport { createOpenRouter } from '@openrouter/ai-sdk-provider';\n\nconst openrouter = createOpenRouter({\n  apiKey: process.env.OPENROUTER_API_KEY,\n});\n\nexport default {\n  web: {\n    url: 'https://your-app.com',\n  },\n  ai: {\n    model: openrouter('openai/gpt-oss-20b'),\n    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),\n    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),\n  },\n};\n```\n\n\u003e [!TIP]\n\u003e Captain and Pilot barely use tokens (just action summaries), so a smarter `agenticModel` costs very little while significantly improving test quality. You can also override any agent's model individually via `ai.agents.\u003cname\u003e.model`.\n\n**4. Add knowledge** (optional but recommended)\n\nIf your app requires authentication, tell Explorbot how to log in:\n\n```bash\n# Interactive mode\nnpx explorbot learn\n\n# Or via CLI\nnpx explorbot learn \"/login\" \"Use credentials: admin@example.com / secret123\"\n```\n\n\u003e [!TIP]\n\u003e Use `--session` to persist browser cookies and localStorage between runs. Log in once, and Explorbot will restore the session on next start:\n\u003e ```bash\n\u003e npx explorbot start /login --session          # saves to output/session.json\n\u003e npx explorbot start /dashboard --session      # restores session, skips login\n\u003e npx explorbot start /app --session auth.json  # custom session file\n\u003e ```\n\n\u003e [!NOTE]\n\u003e Use `*` as URL pattern to add general knowledge that applies to all pages. See [docs/knowledge.md](docs/knowledge.md) for more.\n\n**5. Run**\n\n```bash\nnpx explorbot start /admin/users\n```\n\nStart from a small functional area of your app (admin panel, settings, any CRUD section) so Explorbot can quickly understand its business purpose and context.\n\nBrowser runs headless by default — use `--show` to see it:\n\n```bash\nnpx explorbot start /settings --show\n```\n\nRequires a modern terminal (iTerm2, WARP, Kitty, Ghostty, Windows Terminal). On Windows, use WSL.\n\n## How It Works\n\nExplorbot explores websites, analyzes their UI, and proposes tests — which it can then execute. It controls its own browser through CodeceptJS → Playwright (no MCP involved).\n\n![Explorbot Architecture](assets/architecture.png)\n\nRun `/explore` in TUI or use `explorbot explore` from CLI to watch the cycle: research → plan → test → repeat.\n\n**Supporting components:**\n\n* **Pilot** — supervises Tester from a separate conversation: reviews action logs, detects stuck patterns, makes final pass/fail decisions. Uses `agenticModel` since it only processes compact summaries, not raw HTML\n* **Historian** — saves sessions as CodeceptJS code, learns from experience\n* **Quartermaster** — analyzes pages for A11y issues (axe-core + semantic)\n* **Reporter** — sends test results to Testomat.io\n\n## Basic Usage\n\nOnce in the terminal UI:\n\n```\n/explore              # Full cycle: research → plan → test\n/research             # Analyze current page\n/plan                 # Generate test scenarios\n/test                 # Run next test\n/navigate /settings   # Go to a page\n```\n\nYou can also run CodeceptJS commands directly:\n\n```\nI.click('Login')\nI.fillField('email', 'test@example.com')\nI.see('Welcome')\n```\n\nSee [docs/commands.md](docs/commands.md) for all commands.\n\n\u003e [!NOTE]\n\u003e Most TUI commands also have CLI equivalents that run headless and exit. For example, `explorbot research \u003curl\u003e` and `explorbot plan \u003cpath\u003e` work without launching TUI. See [docs/commands.md](docs/commands.md) for the full mapping.\n\n## What You Get\n\n| Output | Location | Description |\n|--------|----------|-------------|\n| Test files | `output/tests/*.js` | CodeceptJS tests you can run independently |\n| Test plans | `output/plans/*.md` | Markdown documentation of scenarios |\n| Experience | `./experience/` | What Explorbot learned about your app |\n\n## Two Ways to Run\n\n**Interactive mode** — Launch TUI, guide exploration, get real-time feedback:\n\n```bash\nnpx explorbot start https://your-app.com\n```\n\n**Autonomous mode** — Non-interactive testing and planning:\n\n```bash\nnpx explorbot explore /admin/users\n```\n\n**Freesail mode** — Fully autonomous, continuous exploration across multiple pages:\n\n```bash\nnpx explorbot freesail /admin              # explore and test pages indefinitely\nnpx explorbot freesail /app --deep         # depth-first: explore nearby pages first\nnpx explorbot freesail /app --shallow      # breadth-first: spread across many pages\nnpx explorbot freesail /app --scope /admin # restrict to URLs under /admin\n```\n\nFreesail navigates to a page, researches it, runs tests, then moves on to the next least-visited page — repeating until stopped. Also available as `/freesail` in TUI.\n\n## API Testing\n\nExplorbot also tests REST APIs. Add an `api` section to your config and point it at your API:\n\n```javascript\nexport default {\n  web: {\n    url: 'http://localhost:3000',\n  },\n  ai: {\n    model: openrouter('openai/gpt-oss-20b'),\n    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),\n  },\n  api: {\n    baseEndpoint: 'http://localhost:3000/api/v1',\n    spec: ['http://localhost:3000/api/openapi.json'],\n    headers: {\n      'Authorization': 'Bearer \u003ctoken\u003e',\n    },\n  },\n};\n```\n\n```bash\nnpx explorbot api explore /users          # full cycle: plan + test all styles\nnpx explorbot api plan /users             # generate test plan only\nnpx explorbot api test plans/users.md *   # run all tests from a plan\n```\n\nThe API tester uses two agents — **Chief** (plans test scenarios across styles: normal, curious, psycho, hacker) and **Curler** (executes HTTP requests and verifies responses). Both use `agenticModel` by default.\n\nSee [docs/api-testing.md](docs/api-testing.md) for setup, authentication hooks, and full command reference.\n\n## Core Philosophy\n\n**Strategic decisions are deterministic** — The workflow (research → plan → test) is predictable and consistent.\n\n**Tactical decisions are AI-driven** — How to click that button, what to do when a modal appears, how to recover from errors.\n\n**Cheap workers, smart managers** — Tester, Navigator, and Researcher are token-hungry agents that chew through HTML and ARIA on every step. They run on the fast, cheap `model`. Captain and Pilot are the decision-makers — they read only compact action logs and make high-level choices. Set `agenticModel` to a smarter model for better results at negligible extra cost.\n\n**Explorbot learns from its failures** — It uses previous experience interacting with a web page for faster and better decisions on next runs.\n\n**Explorbot needs your knowledge** — You adjust Explorbot prompts by passing suggestions, UI explanations, and domain knowledge as text files, which are loaded when the corresponding page is opened.\n\nWhen tuned, Explorbot **can run autonomously for hours** navigating a web application and trying different scenarios. You don't need to watch it. The more Explorbot runs, the more it learns and the more complex scenarios it can test.\n\n\n## Teaching Explorbot\n\n* **Knowledge** (`./knowledge/`) — Tell Explorbot about your app: credentials, form rules, navigation quirks. See [docs/knowledge.md](docs/knowledge.md).\n* **Rules** (`./rules/`) — Customize agent behavior with markdown files. Add page-specific instructions, override planning styles, or tune how agents work on different parts of your app. See [docs/configuration.md](docs/configuration.md#rules).\n* **Experience** (`./experience/`) — Explorbot learns automatically from successful interactions and saves what works.\n\n## Further Reading\n\n- [docs/prerequisites.md](docs/prerequisites.md) — Application compatibility checklist\n- [docs/commands.md](docs/commands.md) — Terminal command reference\n- [docs/api-testing.md](docs/api-testing.md) — API testing setup and commands\n- [docs/knowledge.md](docs/knowledge.md) — Knowledge system and URL patterns\n- [docs/providers.md](docs/providers.md) — AI provider configuration\n- [docs/agents.md](docs/agents.md) — Agent descriptions and capabilities\n- [docs/planner.md](docs/planner.md) — Planner agent: planning styles and customization\n- [docs/scripting.md](docs/scripting.md) — Building custom autonomous scripts\n- [docs/observability.md](docs/observability.md) — Langfuse tracing and debugging\n- [docs/page-interaction.md](docs/page-interaction.md) — How agents interact with pages\n\n## FAQ\n\n**Can I run it in Cursor? or Claude Code?**\nNo, Explorbot is a separate application designed for constant testing. Cursor, Codex, or Claude Code are coding agents — not relevant here.\n\n\u003e However, Explorbot can be used as subagent or terminal command which is controlled by coding agent.\n\n**Can I bring Cursor or OpenAI Subscription?**\nNo Cursor and OpenAI subscription can't be used. Mostly because their models are slow for Explorbot's usage. We recommend using pay-per-token via Groq and OpenRouter.\n\n**I want to use Opus!!!**\nOpus is great for coding. But for testing we need a simpler model that can safely consume lots of HTML tokens. Opus must be used for sophisticated decision-making, while explorbot needs to collect knowledge from webpages and do it fast.\n\n**Is that expensive?**\nNo. With fast open models (e.g. `openai/gpt-oss-20b` on OpenRouter or Groq), expect roughly **~$1/hour of continuous run**, depending on provider and traffic.\n\n**Does Explorbot have MCP?**\nNot yet.\n\n**Can I build my own agents with it?**\nYes, use the programmatic API. See [docs/scripting.md](docs/scripting.md).\n\n**Ok, but I can do the same in Cursor with Playwright MCP!**\nGood luck running it on CI!\n\n## Development\n\n* Clone this repository\n* Use **Bun** to run TS and TSX with no building\n* Create a sample project under `example` directory:\n\n```\n./bin/explorbot-cli.ts init --path example\n```\n\n* Run your commands using `--path example`\n\n```\n./bin/explorbot-cli.ts start --path example\n```\n\n## License\n\nExplorbot is licensed under the [Elastic License 2.0 (ELv2)](LICENSE).\n\n**Free for commercial use** — you can use Explorbot to test any application, including commercial products, without paying a license fee. You can modify it, self-host it, and integrate it into your workflow.\n\nThe only restriction: you may not offer Explorbot itself as a hosted/managed service (i.e., resell it as a product). This license is used by Elastic, Grafana, and other open-source companies.\n\nExplorbot is built by [Testomat.io](https://testomat.io).\n\n---\n\nExplorbot learns as it explores. The more it tests your app, the better it gets at testing your app. That's vibe-testing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestomatio%2Fexplorbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestomatio%2Fexplorbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestomatio%2Fexplorbot/lists"}