Stop Repeating Playwright Locators: Build Custom Locator Functions Like an Enterprise SDET

Introduction

As your Playwright automation framework grows, you'll quickly notice a common problem—locator code starts appearing everywhere. Consider these examples:

The problem isn't that these locators are wrong—they're actually good locators. The problem is that you're repeating the same locator-building logic hundreds of times throughout your framework.

Large enterprise automation frameworks solve this by creating custom locator wrapper functions. Instead of writing Playwright locators directly in every Page Object or test, they build reusable helper methods that make tests shorter, cleaner, easier to maintain, and more consistent.

In this tutorial, you'll learn how to design reusable locator wrapper functions, understand why enterprise teams use them, and build your own locator utility library.

Why Wrapper Functions?

Imagine your application has over 500 test cases, 120 Page Objects, and 3,000 locators. If your team decides to change its locator strategy—for example, moving from getByRole() to getByTestId()—you may need to update hundreds of files. With wrapper functions, you change the implementation in one place.

The Traditional Approach

Most beginners write code like this:

Nothing is technically wrong with it. However, imagine doing this thousands of times across a large framework.

Creating Your First Wrapper

Create a new file at utils/locatorHelper.ts:

Now your test becomes:

Much cleaner.

Wrapping Textboxes

Usage:

Notice how your tests now read almost like English.

Wrapping Links

Usage:

Wrapping Checkboxes

Usage:

Wrapping Dropdowns

Usage:

Wrapping Test IDs

Many enterprise applications standardize on data-testid.

Usage:

Creating a Base Locator Class

Instead of exporting dozens of standalone functions, many teams create a reusable class.

Usage:

This pattern centralizes locator creation and keeps Page Objects concise.

Using Wrapper Functions in a Page Object

Now your Page Object focuses on business actions instead of locator details.

Adding Logging

Wrapper functions are also a great place to add logging.

Every locator lookup is now automatically logged without changing any test code.

Adding Automatic Waiting

You can extend wrapper functions to wait for visibility before returning or interacting with elements. For example:

This keeps synchronization logic consistent across the framework.

Supporting Multiple Locator Strategies

Suppose your team decides to switch to data-testid. Instead of updating hundreds of Page Objects, you only modify the helper:

Every test continues to work without changes.

Advantages

Using custom locator wrappers provides:

• Cleaner code
• Reusable locator logic
• Centralized maintenance
• Consistent naming conventions
• Easier debugging
• Better logging
• Faster framework evolution
• Simpler onboarding for new team members

These are some of the reasons enterprise automation frameworks remain maintainable as they grow.

Best Practices

• Keep wrapper methods focused on a single responsibility.
• Return Locator objects so callers can choose the action (click, fill, check, etc.).
• Avoid hiding too much Playwright functionality—wrappers should simplify, not limit.
• Use descriptive method names such as button(), textbox(), and link().
• Document the preferred locator strategy so the whole team follows the same pattern.
• Combine wrapper functions with the Page Object Model for maximum maintainability.

Common Mistakes

• Creating wrappers that duplicate every Playwright API without adding value.
• Embedding business logic inside locator helpers.
• Returning ElementHandle instead of Locator.
• Mixing multiple locator strategies inconsistently across the framework.
• Making wrapper methods too generic to understand.

When Not to Wrap

Wrapper functions are a tool, not a religion. Applied without judgement, they produce a second framework that everyone has to learn on top of Playwright, and that is a worse outcome than a few repeated locator calls.

• Do not wrap a Playwright method one-to-one if the wrapper adds nothing but a new name.
• Do not wrap page-specific, one-off locators; those belong in the Page Object that owns them.
• Do not hide assertions inside locator helpers — a function called button() should never also click and verify.
• Do not create wrappers that accept ten optional parameters to cover every case; write two clear helpers instead.

A good rule of thumb: a wrapper earns its place when it is used in at least three different Page Objects, or when it encodes a project-wide convention such as a test-id naming scheme. Everything else is premature abstraction, and premature abstraction in a test framework is just as expensive as it is in production code.

Building a Testability Contract

Custom locator helpers are far more powerful when the application under test cooperates. Rather than writing increasingly clever CSS to reach fragile elements, agree on a testability contract with the development team and encode that contract in your helper layer.

The contract usually has three parts. First, every interactive element exposes a stable attribute — commonly data-testid — that is never changed for styling reasons. Second, the naming follows a predictable pattern such as area-component-action, for example checkout-submit-button. Third, dynamic lists expose an identifier on each row so tests can target a specific record instead of an index position.

Once that contract exists, a single helper can construct locators from semantic arguments. A method like testId('checkout', 'submit', 'button') centralises the naming rule, so if the team ever changes the attribute or the separator, you update one function instead of thousands of test lines. That is the real return on investment of a locator helper layer: it converts a global refactor into a local one.

Prefer Role-Based Locators First

Even with a testability contract in place, prefer Playwright's role-based locators wherever the accessible name is stable. Role locators fail when the application becomes inaccessible, which means your tests double as a lightweight accessibility check. Fall back to test ids for elements with no meaningful accessible name, such as icon-only controls and layout containers.

Migrating an Existing Suite

Most teams adopt locator helpers on a codebase that already has hundreds of tests. A big-bang rewrite is risky and rarely gets finished, so migrate incrementally instead.

• Introduce the helper module first and use it only in new tests, so the pattern proves itself on low-risk work.
• When a test fails because of a locator change, migrate that file as part of the fix rather than patching the old selector.
• Pick the two or three most-edited Page Objects and convert them deliberately; they generate the most maintenance value.
• Add a lint rule or code review checklist item that flags raw page.locator() calls in new Page Objects.
• Track progress with a simple grep count in CI so the migration stays visible instead of stalling silently.

Expect the migration to surface duplicate Page Objects, dead tests, and selectors that never matched anything. That cleanup is part of the value. Teams that follow this incremental path typically report a large drop in the time it takes to fix a UI refactor, because a change to the markup now touches one helper rather than scattered selector strings.

Frequently Asked Questions

Should wrappers return Locator or perform actions?

Return a Locator. Returning the locator keeps Playwright's full API, auto-waiting, and assertion support available to the caller, and it prevents your helper layer from silently reimplementing behaviour Playwright already provides.

Where should the helper file live?

In a shared utilities or core folder alongside the base page, imported by Page Objects. Test files should generally use Page Objects rather than reaching for locator helpers directly.

Do wrappers slow down execution?

No. Building a Locator is a lazy, in-memory operation; nothing touches the browser until the locator is used. The overhead of a function call is irrelevant next to network and rendering time.

How do wrappers interact with the Page Object Model?

They sit underneath it. Page Objects describe what a screen contains and what a user can do there; locator helpers describe how any element is found. Keeping those responsibilities separate is what makes both layers easy to change.

Conclusion

Custom locator wrapper functions are a simple idea with a significant impact. They reduce repetition, enforce consistency, and make it much easier to evolve your automation framework over time. Whether you're building a small test suite or an enterprise framework with thousands of tests, centralizing locator creation pays off in maintainability and readability.

The key is to keep your wrappers lightweight and let Playwright's powerful Locator API do the heavy lifting. When combined with the Page Object Model and good framework design, custom locator helpers become an important building block of a professional Playwright automation framework.