> 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/editing-tests/tabs-and-iframes.md).

# Tabs & iframes

How BugBug runs steps in other tabs and inside iframes: the Switch context step, tab numbers, nested iframes, which steps change the context on their own, waiting conditions and common errors.

Every step runs in a **context**: one browser tab, and in that tab either the page itself (**Top**) or one iframe. A test starts in the first tab, on the page itself. To run steps in another tab or inside an iframe, the test needs a **Switch context** step. When you record, BugBug adds it for you.

{% hint style="info" %}
**In short**

* A Switch context step sets the tab (by number) and the frame (Top, or an iframe by its selector). All later steps run there until the context changes again.
* Tabs are numbered from 0 in the order they were opened. The first tab is 0.
* Opening a new tab by clicking a link doesn't switch to it. Add a Switch context step to that tab's number.
* To get back from an iframe to the page, switch context to **Top** in the same tab. You don't need the iframe's selector for that.
* Nested iframes and iframes from other domains (cross-origin) are supported.
* **Execute JavaScript** always runs on the page itself (Top), even when the context is an iframe.
  {% endhint %}

## Switch context step

| Field             | Value                                                                                                                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tab number**    | The tab to switch to. The first tab of the test is 0, the next one opened is 1, and so on.                                                                                                                             |
| **Context**       | **Top** for the page itself, or **Iframe**.                                                                                                                                                                            |
| **Frame element** | Only for **Iframe**: the [selector](https://docs.bugbug.io/preventing-failed-tests/selectors.md) of the iframe. For an iframe inside another iframe, one selector for each level, from the outermost to the innermost. |

When the step runs, BugBug activates the tab, starts at the top of the page and then goes into each iframe in the path, waiting for each one to be ready. The test starts in tab 0, Top, so you don't need a Switch context step at the beginning.

### Steps that change the context on their own

| Step            | Context after the step                                                                                    |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| **Go to URL**   | The same tab, Top, once the page has loaded.                                                              |
| **New tab**     | The new tab, Top.                                                                                         |
| **Open inbox**  | The new tab with the [testing inbox](https://docs.bugbug.io/editing-tests/variables.md), Top.             |
| **Close tab**   | The tab with the next higher number, or the next lower one if the closed tab had the highest number. Top. |
| **Reload page** | The same tab, Top.                                                                                        |
| **Go back**     | The same tab, Top.                                                                                        |

Other steps don't change the context. That includes a click that opens a link in a new tab.

## Tabs

### Open and use a new tab

When a click opens a link in a new tab (for example `target="_blank"`), the test keeps running in the old tab. To continue in the new one:

1. Add a **Switch context** step with the new tab's number (the second tab of the test is 1) and context **Top**.
2. Add the steps for the new tab, for example an assertion on the page URL.
3. To go back, switch context to tab 0, or close the new tab with **Close tab**.

When you record, BugBug adds the Switch context steps for you.

### Tab numbers

* Tabs get numbers in the order the test opens them, starting at 0.
* A tab keeps its number for the whole run. Closing a tab doesn't renumber the others.
* Only tabs opened during the test count. Tabs you had open before don't.

## Iframes

### Work inside an iframe

1. Add a **Switch context** step with context **Iframe** and the iframe's selector, for example `//IFRAME[@id="payment"]`.
2. Add the steps for the elements inside the iframe. Their selectors are searched only inside that iframe.
3. When you're done, add a **Switch context** step with context **Top** to get back to the page.

**Go to URL** always brings you back to Top once the page has loaded, so after it you don't need to switch context back from an iframe.

### JavaScript inside an iframe

* An **Execute JavaScript** step always runs on the page itself (Top) of the current tab, even after you switch into an iframe. To reach an element inside a same-origin iframe from there, go through the iframe, for example `document.querySelector('iframe#payment').contentDocument`. A cross-origin iframe can't be reached this way.
* A **Custom JavaScript** assertion runs in the current context, so after switching into an iframe, `element` is the element found inside that iframe.

See [Custom JavaScript actions](https://docs.bugbug.io/editing-tests/custom-javascript-actions.md).

### Choose a stable iframe selector

The iframe is found by its selector each time the Switch context step runs. Prefer attributes that don't change between runs, such as `id`, `name` or `title`. Avoid selectors based on `src` if the URL contains tokens or session IDs.

### Nested iframes

For an iframe inside another iframe, the Switch context step has one selector per level. BugBug enters the outer iframe first, waits for it, then finds the inner one inside it. Each selector is searched inside the previous iframe's document. Recording sets this up for you.

### Iframes from other domains

Cross-origin iframes, such as payment forms or embedded widgets from another domain, work the same way as iframes from your own domain.

## Waiting conditions and timeout

A Switch context step uses the **Document readyState is complete** and **Page network requests are finished** [waiting conditions](https://docs.bugbug.io/preventing-failed-tests/waiting-conditions.md) by default. It waits until each iframe in the path is ready. If an iframe doesn't get ready before the step's [timeout](https://docs.bugbug.io/preventing-failed-tests/timeout.md), the step fails with `FRAME_LOADS_TOO_LONG`. Like on other steps, you can turn these conditions off for one Switch context step.

## Common errors

| Code                           | Usual cause                                                                                                                              |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `WINDOW_OR_TAB_DOES_NOT_EXIST` | The tab number doesn't exist: the tab wasn't opened, was closed, or the number is off by one (numbering starts at 0).                    |
| `FRAME_LOADS_TOO_LONG`         | The iframe didn't load before the timeout, or its selector matches nothing. Check the selector and the console and network logs.         |
| `ELEMENT_REMOVED`              | The iframe was removed or replaced while BugBug was switching into it.                                                                   |
| `FRAME_DOES_NOT_EXIST`         | The iframe the steps should run in is no longer there, for example because the iframe was removed or replaced. Switch context again.     |
| `ELEMENT_DOES_NOT_EXIST`       | The element is in an iframe, but the test is still in the Top context (or the other way round). Check the Switch context step before it. |

See [Error codes](https://docs.bugbug.io/debugging-tests/error-codes.md) for all codes.

## In YAML and the API

In [YAML](https://docs.bugbug.io/export-import-and-backup/yaml-schema.md), a `switchContext` step has `value` (`topFrame` or `iframe`), `tab_no`, and for an iframe a `selector`:

```yaml
- action: switchContext
  action_details:
    value: iframe
    tab_no: 0
    selector: xpath=//IFRAME[@id="payment"]
- action: type
  action_details:
    selector: css=input[name="cardnumber"]
    value: '4242424242424242'
- action: switchContext
  action_details:
    value: topFrame
    tab_no: 0
```

For nested iframes, join the selectors of each level with `>>`, from the outermost iframe to the innermost:

```yaml
- action: switchContext
  action_details:
    value: iframe
    tab_no: 0
    selector: xpath=//*[@name="parent_iframe"] >> xpath=//*[@name="child_iframe"]
```

Exported files can also contain `window_no`, `frame_no` and `frame_src`. They are recorded details of the frame. The iframe is found by `selector`.

Steps don't have a frame field of their own. Which frame a step runs in comes from the last Switch context step before it, so add the Switch context step first, also when you create steps through the [Public API](https://docs.bugbug.io/integrations/public-api.md) or [MCP](https://docs.bugbug.io/ai-testing/mcp.md).

## FAQ

<details>

<summary>How do I go back from an iframe to the main page?</summary>

Add a Switch context step with context **Top** and the same tab number. You don't need the iframe's selector.

</details>

<details>

<summary>Does BugBug switch to a new tab automatically?</summary>

Only after the **New tab** and **Open inbox** steps. A tab opened by a click or by the page's JavaScript needs a Switch context step.

</details>

<details>

<summary>In which frame does Execute JavaScript run after Switch context?</summary>

On the page itself (Top) of the current tab, even if the context is an iframe. A Custom JavaScript assertion, on the other hand, runs in the current context and gets the element found inside the iframe.

</details>

<details>

<summary>Does BugBug support cross-origin iframes?</summary>

Yes. Switch context into them the same way as into iframes from your own domain.

</details>

<details>

<summary>Are tab numbers 0-based or 1-based?</summary>

0-based. The first tab is 0, the second is 1.

</details>

<details>

<summary>Does Go to URL reset the context to the main page?</summary>

Yes. After Go to URL loads the page, the context is Top in the same tab, even if it was an iframe before.

</details>

<details>

<summary>What happens to the context when I close a tab?</summary>

BugBug switches to the tab with the next higher number, or the next lower one if the closed tab had the highest number, on the Top context. For example, closing tab 1 of tabs 0, 1 and 2 switches to tab 2.

</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/editing-tests/tabs-and-iframes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
