> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/ai-testing/how-to-use-ai-with-bugbug.md).

# How to use AI with BugBug?

BugBug can be used with AI in two ways:

* Built-in BugBug AI improves recording and test execution inside BugBug. It helps with selectors, waiting, scrolling, and clicking. Read more: [How BugBug AI works](/recording-tests-steps/how-bugbug-ai-works.md).
* AI agents can work with your BugBug project through BugBug Plugin, BugBug MCP, and BugBug Skills. This helps you plan tests, create tests, debug runs, review failures, and maintain test suites from Cursor, Claude Code, VS Code, Codex, and GitHub Copilot.

This page describes common AI-assisted workflows. To connect your AI client first, start with [BugBug Plugin](/ai-testing/plugin.md): `npx @bugbug-io/cli plugin --agent=<agent>`. The selected client completes MCP OAuth after installation. You can also read more about [BugBug MCP](/ai-testing/mcp.md) and [BugBug Skills](/ai-testing/skills.md).

{% hint style="info" %}
BugBug MCP access requires a **Pro or higher** BugBug plan. BugBug Skills are available on **all plans**.
{% endhint %}

## Plan test coverage

Use this when you want the AI agent to analyze your product, existing BugBug tests, and missing coverage before creating anything.

Suggested prompt:

{% prompt description="Plan BugBug test coverage" defaultExpanded="full" %}

```markdown
For <application URL> and <project>, plan BugBug coverage for the login, checkout, and account-settings flows. This is read-only: inspect existing tests, suites, components, profiles, variables, and any available product or repository context. If the URL, environment, project, or flow details are missing, ask me before making assumptions. Return prioritized new tests, reusable components, preconditions, coverage gaps, and the evidence supporting each recommendation. Do not create or update anything.
```

{% endprompt %}

The agent should use read-only BugBug MCP tools such as test, suite, component, profile, and variable listing. If it has browser or repository access, it may also inspect the tested application. If not, provide URLs, screenshots, DOM snippets, route lists, or a product brief.

## Create a test from a flow description

Use this when you already know the user flow and want the agent to create a BugBug test.

Suggested prompt:

{% prompt description="Create and run a BugBug test from a flow" defaultExpanded="full" %}

```markdown
For <project>, create a BugBug test for this following flow:

1. Open the pricing page.
2. Choose the Pro plan.
3. Fill the signup form with test data.
4. Assert that the confirmation page is displayed.

First inspect relevant existing tests, components, profiles, variables, and the target application. You are authorized to create this test and its steps, then run it once. If selectors, credentials, URLs, secret values, or expected confirmation content are missing, ask me before continuing. Return the created test name and ID, the final steps and assertions, the run result, and evidence for any failure; do not make unrelated changes.
```

{% endprompt %}

The agent should plan first, create the test only after the scope is clear, use stable selectors, add assertions, and then run the test. If the test fails, it should inspect the run evidence before changing steps.

Related docs:

* [Your first test](/creating-tests/recording-the-tests.md)
* [Manually editing steps](/editing-tests/manually-creating-the-test.md)
* [Assertions](/editing-tests/assertions.md)
* [Selectors](/preventing-failed-tests/selectors.md)

## Debug a failed test run

Use this when a BugBug run failed and you want an evidence-based diagnosis.

Suggested prompt:

{% prompt description="Diagnose a failed BugBug test run" icon="bug" defaultExpanded="full" %}

```markdown
Debug failed BugBug test run <run-url or run-id>.
Inspect the failed step, screenshots, console logs, network logs, DOM evidence, and error code. Return the failure classification, supporting evidence, and smallest proposed fix; do not change the test.
```

{% endprompt %}

The agent should inspect the run details and artifacts before proposing changes. It should not rewrite the test unless you explicitly ask it to apply a fix.

Related docs:

* [Runs history](/debugging-tests/runs-history.md)
* [Screenshots](/debugging-tests/screenshots.md)
* [Console logs](/debugging-tests/console-logs.md)
* [Network logs](/debugging-tests/network-logs.md)
* [DOM Snapshot](/debugging-tests/dom-snapshot.md)
* [Error codes](/debugging-tests/error-codes.md)

## Fix a broken selector

Use this when a step fails because BugBug cannot find or interact with an element.

Suggested prompt:

{% prompt description="Propose a stable replacement selector" defaultExpanded="full" %}

```markdown
For <project>, repair the selector for failed step <step-run-id> in test run <run-id>. First inspect the failed-step details, screenshot, DOM evidence, and current selector. Propose stable replacements using `data-testid`, ARIA labels, visible text, stable IDs, or a unique parent-child selector. Do not change the selector unless I explicitly authorize the chosen replacement. If the run or step ID is missing, ask me. Return the ranked alternatives, evidence, and rationale.
```

{% endprompt %}

If the tested application can be edited, the best fix may be adding a stable `data-testid` or ARIA attribute in the application code. Read more: [Selectors](/preventing-failed-tests/selectors.md).

## Review visual regression failures

Use this when a visual regression step failed and you need to decide whether the change is a product bug or a new valid baseline.

Suggested prompt:

{% prompt description="Review a visual regression failure" icon="images" defaultExpanded="full" %}

```markdown
For <project> and <environment>, review the visual regression failure in test run <run-id>, step <step-run-id>. This is read-only: compare the expected, observed, and diff screenshots plus failed-step details. If the run or step is missing, ask me. Return what changed, whether it appears to be a regression, and a baseline recommendation with evidence. Do not update the baseline unless I explicitly approve it.
```

{% endprompt %}

Related docs:

* [Visual Regression: How it works?](/visual-regression/how-it-works.md)
* [Review & fix](/visual-regression/review-and-fix.md)

## Refactor existing tests

Use this when your project has duplicate steps, unclear test names, or reusable flows that should become components.

Suggested prompt:

{% prompt description="Review tests for maintenance improvements" icon="wrench" defaultExpanded="full" %}

```markdown
For <project>, review <named suites, tests, or area> for maintenance problems. This is read-only: inspect duplicated login or setup steps, unclear names, stale tests, component usage, and suite organization. If the scope is missing, ask me which tests or suites to inspect. Return affected assets, evidence, prioritized recommendations, and an explicit change plan. Do not rename, delete, move, or refactor anything until I approve the exact changes.
```

{% endprompt %}

Good refactoring candidates include duplicated login flows, repeated checkout setup, long tests with unrelated assertions, and suites that mix smoke tests with full regression tests.

Related docs:

* [Components](/editing-tests/components.md)
* [Grouping steps](/editing-tests/grouping-steps.md)
* [Suites](/organizing-tests/suites.md)

## Create a project status report

Use this when you need a QA or PM summary of test health.

Suggested prompt:

{% prompt description="Create a BugBug project status report" defaultExpanded="full" %}

```markdown
For <project> and the period <date range>, create a read-only BugBug status report for <audience>. Inspect run history, test and suite inventory, recurring failures, and recent changes when available. If the project, period, or audience is missing, ask me. Return pass rate, recurring failures, flaky and stale tests, release risks, recommended actions, and the evidence behind each conclusion. Do not run tests or change project data.
```

{% endprompt %}

This workflow is useful before releases, after large UI changes, or when deciding which tests need maintenance first.

## Work with BugBug YAML

Use this when you export tests as YAML, review generated YAML, or import test definitions from files.

Suggested prompt:

{% prompt description="Review a BugBug YAML file before import" defaultExpanded="full" %}

```markdown
For <project>, review the supplied BugBug YAML file before import. This is read-only: validate its schema, step-action details, variables, selectors, reusable components, and secret handling. If the YAML file or intended target environment is missing, ask me for it. Return proven schema or semantic problems, proposed repairs, and import risks; do not modify or import the file until I explicitly approve.
```

{% endprompt %}

Related docs:

* [Running via API](/running-tests/running-via-api.md)
* [Public API](/integrations/public-api.md)

### FAQ

<details>

<summary>How does BugBug use AI for web test automation?</summary>

BugBug uses AI in two ways. Built-in AI improves test recording and execution by handling selectors, waiting, scrolling and clicking. You can also connect AI agents through the BugBug Plugin and MCP to plan coverage, create and maintain tests, run suites, investigate failures and prepare test reports.

</details>

<details>

<summary>What is the difference between BugBug’s built-in AI and an AI agent connected through MCP?</summary>

BugBug’s built-in AI works automatically inside the recorder and test runner to make recorded tests more reliable. An AI agent connected through MCP can interact with your BugBug projects from tools such as Cursor, Claude Code or Codex. It can inspect tests, create steps, start runs and analyze failures when authorized.

</details>

<details>

<summary>Can an AI agent create end-to-end tests from a natural-language description?</summary>

Yes. Describe the user flow, expected result, application URL and target BugBug project. The agent can inspect existing tests and reusable components, create the required steps and assertions, and run the test after receiving authorization. Providing clear test data and expected outcomes produces more reliable results.

</details>

<details>

<summary>Can AI agents debug and maintain existing BugBug tests?</summary>

Yes. AI agents can inspect failed steps, screenshots, console and network logs, DOM evidence and error details. They can identify broken selectors, recurring failures and duplicated test steps, then recommend the smallest appropriate fix. The agent should only modify tests after you explicitly approve the change.

</details>

<details>

<summary>Do I need coding skills to use AI with BugBug?</summary>

No. Product teams and manual QA testers can record tests visually or describe workflows to a connected AI agent in natural language. Developers can also work with the same tests through YAML, MCP, API, CLI and CI/CD when they need more technical control.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bugbug.io/ai-testing/how-to-use-ai-with-bugbug.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.