Execution Modes

TestBro supports three execution modes that determine how it locates elements on the page during test runs. Choose the mode that best fits your testing scenario.

Selector Mode

Fast and deterministic. Uses CSS selectors and ARIA roles to find elements.

testbro run --url https://example.com --mode selector

How it works

1. Each test step includes a target with selector information (CSS selector, role, or test ID)
2. Playwright uses the selector to locate the element directly
3. If the selector fails, the step fails immediately

Best for

• Regression testing on stable UIs where selectors rarely change
• Maximum execution speed
• Tests where you have pre-defined selectors from the dashboard or learned from previous AI runs

Limitations

• Breaks when UI structure changes (class names, element hierarchy)
• Requires selectors to be defined upfront or learned from AI mode

AI Mode

Flexible and adaptive. Uses GPT-4o-mini vision to find elements on the page.

testbro run --url https://example.com --mode ai

How it works

1. The AI agent takes a screenshot of the current page
2. It analyzes the screenshot to understand the page layout and content
3. For each step, it uses vision to locate the target element by its description
4. It performs the action (click, type, navigate) and verifies assertions visually

Best for

• Testing new or rapidly changing features
• Dynamic UIs where elements are generated at runtime
• When you do not have selectors defined yet
• Running tests generated from PRD or description files

Limitations

• Slower than selector mode (requires API calls for each step)
• Requires an OPENROUTER_API_KEY environment variable
• May occasionally misidentify elements on complex pages

Hybrid Mode (Recommended)

Best of both worlds. Tries selectors first, falls back to AI when selectors fail.

testbro run --url https://example.com --mode hybrid

How it works

1. For each step, the executor first attempts to use the stored selector
2. If the selector succeeds, it proceeds immediately (fast path)
3. If the selector fails or is missing, it falls back to the AI agent
4. When AI finds an element, it can learn the selector for future runs

Best for

• Production test suites that need both speed and resilience
• Gradually building up selector coverage over time
• Teams transitioning from manual to automated testing

Selector Learning

In hybrid mode (and AI mode), TestBro can learn selectors from successful AI interactions. After a test run, if the AI found elements that did not have selectors, you will be prompted to save the learned selectors:

testbro run --mode hybrid --learn-selectors

Use --yes to auto-confirm selector learning without prompts:

testbro run --mode hybrid --learn-selectors --yes

Learned selectors are stored in the test case and used in future selector and hybrid runs.

Choosing a Mode

Setting Default Mode

You can set a default mode in your test-bro.config.json:

{
  "mode": "hybrid"
}

The --mode flag on the CLI always overrides the config file.

Next Steps

• Test Cases -- How test cases and steps work
• CLI Reference -- All run command options
• CI/CD Integration -- Automated testing setup