A UI redesign may leave the application functioning perfectly, yet cause dozens of Playwright tests to fail. By designing tests that focus on semantics rather than implementation details, you can keep your suite resilient.
When a design-system migration lands, the visual output and component behavior appear correct, but the [continuous integrationpipeline shows a flood of red tests. Those failures do not indicate broken features; they reveal that the test suite is tightly bound to the underlying markup. The app works the same, but CSS classes and DOM structures have shifted, and the tests never exercised real user interactions.
Selectors such as div.btn-primary-new-style or nth-child(3) lock the test to a particular construction of the UI, not to what the user experiences. When the construction changes, the test breaks, and every minute spent hunting selectors is a minute not spent on valuable coverage. Simply picking a different selector does not solve the root issue.
The solution is to write tests at an abstraction level that stays constant even when the implementation evolves. The following patterns help you build a suite that survives design-system migrations, component-library upgrades, and other UI refactors.
Understanding why tests break during refactors
When a refactor leaves the application behavior unchanged but causes tests to fail, the problem is not merely a selector choice; it is a design flaw. Two distinct concerns are at play: the locator strategy you employ and the abstraction layer that organizes interaction logic across the suite. Identifying which type of failure you are facing is the first step toward a lasting fix. Many engineers treat each failure as an isolated incident and apply a quick fix, only to see the same pattern reappear because the underlying cause remains.
Google reports that about 84 % of pass-to-fail transitions in their test infrastructure are due to flaky tests. Flakiness adds randomness, but it is only one failure category. Tests that are coupled to implementation details add another cost layer: they fail consistently after UI-structure updates, masquerading as product bugs while actually stemming from selector design.
Most of these failures arise because the tests are watching the wrong things. Below are the five most common coupling patterns that make Playwright suites brittle during refactors, each with a recognizable failure signature and an associated cost.
Selector coupling to visual structure
Structural selectors capture the DOM hierarchy at a specific moment. A selector like div > section > form > input describes how the markup was arranged when the test was authored, not what the user sees or does.
Refactors often rearrange that hierarchy – forms may move into modals, new layout containers can be added, or child components may be extracted for reuse. The underlying behavior stays the same, but the selector no longer matches the new structure, causing the test to fail even though the product works.
Because the DOM changes frequently, tests that depend on its exact structure are prone to breakage. What remains stable are the attributes that users interact with: ARIA roles, labels, and accessible names. These convey purpose rather than position.
Selector coupling to styling artifacts
CSS class names generated by component libraries are build-time artifacts, such as .MuiButton-containedPrimary, .css-1x2y3z, or .buttona3f2k_1. They are not stable identifiers. When a library version is upgraded or the build configuration changes, the class names can be completely rewritten while the UI looks identical.
Tests that rely on these auto-generated classes or on XPath expressions tied to a specific DOM layout break whenever developers refactor the UI. In codebases that heavily use component libraries, the breakage threshold is low. For example, upgrading Material-UI from v4 to v5 replaced stable class names with hashed ones. Changing a CSS-Modules configuration rotates the hash suffix. In both scenarios the interface remains unchanged for the user, but the selectors lose their targets.
During a Tailwind migration, the issue becomes more pronounced: a conversion from CSS-in-JS may replace a single class with dozens of utility classes. Any test that selects by class will fail, even though the component’s behavior is unchanged.
Coupling to component internals
Some tests reach inside component internals – using IDs generated by the library, assuming a particular HTML element type, or writing XPath expressions that target a fixed path inside a component.
For instance, a test that looks for input[type=text] will break if a component library swaps the native input for a custom element. This pattern appears often when teams adopt headless UI libraries or design systems that enhance accessibility. Users still see the same behavior, but the underlying markup changes, causing the test to fail.
Component libraries frequently add wrapper nodes for layout or accessibility, breaking deeply chained selectors. Playwright’s locators automatically pierce open shadow DOM, so semantic locators like getByRole and getByText work inside shadow roots without extra configuration. Fragility arises when XPath is used inside shadow DOM (XPath does not cross shadow boundaries) or when targeting closed-mode shadow roots, which Playwright does not support. Semantic locators remain stable across shadow-DOM boundaries; structural ones do not.
The most damaging scenario is in authentication flows, where engineers rely on internal identifiers for password fields, OTP inputs, or modal containers because the component library does not expose clean semantic attributes. When the design system changes, these tests break even though authentication continues to work.
Implicit coupling via position and order
Index-based selectors and :nth-child expressions assume elements appear in a fixed order. Adding a navigation item above an existing one shifts every subsequent index. Reordering a form field for UX reasons breaks any test that targets the third field by position, and adding columns to a data table invalidates selectors tied to column indices. The application’s behavior is unchanged, yet the tests fail.
Avoiding positional selectors like nth(3) is a well-known best practice. Beyond fragility, these selectors provide little diagnostic value: a failure only tells you that the position changed, not what behavior was being verified.
Text content coupling
Tests that select by exact text tie themselves to copy decisions. A copy edit, an i18n migration, or a CMS update can break the selector even though the application still works.
Text selectors are not inherently bad. Playwright’s getByText() is a first-class locator that mirrors how users interact with visible text. When the text is part of the user-facing contract – headings, legal notices, status messages – asserting on it is appropriate.
Problems arise when text is used as a stable identifier for elements whose copy is expected to evolve. In such cases the test no longer validates behavior but mirrors an implementation detail that changes independently of functionality. Text-based tests break when new locales are added; the application remains correct across languages, but the selectors no longer match.
Partial text matching improves resilience but does not eliminate coupling. A test using getByText(/sign in/i) survives capitalization changes but still fails if the product team renames the action to “Log in.”
A survey of 335 professional developers and testers found that the primary cost of unreliable tests is not computational overhead but a gradual loss of confidence in test results. Text-based selectors accelerate this problem by generating failures that engineers learn to ignore. Over time, real regressions become harder to spot.
The selector hierarchy: what to use and when
Not all selectors age equally. Some survive a design-system migration untouched, while others break the moment a utility class is renamed or a component library is upgraded. The difference lies in what each selector is anchored to.
User-facing attributes and explicit contracts produce more stable tests because they tie directly to what the application intentionally exposes. This creates a clear hierarchy; where a selector sits determines whether the suite needs constant maintenance or largely remains stable.
Tier 1: ARIA role and accessible name
page.getByRole('button', { name: 'Add to cart' }) sits at the top of the hierarchy because it queries based on semantic role and accessible name, not on DOM structure. Role-based selectors survive layout changes and class updates because well-designed systems preserve semantic roles by default. Converting a <div role="button"> to a native <button> does not break the selector, nor does a Tailwind migration that rewrites every class.
A secondary benefit is that when a component breaks getByRole, it also violates its accessibility contract, turning the locator into an implicit accessibility check.
For dynamic accessible names – order numbers, user-specific text – regular-expression matchers work cleanly, e.g., getByRole('heading', { name: /order #\d+/i }).
Tier 2: Label and placeholder
page.getByLabel('Email address') binds to the form-label association using for/id, aria-labelledby, or aria-label. Label-based locators stay stable across input-type changes, component-library upgrades, and layout refactors as long as the label text and its association remain.
getByPlaceholder can serve as a fallback for unlabeled inputs, but placeholder text changes frequently for UX reasons and carries less semantic weight than a label.
Tier 3: Explicit test attributes
Attributes such as data-testid, data-cy, or data-test create a clear contract between the application and the test suite. They exist solely for testing and remain stable through visual and structural refactors. Playwright offers first-class support via page.getByTestId(). The attribute name can be configured in playwright.config.ts using use.testIdAttribute to match your team’s convention.
When used selectively on meaningful elements, data-testid provides a net benefit. It introduces a stable contract without coupling tests to implementation details. The trade-off is the presence of test-specific markup in production HTML. This can be mitigated with tools like babel-plugin-react-remove-properties, which strip data-testid attributes at build time. Consistency requires enforcement – custom ESLint rules or CI checks that verify the attribute’s presence on critical components prevent inconsistency.
Tier 4: Text content (with caveats)
page.getByText() belongs at the bottom of the hierarchy and should be reserved for content that lacks a semantic role, label, or test attribute. Using a regex such as /submit order/i handles case variations without demanding an exact string.
Because getByText() is sensitive to copy changes, i18n migrations, or CMS-driven updates can break the locator even when the application behaves the same. Repeated failures in this tier often signal a missing data-testid rather than a feature problem.
What never to use
CSS classes generated by component libraries – e.g., .MuiButton-containedPrimary or .css-1x2y3z – reflect build output, not user-facing behavior. They change frequently during design-system updates and are unreliable selectors.
Deeply chained CSS selectors are equally fragile; a small layout tweak or an extra wrapper can break the entire path without affecting the feature.
XPath with positional predicates, :nth-child without filtering, and dynamically generated id attributes pose the same risk. They depend on structure and ordering that do not stay stable, leading to failures that reveal more about the selector than the application.
Scoping and chaining locators
A good selector strategy finds the right element; a good scoping strategy keeps it there as the page evolves. The two are related but distinct, and solving only one leaves a common failure unaddressed.
Problems arise when a page contains multiple elements that match the same locator. For example, two “Confirm” buttons – one in a form, one in a modal – become ambiguous if the test does not narrow the scope. Playwright enforces strict mode by default, throwing an error when an action matches more than one element. This is not merely a best-practice recommendation; it is a framework constraint.
A common workaround is using an index such as .nth(0) or .nth(1). This relies on position and breaks as soon as the layout changes. The more reliable approach is semantic scoping.
Container scoping
page.getByRole('dialog').getByRole('button', { name: 'Confirm' }) anchors the locator to a semantic container, keeping the test focused on what the user sees rather than how the DOM is arranged.
Locators should reflect how a user navigates the interface, not a CSS path through the DOM. “In the confirmation dialog, click the Confirm button” remains stable through layout refactors, while “the third button in the second div inside the modal wrapper” depends on a structure that shifts with any layout change.
Filtering locators
locator.filter({ hasText: /.../ }) and locator.filter({ has: page.getByRole(...) }) solve the problem of multiple matches by narrowing the result set based on content or child elements rather than position.
For example, page.getByRole('row').filter({ has: page.getByText('Order #12345') }) targets the correct row by its content, not its position, staying accurate when data is reordered or generated dynamically. Index-based row selection would break in both cases.
Avoiding locator chains that re-encode structure
Chaining selectors through the DOM hierarchy does not add stability; it merely moves the structural coupling deeper into the chain where it is harder to spot.
page.locator('.container').locator('.form').locator('.input') is still a structural selector, just split across three lines. It adds no stability over a single selector and only hides the coupling.
Each step in a chain should narrow the target semantically, such as scoping from a named dialog to a labeled button. Moving from a wrapper class to a child class to a grand-child class merely mirrors the layout, which changes frequently. The semantic approach holds up when the UI changes; the structural chain does not.
Page-object design for refactor resilience
Centralizing selectors and interactions into a dedicated abstraction layer – whether page objects, app actions, or domain helpers – keeps changes contained and prevents failures from propagating across the suite.
Selectors alone do not guarantee stability. You can have role-based locators, semantic scoping, and data-testid attributes, yet still see failures across many files when a single component changes. The root cause is how tests are organized.
Playwright’s documentation increasingly highlights the app-actions pattern as an alternative to classic page objects: instead of wrapping a page in a class, you attach high-level helper functions directly to Playwright fixtures. App actions work well for cross-cutting flows that do not map cleanly to a single page, while page objects remain natural for modeling a specific UI surface with its own set of interactions. In both cases the principle is the same – keep interaction logic out of individual tests.
When selectors are scattered throughout tests, even a minor UI change can trigger updates in many files. Centralizing them in a dedicated layer contains those changes.
Centralizing selectors in page objects
Page objects group selectors in one place and make them reusable. The concept is simple, but real-world codebases often stumble. A common failure is duplication: the same getByRole('button', { name: 'Sign in' }) call appears across many test files. When the product team renames the action to “Log in,” the functionality stays the same, but dozens of tests fail simultaneously. Fixing each occurrence creates a wave of merge conflicts.
A page object should describe what a user can do and observe, while keeping implementation details out of the tests. Tests call methods, not raw locators. The selector lives once – in the page object – so only that file needs updating when the UI changes.
Page objects that expose behavior, not selectors
A page-object property that returns a locator, such as get addToCartButton(), is only a small step up from placing the selector directly in the test. The test still depends on how the UI is built.
A method like addItemToCart(sku: string) expresses the user’s intent. Locators and interaction details stay inside the page object, so when the UI changes – say a confirmation modal appears after a design-system update – the change is handled inside the page object. Tests continue to call the same method without modification.
Component-level page objects for design-system migrations
Page-level objects work well for stable applications, but design-system upgrades demand finer granularity. Building reusable page objects around user behavior rather than UI structure keeps test suites stable as the application evolves.
For example, a DatePickerComponent page object encapsulates every interaction with a date picker, regardless of where it appears. When the design system upgrades the component, only the DatePickerComponent needs updating. This shifts maintenance from the test suite to the component-object library, which is maintained by the team closest to the change.
Each component-level page object you create is a file you no longer have to touch during the next upgrade.
Coordinating with frontend teams
Test resilience is not the sole responsibility of a single team. When a component pull request changes internal structure without checking test dependencies, failures follow. Poor communication between developers and testers remains a common source of quality issues. Solving it requires changes in collaboration practices, not just more discussion.
Data-testid as a shared contract
Treating data-testid as part of a component’s public API changes its role from an informal convention to a documented expectation. When a component ships with data-testid="checkout-submit", that attribute becomes part of its interface and should be reviewed in every PR. Renaming or removing it without considering the test suite introduces avoidable breakage.
Consistency comes from enforcement. A custom ESLint rule or a CI check that validates the presence of the attribute on critical components turns the expectation into a reliable contract. Without discipline, test maintenance can dominate development time.
Pre-refactor test audits
Before a large UI refactor begins, centralized selectors in page objects let you quickly trace where components are used across the suite. If forty tests depend on a date picker’s internal structure, that number should inform the refactor plan.
Skipping the audit often leads to reactive debugging after CI failures. Conducting the audit first lets you introduce data-testid attributes on critical components, sequence changes to limit disruption, and maintain coverage throughout the transition. The audit replaces reactive firefighting with planned, controlled changes.
Playwright component testing as a complement
@playwright/experimental-ct-react mounts individual React components in a real browser using the same Playwright API as the integration suite. A DatePicker component can be tested in isolation before it appears in any user flow. When a design-system upgrade introduces a new rendering pattern, the component suite catches regressions early, before they reach integration tests.
The experimental label matters: the API continues to evolve, setup requires extra Vite configuration, and there are limitations around passing complex Node.js objects to the browser context. It works best alongside integration tests. Component tests focus on element behavior in isolation; integration tests cover full user journeys that cross routing and API boundaries. During a design-system migration, component tests provide faster feedback, reducing the cost of each upgrade.
Validating resilience: confirming your tests are truly decoupled
After a UI refactor, a green CI run can be misleading because tests may pass without actually monitoring the changes. Verifying that the suite truly responds to updates requires deliberate checks, not assumptions.
Selector resilience audit
Before running the suite, perform a code-wide search for page.locator('.') or other CSS-class selectors in your test files. This quickly surfaces selectors that are tied to styling artifacts.
By adopting semantic locators, centralizing selector logic, and collaborating closely with frontend developers, you can build a Playwright test suite that endures design-system migrations, component-library upgrades, and other UI refactors without constant maintenance overhead.