Frameworks and the DOM

One page, three DOMs#

The DOM (Document Object Model) is the live tree of elements the browser keeps for a page. Tests, scripts and developer tools all work on it, not on the HTML file. How it comes to exist is the first difference between sites.

See how a page loads for the events involved, and Frontends, backends and APIs for where the HTML comes from.

What each framework leaves in the DOM#

Frameworks are libraries that keep the screen in step with the application’s data. To do that they add their own markers, and these markers are the first thing a copied selector latches on to. This table shows what you will meet; the exact names depend on the version and the build.

A few details that matter in practice:

• Generated names change. The hash in Button_primary__3xYz is derived from the file and its contents. Rename a file or upgrade the build tool and every such selector breaks, though nothing a user sees has changed.
• Structure shifts. A framework may wrap a component in extra div elements, and an A/B test may reorder a page. A selector that counts div > div > div:nth-child(3) breaks with it.
• Portals and teleports. A modal is often moved to the end of body, away from the button that opened it. A selector that starts at the button’s parent will not find the dialog.
• Virtualised lists. Long lists (and “infinite scroll”) may keep only the visible rows in the DOM. Row 80 does not exist until you scroll.
• Controlled inputs. React and similar frameworks watch input events, not the field’s value. Setting input.value = "x" from a script changes what is on screen but not what the framework knows, so the next render may erase it. Real, trusted keystrokes fire the events the framework listens for.

Hydration and why clicks get lost#

Server rendering with hydration. The gap between the two notes is where a very early click does nothing.

A test that clicks as soon as the button is visible can click inside that gap. The click is delivered, but no handler is attached, so nothing happens and the test fails for no visible reason. Remedies, from best to worst:

1. Wait for the effect, not for the clock. Click, then wait for the thing the click should cause. If it does not appear, click again, a few times at most.
2. Wait for a signal the app gives when it is ready, if the team can add one (an attribute set after hydration, or a network request that the page makes only once it is interactive).
3. Do not add a fixed sleep. It is slow when the page is fast and still fails when the page is slow.

Hydration mismatches are a related bug. If the HTML the server made differs from what the browser would build (a date formatted in two time zones, a random id, a value that depends on window), the framework warns in the console and may rebuild the part of the page, discarding what a test just typed. A Console error about hydration in a test run is worth reading (see Developer tools).

Web Components and the shadow DOM#

Web Components are the browser’s native way to make reusable elements: custom tags such as my-card, defined with JavaScript. A component can attach a shadow root, a private DOM tree inside the element. Styles and selectors from outside do not reach into it, which is the point: the component’s insides cannot be damaged by the page around it.

• An open shadow root can be entered by script (element.shadowRoot).
• A closed shadow root cannot be entered from page script.
• Content passed in from outside appears through slots.

A plain CSS selector such as my-card button stops at the shadow boundary and finds nothing. Tools therefore offer a way to cross it. In BaseCase this is the ::shadow combinator, as in sb.shadow_click("my-app ::shadow button"); see Shadow DOM and the Selectors guide. Closed roots cannot be entered by WebDriver or CDP either.

Why a selector works on one site and not on another#

A selector is a question asked of the DOM. It fails when the answer changes, and the usual reasons are these:

diagnose_selector (an MCP tool) answers this question for a given selector: it reports invalid syntax, no match, matches that are hidden, off screen, disabled or covered, matches inside an iframe or a shadow root, and near misses such as a similar id. suggest_selectors proposes ones that work and inspect_page outlines the page. See Developer tools.

Stable strategies#

Choose selectors by what is meaningful and intended, in this order:

1. A test attribute the team owns: data-testid, data-test or data-qa. They exist only for tests, so nobody changes them by accident. If the application has none, ask for them; it is the cheapest fix.
2. Role and accessible name. A “Sign in” button has the role button and the name “Sign in” whatever markup produced it. These are the same facts that screen readers use, so a selector built on them also checks that the page is accessible.
3. Label or visible text. A field is “the one labelled Email”. A button is “the one that says Add to cart”. Users find the page this way, so tests written this way follow what users see, and they survive restyling.
4. A stable id or name, if the application writes them by hand. Ignore ids a framework generates.
5. Short CSS structure only as a last resort, and never a long chain or a position (nth-child).

Avoid anything copied from a framework’s output: hashed class names, data-v-*, _ngcontent-*, svelte-*, and css-* classes.

How seleniumbase-rs reads a selector#

Every method that takes a selector reads a plain string and works out its kind from how it begins (Selector::auto in src/utils/selectors.rs):

The prefixes are matched exactly, so LINK=Home is CSS. To state the kind yourself, use the Selector enum (Css, XPath, LinkText, PartialLinkText and Id; an Id needs no escaping, which helps with ids such as :r1:) or the owning type SelectorBuf, which the pure CDP engine takes in Page::locator.

SelectorBuf also has constructors for the stable strategies above. They build XPath for you, as approximations of Playwright’s getByText, getByLabel and getByRole:

Their limits are written in their documentation: aria-labelledby is not followed, and roles that depend on context, hidden elements and states such as checked are not covered.

use seleniumbase_rs::utils::selectors::SelectorBuf;// A test attribute: the most stable choice.page.locator("[data-testid='checkout']").click().await?;// By role and accessible name, whatever markup the framework made.page.locator(SelectorBuf::role("button", Some("Sign in"), false)).click().await?;// By the text a user reads.page.locator(SelectorBuf::text("Add to cart", true)).click().await?;

// The prefix says what kind of selector this is.sb.click("[data-testid='checkout']").await?;sb.click("link=Sign up").await?;sb.assert_text_visible("$42.00", "[data-testid='total']").await?;

Where to go next#