> 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/preventing-failed-tests/smart-scroll.md).

# Smart scroll

How BugBug automatically scrolls an element into view before interacting with it: when it scrolls, how it handles covered, partly visible and nested elements, iframes, and when you still need a Scroll

Before BugBug clicks, types into or checks an element, it makes sure the element can actually be reached. If the element is outside the visible part of the page, or something covers the point BugBug wants to interact with, BugBug scrolls it into view first. You don't need to record scroll steps for this.

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

* Works automatically for every step that targets an element with a selector. There is nothing to configure.
* BugBug only scrolls when it has to. An element whose interaction point is already visible and not covered isn't scrolled, even if part of it is off screen.
* The element must already exist on the page. To load content that appears only after scrolling, such as infinite lists, add a [Scroll step](/editing-tests/actions.md).
  {% endhint %}

## When BugBug scrolls

Smart scroll runs while BugBug checks the step's [waiting conditions](/preventing-failed-tests/waiting-conditions.md). BugBug finds the element and checks the point it will interact with, by default the point chosen by **Smart** interaction position:

* If that point is inside the viewport and nothing covers it, BugBug doesn't scroll.
* If the point is outside the viewport, or another element covers it, BugBug scrolls.

So your test doesn't fail when new content pushes a button below the fold, or when a sticky header or banner sits on top of the element and scrolling moves it out from under it.

## How it scrolls

1. BugBug scrolls the element to the **center** of the viewport, the same way the browser's `scrollIntoView()` does. Scrollable containers the element sits in, such as a sidebar or a modal with its own scroll, are scrolled too.
2. When scrolling stops, BugBug checks the interaction point again.
3. If it's still covered, BugBug tries other positions: element at the top, at the bottom, at the left, at the right, and finally an instant jump without smooth scrolling.
4. If none of them helps, the step continues with the normal waiting conditions, and **Element is not covered** reports what covers the element.

BugBug doesn't reset scroll positions it didn't change.

### Special cases

* **Element inside a hidden parent.** If a parent is not rendered (`display: none`), BugBug scrolls the nearest visible parent into view, so content that appears on scroll gets a chance to render.
* **Element inside an iframe.** If the iframe itself is below the fold, BugBug scrolls the iframe into view on the main page as well.
* **Chained selectors.** When a selector is a chain (*Then find its parent / child / sibling*), only the final element is scrolled into view.
* **Shadow DOM.** Scrolling inside shadow DOM containers is handled too.

## Time limit

Smart scroll only runs during the part of the step's [timeout](/preventing-failed-tests/timeout.md) reserved for waiting conditions: 70% of the timeout for timeouts up to 10 seconds, 50% for longer ones. After that, BugBug stops trying to scroll and runs the step with the element where it is.

## When you need a Scroll step

Add a [Scroll step](/editing-tests/actions.md) when:

| Situation                                                                                                | Scroll step `scroll_to`                                                             |
| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| The element is loaded only after you scroll (infinite list, lazy loading, a dropdown that loads options) | `untilNextStepElementIsVisible`: scrolls until the element of the next step appears |
| You need to scroll to an exact position                                                                  | `coords`                                                                            |
| You need to reach an edge of a list or the page                                                          | `edge`                                                                              |

## FAQ

<details>

<summary>Does BugBug scroll the element into view before a click?</summary>

Yes, when it's needed. If the click point is outside the viewport or covered by another element, BugBug scrolls the element to the center of the viewport and checks again before clicking. If the point is already visible and not covered, it clicks without scrolling.

</details>

<details>

<summary>Does smart scroll work with nested scrollable containers?</summary>

Yes. BugBug uses the browser's scroll-into-view behaviour, which scrolls every scrollable container around the element, not only the page.

</details>

<details>

<summary>Why does my test fail with ELEMENT_DOES_NOT_EXIST on a long list?</summary>

Smart scroll can only scroll to an element that is already in the page. If the list loads more items as you scroll, add a Scroll step that scrolls until the next step's element is visible (`untilNextStepElementIsVisible`) before the step that uses the item.

</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/preventing-failed-tests/smart-scroll.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.
