Why CSS Selectors Break — and How I Built StableHTMLFinder to Analyze DOM Stability

Pavel Borisov — Tue, 20 Oct 2026 12:00:00 +0000

If you've ever written CSS selectors for browser automation, web scraping, or blocking unwanted elements, you've probably encountered this situation: a selector works perfectly today, but tomorrow it can no longer find the element you need.

Often, the problem isn't the selector itself. It's the page.

Modern websites frequently use dynamically generated classes, changing attributes, advertising elements, and JavaScript-driven interfaces whose DOM structure can differ between page loads.

I encountered this problem while developing BlockIt, a Chrome extension for blocking unwanted elements on web pages.

At some point, I needed a tool that would help me understand which parts of the DOM actually remain unchanged across repeated page loads.

That's how StableHTMLFinder was born.

In this article, I'll explain why I created it, what a DOM stability map is, and how it helps identify reliable element characteristics — without going into the internal implementation of its algorithms.

The Problem: The DOM Keeps Changing

Imagine you want to hide an advertising block on a website.

You open DevTools, inspect the element, and see something like this:

<div class="ad-container_x7Kp2">
    <div class="banner_9fA31">
        Advertisement
    </div>
</div>

You could write a selector:

.ad-container_x7Kp2

It works. But after refreshing the page, the HTML looks different:

<div class="ad-container_m4Rz8">
    <div class="banner_2qB76">
        Advertisement
    </div>
</div>

Your selector no longer matches the element.

Of course, you could try matching part of the class name:

[class^="ad-container_"]

But this approach only works when dynamically generated values follow a predictable pattern.

What if not only classes but also IDs, attributes, nesting levels, or element positions change?

You have to examine the surrounding DOM structure and look for more reliable reference points.

This leads to the central question:

How can we distinguish genuinely stable DOM characteristics from those that merely happen to look stable in the current page load?

Why a Single DOM Snapshot Isn't Enough

Many conventional selector-generation tools analyze the current state of a page.

They can identify a unique class or ID, construct a CSS path, or generate an XPath expression.

But uniqueness and stability are two very different things.

Consider this example:

<button id="action_583921" class="btn_8xQ2">
    Continue
</button>

The ID action_583921 might be unique on the page. But that tells us nothing about whether it will remain the same after a refresh.

A tool that examines only one DOM snapshot cannot directly observe how that ID changes between page loads.

Of course, heuristics can help identify classes or IDs that appear to be dynamically generated. But an educated guess is not the same as observation.

When I started developing StableHTMLFinder in 2026, I couldn't find a tool that automatically collected multiple snapshots of the same page and used them to build a visual map of stable elements and their characteristics.

And I wasn't trying to build another selector generator.

My original idea was much simpler: remove all the unstable noise from the DOM and see what remains.

Introducing the DOM Stability Map

StableHTMLFinder is a free Chrome extension that analyzes multiple consecutive page loads and builds a stability map from the collected DOM snapshots.

Its structure resembles a DOM tree, but with one fundamental difference: it displays only elements and characteristics whose stability has been established during the analysis.

Suppose the same element appears across several page loads.

First load:

<section class="content_a72" data-session="1842">
    <h2 class="section-title">News</h2>
</section>

Second load:

<section class="content_b91" data-session="7501">
    <h2 class="section-title">News</h2>
</section>

Third load:

<section class="content_c38" data-session="3926">
    <h2 class="section-title">News</h2>
</section>

In this simplified example, we can observe that:

The section tag remains unchanged.
The class attribute is always present, but its value changes.
The data-session attribute is always present, but its value also changes.
The child h2 element and its class remain unchanged.

If the elements can be matched reliably across page loads, the stability map might represent the structure approximately like this:

<section class data-session>
    <h2 class="section-title">
        News
    </h2>
</section>

This is a schematic illustration, not an exact representation of the StableHTMLFinder interface.

Notice that the attribute names class and data-session remain, while their unstable values disappear.

The stability map can therefore distinguish between several situations:

An element, its attributes, and their values are stable.
An element and certain attribute names are stable, but their values are not.
The element itself can be identified across page loads, but its attributes provide no reliable reference points.

The purpose of this representation isn't to show as much HTML as possible.

It's to retain only information that may be useful for constructing a reliable selector.

Instead of examining dozens of random-looking classes, you can focus on characteristics that actually remain consistent across page loads.

Here's what a section of the stability map looks like in practice. This example shows a fully stable part of a web page, where elements and their attributes remain consistent across multiple page loads. The tree-like structure makes it easy to explore these elements and their relationships without the distraction of unstable DOM characteristics.

Fully Stable and Relatively Stable Elements

Not every element can be matched across page loads with the same level of confidence.

That's why StableHTMLFinder distinguishes between fully stable and relatively stable elements.

Fully stable elements are the most reliable parts of the stability map. Their own characteristics, along with those of their parents and immediate children, match exactly across the analyzed snapshots.

These elements provide particularly useful reference points when examining the page structure.

Relatively stable elements are elements for which there is sufficient evidence that they represent the same DOM element across different page loads, even though some characteristics or parts of the surrounding structure may change.

They are displayed in a lighter color on the stability map.

This is an important distinction: StableHTMLFinder doesn't assume that everything on a page must be either completely stable or entirely unsuitable for analysis.

In real-world web applications, things are much more complicated.

An element may retain its purpose while its classes change. Its parent may receive new attributes. Additional containers may appear between otherwise familiar elements.

Rather than discarding everything that isn't perfectly stable, StableHTMLFinder preserves elements whose identity can still be established with reasonable confidence.

Islands of Stability Inside a Dynamic DOM

One of the more interesting features of StableHTMLFinder is its ability to display islands of stability.

Imagine that an entire chain of nested containers changes between page loads.

During one load, the element you're interested in is nested inside two intermediate containers. During another, it might be nested inside four. Their classes and attributes may also be different.

But somewhere inside this unstable structure, an element with recognizable characteristics remains.

It would be a mistake to discard that element simply because its ancestors are unstable.

StableHTMLFinder can preserve such an element on the stability map while representing the unstable intermediate levels using special gray placeholders.

These placeholders resemble elements in the tree, but they actually represent unstable structures with potentially varying nesting depths.

As a result, you can see that an unstable region exists between stable parts of the page without losing the ability to examine the elements inside it.

This can be particularly useful on websites where JavaScript dynamically rebuilds parts of the interface.

Finding Elements on the Stability Map

Suppose you've found an element on a website that you want to block.

You open DevTools and inspect its HTML, but the classes and IDs look randomly generated.

Instead of manually examining numerous parent and child elements, you can use StableHTMLFinder's search feature.

The search supports several approaches, including:

Pasting an HTML element copied from DevTools.
Entering a selector to locate the corresponding element.

If the element exists on the stability map, you can navigate to its card and examine the available stable characteristics.

This provides a convenient way to move from the original DOM, filled with dynamically changing values, to a cleaner representation of the same page.

It's particularly helpful when the target element itself has no reliable attributes, but more stable elements exist nearby.

How to Improve Search Accuracy

StableHTMLFinder performs its search primarily against the last DOM snapshot collected during the analysis.

If you haven't reloaded the page since the analysis finished, and the target element hasn't changed due to JavaScript activity, you can copy it from DevTools and paste it into the search field.

In this case, the extension will accurately locate the corresponding element on the stability map, even if all its attributes and their values turned out to be unstable and only the element's tag remains on the map.

If, however, you copied an element that had already changed since the last DOM snapshot, the search may still succeed. StableHTMLFinder will attempt to match it using the characteristics that remain recognizable, but with a lower level of confidence.

Automatic Selector Generation

Although StableHTMLFinder was originally designed as a visual DOM analysis tool, I later added automatic selector generation.

It seemed like a natural extension of the original idea.

If the tool has already identified stable characteristics of an element and its surroundings, why not try generating a selector from them?

From an element's card, you can obtain a suggested selector and copy it.

A human-readable explanation is displayed alongside the selector, describing which characteristics were used to construct it.

I consider this important because a selector shouldn't be an incomprehensible string that users have to trust blindly.

However, there's an important limitation.

In particularly complex cases, StableHTMLFinder may be unable to generate a unique selector for a given element.

Although the extension can usually generate a unique selector, some elements lack a unique combination of stable characteristics within their nearby DOM structure. In these rare cases, StableHTMLFinder clearly indicates that a unique selector could not be generated.

Some pages are structured in ways that simply don't provide enough stable characteristics.

In those cases, the stability map can still be valuable because it gives you the information needed to investigate the problem and develop your own solution.

That's why I see automatic selector generation as a convenience feature rather than the extension's primary purpose.

How StableHTMLFinder Connects to BlockIt

StableHTMLFinder originated while I was working on another project of mine: BlockIt.

BlockIt is a Chrome extension for blocking unwanted elements on web pages.

It supports rules based on CSS, XPath, and additional conditions, along with more advanced methods of locating elements.

But even a powerful rule syntax can't solve the fundamental problem: if a rule relies on unstable characteristics, it may stop working after the next page load.

StableHTMLFinder helps identify more reliable reference points for those rules.

The two extensions serve different purposes:

StableHTMLFinder analyzes a page, displays its stability map, and helps create selectors. It doesn't block anything itself.

BlockIt uses rules to locate and block unwanted elements on web pages.

StableHTMLFinder can also suggest special rules designed for use with BlockIt.

In other words, one extension helps you investigate the DOM and prepare a rule, while the other applies that rule in practice.

I'll cover BlockIt and its capabilities in a separate article.

Can StableHTMLFinder Be Useful Beyond Ad Blocking?

Although the project grew out of the need to block unwanted elements, unstable DOM locators are a problem in other areas as well.

One example is browser automation and UI testing.

If a test relies on a dynamically generated class, it may fail after a page update even though the button or form it's supposed to interact with still exists.

A stability map could potentially help developers identify more reliable reference points.

Similar challenges sometimes arise when writing browser scripts or extracting data from websites.

However, StableHTMLFinder isn't a universal solution for these scenarios. Its usefulness depends on the structure of the particular website and whether sufficiently stable characteristics can be identified.

There's also an important distinction between observed stability and guaranteed future stability.

Just because an element remained unchanged across several page loads doesn't mean it will never change.

The stability map reflects the results of the analysis, not an absolute guarantee.

Why I Think This Approach Matters

When developing StableHTMLFinder, I wanted to change the way I worked with the DOM.

Normally, a developer opens DevTools, sees an enormous tree of elements, and tries to figure out which characteristics are suitable for a selector.

But much of that information may be useless: random classes, temporary IDs, dynamic attributes, and constantly changing containers.

StableHTMLFinder takes a different approach:

First, identify what remains stable across page loads. Then decide how to use those characteristics.

This doesn't eliminate every challenge associated with dynamic DOM structures, and it doesn't make selectors immune to future website changes.

But it allows you to focus on more reliable information and reduce the amount of manual investigation required.

And perhaps that best captures the original idea behind the project: not necessarily to write a selector for you, but to let you see a web page without the noise of constantly changing DOM characteristics.

Try StableHTMLFinder

StableHTMLFinder is a free Chrome extension.

If you'd like to try it yourself, visit the official StableHTMLFinder project page, where you'll find a link to install the extension from the Chrome Web Store.

If you work with dynamic web pages, I'd be interested to hear what challenges you've encountered with selector stability and how you've approached solving them.

DEV Community: Pavel Borisov