Why product tours break after a deploy, and how to keep yours working
A tour points at elements in your app. Your app changes every week. Here is what actually breaks, and how to build steps that keep finding their element.

The tour worked on Friday. On Monday a designer renamed a few classes, a developer wrapped the toolbar in a new container, and step three now points at nothing. Nobody noticed until a new user did.
This is the most common way onboarding decays, and it is mostly preventable. A tour does not need your app to stand still. It needs each step to describe its element in a way that survives the kind of changes your team makes.
How a step finds its element
Every tooltip step is tied to an element on the page: a button, a field, a menu item. To find it again on a visitor’s screen, the tour stores a description of that element, usually a CSS selector such as header .btn-primary or an XPath such as //button[text()="New project"].
When the step runs, the browser looks for something that matches. One match: the spotlight lands where it should. No match: the step has nothing to point at. Several matches: it may point at the wrong one.
So the question is not whether your app will change. It is which parts of an element’s description are likely to stay the same.
What usually breaks a tour
| Change in your app | What it breaks | What survives it |
|---|---|---|
Classes renamed, or generated by a build tool (css-1x9k2f) | Selectors built on classes | Text, ids, data- attributes |
| Markup restructured: a new wrapper, a moved section | Long structural paths like main > div:nth-of-type(3) > button | Text, ids, data- attributes |
| Button relabelled from “New project” to “Create project” | Selectors based on text | Classes, ids, data- attributes |
| Element only shown after a click (menu, tab, dialog) | Any selector, until the element is on screen | A step before it that opens the menu |
| Page moved to a new address | The page rule of the tour | A pattern that matches the new address |
No single kind of selector survives everything. Text breaks on a copy change; classes break on a redesign. The fix is to keep more than one description and try them in turn.
Keep a backup for every step
When you click an element in the Stepsome editor, the step stores three things: a main selector, up to two backup selectors, and the element’s text. On a visitor’s screen it tries them in that order and uses the first one that finds the element.
The main selector prefers attributes that rarely change. It looks for an id that does not look generated, then attributes such as data-tour, data-testid, aria-label, name and placeholder, and only falls back to classes and position when nothing better is there. The backups are picked so that each one survives a different kind of change: one on the element’s text, one on another stable attribute, one on the structure without classes.
To see them, select the step and open Element in the Step tab. Each selector shows a live count on the current page:
- 1 match is what you want.
- No match on this page means the selector no longer fits.
- 3 matches means it is ambiguous. When that happens, the element with the same text wins.
You can edit any of them, or click Add a backup selector to write your own in CSS or XPath.
Add a data attribute where it matters
The most durable selector is one your team controls. If you can touch the code, give the handful of elements your tours depend on an attribute that exists only for this purpose:
<button data-tour="new-project">New project</button>
Stepsome prefers data-tour over classes and position when it builds a selector, so new steps on that button use it automatically. For existing steps, paste button[data-tour="new-project"] as a backup. The attribute does nothing else, so nobody renames it during a redesign. The same goes for data-testid if your team already writes end-to-end tests: a tour and a test that point at the same element break, and get fixed, together.
You do not need this on every element. Start with the steps of your welcome tour and the buttons your checklist sends people to.
Decide whether the text is part of the element
Matching by text is a strong backup for buttons and menu items, because a label like “Invite teammates” rarely changes in a refactor. It is a poor one for anything that shows data: a counter, a user’s name, a date.
For those, clear the Text field under Element. It then reads Don’t match by text, and the step relies on its selectors alone.
Dynamic addresses and single-page apps
Two more things break tours that are unrelated to selectors.
Ids in the address. A tour built on /projects/8f3a2b1c/settings should run on the settings of every project, not one. Stepsome turns ids in a pasted address (numbers, UUIDs, things like PROJ-123) into :id on its own, so the page rule becomes /projects/:id/settings. Check it under On pages: below the field it says Matches this page or Not this page.
Re-rendering. In React, Vue or Svelte apps, the element you pointed at may be replaced by an identical one a moment later. A tour that holds on to the old element ends up pointing at empty space. Stepsome looks the element up again when the app re-renders it, and keeps the target out from under a sticky header when it scrolls.
What the visitor sees when a step fails anyway
Sometimes the element really is gone. In that case Stepsome waits a few seconds, then shows the step as a card in the middle of the screen without a spotlight. The tour keeps going instead of getting stuck, and the visitor never sees an error.
That is a safety net, not a fix. A step that floats in the middle of the page says “click here” with nothing to point at. Your analytics will show it as a drop at that step; see How to measure user onboarding.
A five-minute check before each release
- Open your staging or preview build and press Alt Shift T.
- Open each published tour and click through its steps. In the editor, a step whose element is missing says so: This step’s element isn’t on the page right now.
- For each missing step, open whatever shows the element (a menu, a tab, a dialog). Still missing? Click Pick it again and point at the new element.
- Check the match counts under Element. Anything other than 1 match deserves a backup.
- If you changed anything, download the site file again and ship it with the release.
Running the check on staging means the fix goes out in the same deploy as the change that caused it. Teams that do this rarely find out about a broken tour from a user.
Starting a new tour? User onboarding for SaaS covers how to choose the steps in the first place.


