BugBrain AI Testing Agents
The BugBrain AI agent is the core of the platform. It autonomously navigates your web application, makes intelligent decisions about what to click and type, verifies expected outcomes, and explains failures.
How the AI Agent Works
The agent operates in a continuous loop:
1. Think
The AI receives the current state of the application (screenshot, page content, DOM) and your test step instructions. It plans the next action:
Current step: "Click the 'Checkout' button"
Page state: A form with email/password fields and a blue button
Agent thinks:
- Email field is visible and empty
- Password field is visible and empty
- Blue button labeled "Checkout" is visible
- I should click the button to proceed2. Act
The agent executes the planned action on the actual application:
Agent action: click([data-testid='checkout-button'])
Result: Button clicked, page transitions to /checkout3. Observe
The agent checks what changed on the page and whether the action succeeded:
Page changed to /checkout
New URL: https://app.example.com/checkout
Page contains "Order Summary" heading
Action was successful ✓4. Repeat
The agent moves to the next step and repeats. This cycle continues for up to 50 iterations per test (configurable).
What the Agent Can Do
The AI agent can perform any user action:
| Action | Example | Use Case |
|---|---|---|
| Navigate | goto('https://example.com') | Open a URL |
| Click | click('[data-testid="submit-btn"]') | Submit forms, open modals |
| Type | type('#email', 'user@example.com') | Fill input fields |
| Select | select('#country', 'United States') | Choose from dropdowns |
| Scroll | scroll('down', 500) | Reach bottom-of-page content |
| Wait | wait(2000) | Wait for slow animations |
| Assert | assert page.contains('Success') | Verify expected text |
| Screenshot | Auto-captured per step | Visual debugging |
| Extract | Get table data, form values | Data validation |
Handling Complex Scenarios
Authentication
Seamlessly handles login using Personas:
- Basic username/password forms
- Email OTP (2-3 second OTP window)
- Magic links
- TOTP / MFA codes
No manual credential entry needed. Learn more →
Session Caching
After first login, sessions are cached for 8 hours:
- Second run skips login entirely
- Tests run 5x faster
- Distributed lock prevents duplicate auth attempts
Dynamic Content
The agent handles:
- Lazy-loaded content
- AJAX requests
- Modal dialogs
- Single-page applications (React, Vue, Angular)
- JavaScript-heavy interactions
Error Recovery
When actions fail, the agent:
- Retries with different selectors
- Waits for elements to appear
- Handles unexpected state changes
- Logs detailed information for debugging
AI Model Selection
BugBrain uses your preferred LLM provider in this order:
- BrowserUse API — Specialized for testing, fastest
- Claude (Anthropic) — Best quality, most capable
- Gemini (Google) — Cost-effective, fast
- GPT-4o (OpenAI) — Excellent general-purpose
You control which models are available by setting environment variables in Settings.
Configuration Options
Max Iterations
Default: 50 iterations per test
Increase for complex flows, decrease for simple tests to save cost and time.
Execution Timeout
Default: 300 seconds (5 minutes)
Maximum time a single test can run. Useful for catching infinite loops or deadlocks.
Browser Mode
Default: Headless (no browser window)
- Headless mode — Faster, uses less CPU, perfect for CI/CD
- Headed mode — See the browser window, useful for debugging
Set in your project’s execution settings or per-execution.
Cost Optimization
To optimize testing costs:
- Leverage session caching — Eliminates redundant login steps, saves time and resources
- Use test plans efficiently — Group related tests to share setup and teardown
- Set appropriate timeouts — Adjust timeout values based on your app’s performance
- Reduce unnecessary steps — Each step takes time; keep tests focused
- Batch tests — Running multiple tests together is more efficient than running individually
AI Agent Limitations
The agent cannot (yet):
- File uploads — Drag/drop, file selection dialogs
- Desktop applications — Only web browsers
- Custom protocols — Only HTTP/HTTPS
- Hardware interaction — Camera, microphone, printers
- JavaScript evaluation — Can’t run arbitrary JS (intentional for security)
These limitations are rare for web applications; most workflows are fully automated.
Performance Expectations
| Scenario | Avg Duration | Speed |
|---|---|---|
| Simple login test (3 steps) | 2 seconds | 2-5s |
| Multi-step form (8 steps) | 8 seconds | 1-2s per step |
| Auth + checkout flow (12 steps) | 15 seconds | 1-2s per step |
| Auth test (with caching) | 1 second | ✓ 10x faster |
| Complex flow (50+ iterations) | 60 seconds | 1s per iteration |
Execution time depends on page load speed, complexity, and your network connection.
Next Steps
- Browser Automation — How the AI controls your browser
- Failure Analysis — Understand test failures
- Authentication Testing — Test login flows