> 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/recording-tests-steps/how-bugbug-ai-works.md).
# How BugBug AI works
BugBug's AI capabilities are built into the test recorder and test execution engine. They activate automatically — during recording, before each test step, and at run time. You don't configure or enable them separately.
There are three AI features:
| **Feature** | **When it runs** | **What it does** |
| -------------------- | ---------------------- | --------------------------------------------------------------------------- |
| Adaptive Locators | During recording | Generates the most stable selector for each element you click |
| Smart Click & Scroll | During test execution | Mimics real user behavior; handles dynamic, covered, or off-screen elements |
| Smart Waiting | Before every test step | Checks that the page and element are ready before acting |
### Adaptive Locators
When you click an element during recording, BugBug generates multiple selectors for it simultaneously and evaluates which is most likely to stay stable across UI changes.
Priority order:
1. `data-testid` / `data-test` and custom attributes defined by the user (most stable — tied to developer intent, not visual structure)
2. Visible text content (e.g. a button labeled "Save")
3. Names, ids, semantic tags, roles and ARIA labels (e.g. `role="button"`, `aria-label="Submit"`)
4. Other `data-*`
5. Unique parent-related selector
6. CSS classes and IDs (only if stable — dynamic or auto-generated ones are deprioritized)
7. DOM position (last resort — most fragile)
BugBug skips dynamic values. The selected locator is stored with the test step. You can view and override it manually if needed.
BugBug also automatically prioritizes element attributes and properties that are unique on the page.
For example, if an element has a `data-testid`, but another earlier element uses the same value, BugBug treats it as non-unique. The selector then gets an index, making it less preferred because indexed selectors are more likely to break when the page structure changes.
When BugBug detects an indexed selector, it still tries to make it more reliable — for example, by finding a unique parent element and combining it with the target element selector. This can create a more stable selector path and move it higher in the selector priority order.
{% hint style="info" %}
**Tip:** If your app has `data-testid` or ARIA attributes on key elements, BugBug will always prefer them. Ask your frontend team to add them to primary CTAs, form fields, and navigation items — it's the single most effective way to make tests long-lived.
{% endhint %}
[Learn more about selectors →](/preventing-failed-tests/selectors.md)
***
### Smart Click & Scroll
BugBug simulates real cursor movement instead of dispatching JavaScript click events directly. This means:
* It will not click an element that a real user couldn't click — if the element is covered by a modal, cookie banner, or overlay, BugBug detects this and retries.
* It scrolls automatically — if the target element is outside the viewport, BugBug scrolls to bring it into view before clicking. You don't need to add scroll steps manually.
* It avoids covered elements — if another element overlaps the target, BugBug scrolls the page until it finds a clear position where the target can be clicked safely.
* It finds the clickable area — if the center of an element is covered, BugBug looks for an uncovered point within the element's bounds and clicks there.
* It avoids accidental clicks on nested elements — if the target element contains another clickable element, BugBug finds a safe position within the target so the intended element is clicked, not the element inside it.
[Learn more about Smart click →](/preventing-failed-tests/smart-click.md)
[Learn more about Smart scroll →](/preventing-failed-tests/smart-scroll.md)
***
### Smart Waiting
Before executing each step, BugBug checks a series of conditions. If they aren't met yet, it waits — up to the configured timeout — before proceeding.
**Conditions checked automatically:**
* Document readyState is complete (Page has finished loading)
* Page network requests are finished
* Element must have expected attributes
* Element exists in the DOM
* Element is visible (not hidden with `display:none` or `visibility:hidden`)
* Element is not animating
* Element is not covered by the other one
* Element must be active
* Element has focus
* Page URL has changed (for steps that trigger navigation)
* Page will navigate after step execution
This is why you don't need manual `sleep` or `delay` steps in most cases.
You can view, enable, or disable individual waiting conditions per step, and set global defaults in Project Settings.
[Learn more about Waiting conditions →](/preventing-failed-tests/waiting-conditions.md)
***
### Security & AI FAQ
Is BugBug AI based on generative AI or LLMs?
No. BugBug AI does not use large language models to generate, rewrite, or execute your tests. The AI features are built into the recorder and execution engine to improve selector choice, waiting, scrolling, and clicking behavior. They are designed to make tests more stable and human-like, not to send your test data to an external AI model.
When BugBug creates locators, it uses prepared, structured data about DOM elements instead of processing a DOM snapshot of the entire page.
Does BugBug send my app's data to third-party AI providers like OpenAI or Anthropic?
No. BugBug's AI features (Adaptive Locators, Smart Click & Scroll, Smart Waiting) run within BugBug's own infrastructure. Your app content, test steps, and recorded interactions are not sent to external AI or LLM providers as part of the test recording or execution process.
Is my test data used to train AI models?
No. Your recorded tests and test run data are used solely to execute your tests. BugBug does not use customer test data to train or improve AI models.
Can I disable BugBug AI features?
Some behaviors can be adjusted at the step or project level. For example, waiting conditions can be enabled, disabled, or customized per step, and global defaults can be managed in Project Settings. Adaptive Locators are part of how BugBug records stable tests, but you can manually review and override selectors when needed.
Does BugBug AI automatically rewrite or change my tests?
No. BugBug does not silently rewrite your test steps. During recording, Adaptive Locators choose the most stable selector for each element. During execution, Smart Waiting, Smart Click, and Smart Scroll help the existing step run more reliably. You can still review, edit, or override selectors manually.
What if BugBug selects the wrong element or selector?
You can inspect the selector saved with each test step and override it manually. BugBug prioritizes stable selectors such as data-testid, ARIA labels, visible text, and stable IDs/classes, but manual editing is available when your application needs a more precise locator.
Does BugBug self-heal broken selectors at run time?
BugBug improves selector stability during recording by choosing the most reliable locator available. During execution, Smart Waiting, Smart Click, and Smart Scroll help the step run under real page conditions. If the application changes so much that the saved selector no longer identifies the right element, you may still need to update the step manually.
Where does AI processing happen?
BugBug's infrastructure is hosted in the EU — specifically in Gdańsk, Poland ([IQ Data Center](https://www.iq.pl/data-center)). AI processing for the test recorder runs within this infrastructure. No data is transferred outside the EU as part of normal recording or cloud test execution.
What data does BugBug collect during recording?
During recording, BugBug captures:
* The interactions you perform (clicks, typing, navigation, form selections)
* The DOM selectors of elements you interact with
* Screenshots taken at each step (during cloud runs)
* URLs visited during the test
BugBug does not record audio, video of your screen outside the test window, or any data from browser tabs other than the active incognito test window.
{% hint style="info" %}
**Hint:** Each test runs in a fresh incognito window — no cookies, cache, or localStorage from your regular browser session are present.
{% endhint %}
Does BugBug AI process passwords, form values, or sensitive test data?
BugBug records the data required to replay your test steps, including typed values if they are part of the test. These values are not sent to third-party AI providers or used to train AI models. For sensitive data, use test accounts, variables, and non-production credentials wherever possible.
Who at BugBug can access my recorded tests?
Access to the BugBug database is strictly limited to the BugBug application infrastructure. Within the BugBug team, only the IT department has access to customer data. BugBug conducts annual security audits, and internal access is governed by role-based policies.
Is BugBug GDPR compliant?
BugBug's servers are located in the EU (Gdańsk, Poland), which means your data is stored within EU jurisdiction. BugBug is built with data privacy in mind — encrypted connections (SSL), encrypted passwords, and strict access controls are standard.
For formal GDPR documentation or a Data Processing Agreement (DPA), contact .
Can I use BugBug's AI features if my app is behind a firewall or VPN?
The AI features in the test recorder work locally during recording — they don't require outbound calls to external services, so a firewall or VPN doesn't affect them.
For cloud test runs, BugBug's cloud runners must be able to reach your application. If your app is behind a firewall, you'll need to whitelist BugBug's cloud runner IPs.
[IPs list of cloud runners →](/troubleshooting/ips-list-of-cloud-runners.md)
[VPN or Firewall →](/troubleshooting/vpn-or-a-firewall.md)
Is there any AI processing during cloud test runs that's different from local runs?
No. AI processing does not differ between local and cloud runs. In both cases, BugBug uses the same Chrome extension to replay tests, so selector handling, waiting, scrolling, and clicking behavior work the same way.
Local and cloud runs capture screenshots at each step by default. These screenshots are stored securely in BugBug’s infrastructure and are available in every test step’s details.
[Runs history →](/debugging-tests/runs-history.md)
[Run in cloud →](/running-tests/in-cloud-on-server.md)
---
# 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/recording-tests-steps/how-bugbug-ai-works.md?ask=&goal=
```
`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.