Forem: zhilin yang

Stop Treating Locators as Strings: A More Resilient Locator Strategy in Playwright

zhilin yang — Thu, 19 Mar 2026 07:01:43 +0000

Most flaky UI tests do not fail because the business flow is complicated.

They fail because the locator strategy is fragile.

At the beginning, locator code usually feels easy. You inspect the page, copy a selector, maybe tweak a bit of XPath or CSS, and the test passes. For a while, that feels good enough.

Then the UI changes.

A designer wraps a button in another container.
A frontend refactor renames a class.
A modal introduces a second “Confirm” button.
A list gets reordered and nth(1) clicks the wrong row.

Now the test still looks “correct,” but it is no longer pointing at the thing you meant.

That is the real problem.

The issue is not whether XPath is better than CSS, or whether text selectors are more readable than test IDs. The issue is that many test suites still treat a locator as a single string, when in practice it should be treated as a decision: a structured, ordered strategy for finding the intended element in a changing UI.

That is what this post is about.

I want to show a practical way to move from one-off selectors to a layered locator contract in Playwright: a small abstraction that captures how an element should be found, in what order, with what fallbacks, and under what scope.

Why “just write a selector” stops working at scale

Playwright’s locator model is built around resilience. Locators are the core of Playwright’s auto-waiting and retryability, and the docs recommend using built-in locators such as getByRole, getByLabel, getByText, getByPlaceholder, getByAltText, getByTitle, and getByTestId rather than jumping straight to CSS or XPath. The best-practices guide also explicitly recommends testing user-visible behavior instead of implementation details.

That recommendation reflects a deeper idea:

You usually do not want to find “the second button under this div.”
You want to find “the Submit Order button inside the Order Confirmation dialog.”

Those are not the same thing.

The first description is tied to implementation details.
The second is tied to user-facing meaning.

The more your locator depends on DOM structure, index, or styling, the more likely it is to break when the UI evolves. The more your locator reflects what the user actually sees and interacts with, the more likely it is to survive refactors. Playwright’s documentation makes that tradeoff pretty explicit, especially in its guidance around user-visible locators and its caution around CSS-based selectors and other implementation-coupled approaches.

A locator should be a contract, not a string

The shift I find most useful is this:

A locator is not a selector string.
A locator is a contract.

By “contract”, I mean a small piece of structured data that answers four questions:

What is this element, in business terms?
What scope does it live in?
What is the preferred way to locate it?
If that fails, how should the strategy degrade?

This changes the mental model completely.

Instead of storing a single answer, you store the reasoning behind the answer.

That matters because resilient UI automation is rarely about finding one perfect selector. It is about choosing the most meaningful locator first, then degrading in a controlled way only when necessary.

Playwright already points us toward a priority order

Playwright’s locator APIs are not all equal.

The docs recommend getByRole() as the primary way to locate interactive elements through explicit and implicit accessibility attributes, and the examples consistently pair role with accessible name. They also recommend getByLabel() for form controls, getByPlaceholder() for inputs, getByAltText() for images, getByTitle() where appropriate, and getByText() for visible text. At the same time, the “other locators” guide explicitly warns that CSS selectors are more tightly coupled to implementation details and can break when the page changes.

That suggests a real ordering principle.

A good locator strategy should prefer:

user-facing semantics over DOM structure
uniqueness over ambiguity
stable meaning over transient layout
explicit scope over global guessing
controlled fallback over accidental matching

Once you see locators through that lens, the usual “XPath vs CSS vs text” debate becomes much less interesting.

A practical five-level locator strategy

Here is the hierarchy I use in Playwright.

It is not arbitrary. It follows the same logic Playwright’s own guidance points toward.

Level 1: Role-based, user-facing semantics

This is the highest-confidence layer.

Use getByRole() with an accessible name whenever possible, and narrow the scope if the page has more than one matching area.

await page.getByRole('button', { name: 'Submit Order' }).click();

Or inside a dialog:

await page
  .getByRole('dialog', { name: 'Order Confirmation' })
  .getByRole('button', { name: 'Submit Order' })
  .click();

This is usually the most resilient form of locator because it expresses what the element is and what it is called from the user’s perspective. That is exactly the style Playwright recommends for many common interactions.

Level 2: Explicit control semantics

When role/name is not the best fit, the next layer is element-specific semantics:

getByLabel()
getByPlaceholder()
getByTitle()
getByAltText()

These APIs map well to form fields, labeled controls, images, and descriptive attributes.

await page.getByLabel('Departure City').fill('Shanghai');
await page.getByPlaceholder('Enter your phone number').fill('13800000000');
await page.getByTitle('Close').click();

Playwright explicitly recommends these built-in locators for those cases.

Level 3: Visible text

Text is useful, but it is not always strong enough on its own.

await page.getByText('Payment Successful').click();

That can be fine for non-interactive content, banners, headings, or result messages. But for interactive controls such as buttons and links, text alone is often too weak because it lacks type information and is frequently duplicated.

This is why getByText() belongs below role-based and label-based strategies in a resilient hierarchy, even though it is still much better than raw DOM selectors in many cases. Playwright includes getByText() among its recommended locators, but its broader testing philosophy still favors user-visible meaning and interaction semantics over implementation detail.

Level 4: Scoped and relative locators

When a page contains repeated labels or repeated controls, you often need to add context.

This is where chaining and filtering become powerful. Playwright supports narrowing locators with filter({ hasText }) and filter({ has }), which is especially useful for lists, cards, repeated groups, and local regions of the page.

For example:

const row = page
  .getByRole('listitem')
  .filter({ hasText: 'MU5137' });

await row.getByRole('button', { name: 'Book' }).click();

Or:

const dialog = page.getByRole('dialog', { name: 'Payment Confirmation' });
await dialog.getByRole('button', { name: 'Confirm Payment' }).click();

This layer is still semantic, but it begins to rely on structural relationships between parent and child elements. That makes it slightly less stable than the first three layers, but still far better than a long XPath tied to the current DOM shape.

Level 5: Implementation-detail fallback

Only at the bottom should you fall back to:

CSS selectors
XPath
nth(), first(), last()

Examples:

await page.locator('.dialog-footer .primary-btn').click();
await page.locator('//div[@class="dialog-footer"]//button[2]').click();
await page.getByRole('button').nth(1).click();

Playwright’s docs are quite clear here: CSS selectors tied to implementation details are more brittle, and index-based disambiguation like nth() is risky because the page can change while the selector still technically matches something.

That does not mean you must never use these approaches. It means they should be treated as explicit fallback, not the primary expression of intent.

Where does `getByTestId()` fit?

getByTestId() deserves special treatment.

It does not fit neatly into the same ladder because it is not really “user-facing semantics,” but it is often one of the most stable locator mechanisms in real-world test suites. Playwright includes it among its recommended built-in locators, and it supports custom test ID attributes as well.

In practice, I treat test IDs as a parallel primary channel.

That means a robust locator contract can have two top-level strategies:

a semantic primary path, based on role, label, or text
an execution primary path, based on stable test IDs

This gives you the best of both worlds:

human-readable intent
engineering-grade stability

If your app exposes well-designed test IDs, there is no reason not to use them. Just do not confuse them with user-visible semantics. They serve a different purpose.

Why strict uniqueness matters

A good locator contract should aim for a single intended match.

Playwright’s locator model is intentionally strict in many contexts, and frame locators are strict as well. The docs explicitly note that frame locators throw if more than one frame matches, unless you narrow the selection yourself. That is not a limitation — it is a feature. It pushes your test code toward precision.

The important takeaway is this:

A resilient locator should not merely “find something.”
It should find the one thing you actually meant.

That is why scope comes before fallback, and why relative matching should be explicit instead of accidental.

From idea to code: a `LocatorContract` in TypeScript

Here is a practical implementation in Playwright and TypeScript.

Step 1: define the contract shape

// locator-contract.ts
import { expect, Page, Locator, FrameLocator } from '@playwright/test';

type Root = Page | Locator | FrameLocator;

type ScopeDef =
  | { kind: 'role'; role: string; name?: string | RegExp }
  | { kind: 'testId'; value: string }
  | { kind: 'css'; value: string };

type StrategyDef =
  | { level: 1; kind: 'role'; role: string; name: string | RegExp }
  | { level: 1; kind: 'testId'; value: string }
  | { level: 2; kind: 'label'; value: string | RegExp }
  | { level: 2; kind: 'placeholder'; value: string | RegExp }
  | { level: 2; kind: 'title'; value: string | RegExp }
  | { level: 2; kind: 'alt'; value: string | RegExp }
  | { level: 3; kind: 'text'; value: string | RegExp; exact?: boolean }
  | {
      level: 4;
      kind: 'scopedRole';
      containerRole: string;
      containerName?: string | RegExp;
      targetRole: string;
      targetName: string | RegExp;
    }
  | { level: 5; kind: 'css'; value: string }
  | { level: 5; kind: 'xpath'; value: string };

export interface LocatorContract {
  name: string;
  frame?: string;
  scope?: ScopeDef[];
  strategies: StrategyDef[];
}

The important part is not the syntax. It is the shape of the idea:

scope is modeled explicitly
locator strategies are layered
fallback is part of the design, not an afterthought

Step 2: resolve the contract into a Playwright locator

// locator-contract.ts
function applyScope(root: Root, scope: ScopeDef): Root {
  switch (scope.kind) {
    case 'role':
      return root.getByRole(scope.role as any, scope.name ? { name: scope.name } : {});
    case 'testId':
      return root.getByTestId(scope.value);
    case 'css':
      return root.locator(scope.value);
  }
}

function buildCandidate(root: Root, strategy: StrategyDef): Locator {
  switch (strategy.kind) {
    case 'role':
      return root.getByRole(strategy.role as any, { name: strategy.name });

    case 'testId':
      return root.getByTestId(strategy.value);

    case 'label':
      return root.getByLabel(strategy.value);

    case 'placeholder':
      return root.getByPlaceholder(strategy.value);

    case 'title':
      return root.getByTitle(strategy.value);

    case 'alt':
      return root.getByAltText(strategy.value);

    case 'text':
      return root.getByText(strategy.value, { exact: strategy.exact ?? false });

    case 'scopedRole': {
      const container = root.getByRole(
        strategy.containerRole as any,
        strategy.containerName ? { name: strategy.containerName } : {}
      );
      return container.getByRole(strategy.targetRole as any, { name: strategy.targetName });
    }

    case 'css':
      return root.locator(strategy.value);

    case 'xpath':
      return root.locator(`xpath=${strategy.value}`);
  }
}

export async function resolveLocator(
  page: Page,
  contract: LocatorContract
): Promise<Locator> {
  let root: Root = page;

  if (contract.frame) {
    root = page.locator(contract.frame).contentFrame();
  }

  for (const scope of contract.scope ?? []) {
    root = applyScope(root, scope);
  }

  const ordered = [...contract.strategies].sort((a, b) => a.level - b.level);

  for (const strategy of ordered) {
    const candidate = buildCandidate(root, strategy);
    const count = await candidate.count();

    if (count === 1) {
      await expect(candidate).toBeVisible();
      return candidate;
    }
  }

  throw new Error(`No unique locator matched contract: ${contract.name}`);
}

This resolver does three things in order:

narrow to the right frame if needed
narrow to the correct scope
try strategies from highest confidence to lowest confidence

That sequencing matters.

You do not want fallback to compensate for missing context.
You want context first, fallback second.

A concrete example

Suppose you want to target the Submit Order button inside an Order Confirmation dialog.

Define the contract

// contracts.ts
import type { LocatorContract } from './locator-contract';

export const submitOrderButtonContract: LocatorContract = {
  name: 'Submit Order button',
  scope: [
    { kind: 'role', role: 'dialog', name: 'Order Confirmation' },
  ],
  strategies: [
    { level: 1, kind: 'role', role: 'button', name: 'Submit Order' },
    { level: 1, kind: 'testId', value: 'submit-order' },
    { level: 2, kind: 'title', value: 'Submit Order' },
    { level: 3, kind: 'text', value: 'Submit Order', exact: true },
    {
      level: 4,
      kind: 'scopedRole',
      containerRole: 'group',
      containerName: 'Order Details',
      targetRole: 'button',
      targetName: 'Submit Order',
    },
    { level: 5, kind: 'css', value: '.dialog-footer .primary-btn' },
    { level: 5, kind: 'xpath', value: '//div[contains(@class,"dialog-footer")]//button[last()]' },
  ],
};

Use it in a test

// order-confirm.spec.ts
import { test, expect } from '@playwright/test';
import { resolveLocator } from './locator-contract';
import { submitOrderButtonContract } from './contracts';

test('submit order', async ({ page }) => {
  await page.goto('https://example.com/order/confirm');

  const submitButton = await resolveLocator(page, submitOrderButtonContract);
  await submitButton.click();

  await expect(page.getByText('Order submitted successfully')).toBeVisible();
});

The test reads like a business action.
The contract captures the locator logic.
Those two concerns are now separated.

That separation is where a lot of maintainability comes from.

Why this is better than “a really good XPath”

Because XPath only answers one narrow question:

How do I select it right now?

A locator contract answers a more useful set of questions:

What is this element supposed to represent?
What is the strongest semantic signal available?
What context should narrow the search?
How should the strategy degrade if the preferred path is unavailable?
Which fallback is acceptable, and which one is just emergency-only?

In other words, you are no longer encoding a selector.
You are encoding intent.

That is the difference between test code that survives UI evolution and test code that constantly needs patching.

Treat locator contracts as test assets

Once you adopt this pattern, do not leave the contracts scattered across spec files.

Treat them as a first-class layer in your test codebase.

A practical structure might look like this:

page-level contract modules
one named contract per important control
spec files that consume contracts instead of hand-writing selectors
locator maintenance separated from business-flow maintenance

This naturally creates two layers:

business action layer
What the test is trying to do

locator contract layer
How the intended element should be found, with scope and fallback

That boundary is healthy. It keeps tests readable and keeps locator decisions centralized.

Final thought

The biggest mistake in UI automation is not choosing the wrong selector syntax.

It is treating element location as a one-line implementation detail.

In Playwright, a better model is to treat element location as a structured decision:

prefer user-facing semantics
prefer uniqueness
prefer explicit scope
use test IDs as a strong parallel contract
reserve CSS, XPath, and index-based selection for controlled fallback

Once you make that shift, locator code becomes far less brittle — and much easier to reason about.

The point is not to eliminate fallback.
The point is to make fallback intentional.

That is what a locator contract gives you.

You can find the open-source implementation of the code examples in this article at:
https://github.com/bohewei123/playwright-locator-contract

If you find this project helpful, please give me a star! Thanks :-)

The End of “Agent Babysitting”: Why Context Engineering Is the New Code

zhilin yang — Sat, 14 Feb 2026 15:39:20 +0000

We are currently navigating the “Agent Paradox.” In the early days of AI coding, the experience felt like pure magic—a few lines of natural language yielding a functional script. But as we move into professional, large-scale systems, that magic has devolved into the drudgery of “agent babysitting.” We find ourselves managing a non-deterministic, stochastic intern who constantly loses the thread, hallucinating imports, or drifting from the original architectural intent. We spend more time correcting the agent’s “state-drift” than we would have spent writing the code ourselves.

Oh My OpenCode represents a fundamental shift in this philosophy. Built on the open-source OpenCode ecosystem—a platform trusted by over 650,000 developers—it is not merely another “wrapper.” It is a specialized orchestration layer designed to be the “Linux-after-Windows” moment for AI agents. It replaces the fragile, monolithic chat interface with a production-ready agent harness that understands the distributed cognitive load of a real-world build pipeline.

1. Introduction: The Agent Paradox
2. Multi-Model Orchestration (The “Three Zhuge Liangs” Rule)
3. Context Engineering > Prompt Engineering
4. The “Ultrawork” Magic Word
5. The Marginal Cost of Code Is Approaching Zero
6. Non-Interruption Is the Ultimate Feature
7. Infrastructure Is the Final Frontier
8. Conclusion: The Rise of the “AI Manager”

1. Introduction: The Agent Paradox

We find ourselves managing a non-deterministic, stochastic intern who constantly loses the thread, hallucinating imports, or drifting from the original architectural intent. We spend more time correcting the agent’s “state-drift” than we would have spent writing the code ourselves.

2. Multi-Model Orchestration (The “Three Zhuge Liangs” Rule)

The industry’s fixation on finding a single “God Model” is a dead end. In high-stakes engineering, the ceiling of performance is no longer raw model intelligence but the efficiency of multi-model orchestration.

Oh My OpenCode operates on the principle that specialized roles create leaner, more deterministic contexts. By assigning specific agents to distinct domains, we prevent the “token blow-up” that occurs when a single model tries to hold the entire world-state in its latent space.

In this ecosystem:

Prometheus handles the high-level planning.
Hephaestus—the “Legitimate Craftsman”—focuses on goal-oriented execution with surgical precision.
Oracle provides strategic backups.
The Librarian digests raw documentation.
Explore utilizes AST-Grep for rapid codebase mapping.

“This isn’t a novel idea—three cobblers can outdo Zhuge Liang, and here we have three Zhuge Liangs. The future ceiling is unlikely to come from ever-larger models alone... [but from] multi-model collaboration + context engineering + stable loops. Your agent is now the dev team lead. You’re the AI Manager.”

— Ed Huang, CTO/Co-founder, PingCAP TiDB

3. Context Engineering > Prompt Engineering

The era of “prompt engineering”—the desperate search for magic incantations—is over. The new frontier is Context Engineering: the structural, stable management of the agent’s environment.

As architects, we must move away from stacking prompts and toward managing state. This involves utilizing experimental features like preemptive compaction and DCP (Dynamic Context Partitioning) to ensure the model doesn’t lose its way during long-running sessions.

Effective context engineering requires five essential elements to maintain a stable engineering loop:

Goals: Clearly defined, non-overspecified objectives provided by the human architect.
Plans: Explicit, versioned roadmaps generated by the planner agent (Prometheus).
Boundaries: Strict engineering constraints and linting rules to prevent architectural drift.
Decisions: A persistent log of historical trade-offs and implicit assumptions.
Stable Structures: Intermediate formats and “preemptive compaction” that prevent the model from drifting in high-token-count contexts.

4. The “Ultrawork” Magic Word

The sheer complexity of managing parallel agents and background tasks is abstracted away by a single keyword: ultrawork (or simply ulw). This is the “bouldering” mode of the Oh My OpenCode harness.

opencode --agent sisyphus "Refactor the PostgreSQL protocol layer" --ulw

When you invoke ulw, you are triggering a state of relentless execution. The system leverages the Todo Continuation Enforcer, which prevents the AI from quitting halfway through a task—the most common failure point in standard agents.

It hands the “boulder” to Sisyphus, who utilizes LSP (Language Server Protocol) and AST-Grep for surgical, deterministic refactoring rather than guessing. If you need deeper reflection, the ultrathink command engages higher-order reasoning, ensuring the agent “thinks twice and codes once.”

5. The Marginal Cost of Code Is Approaching Zero

The most chilling realization for any senior engineer is that the marginal cost of high-quality code is collapsing toward zero.

We recently saw a non-trivial engineering feat: the re-implementation of a PostgreSQL-compatible SQL layer (the tipg project) on top of TiKV. This is a task that historically required a dedicated human team two months of intensive labor.

An AI-driven system, burning through millions of tokens in a brute-force intelligence cycle, accomplished the same milestone in a single afternoon. When you can solve architectural problems by burning compute instead of human hours, the nature of professional code-writing shifts from a “craft of lines” to a “craft of context.”

“The marginal cost of writing code is now close to zero. Even for systems as complex as databases, operating systems, or compilers—which, frankly, are not that complex from an AI’s perspective.”

— Ed Huang

6. Non-Interruption Is the Ultimate Feature

The true bottleneck in the modern SDLC is no longer the model; it is the human.

The standard “think → execute → error → wait” cycle is a recipe for cognitive context switching and massive productivity loss. The solution is the ralph-loop, which allows agents to run inside a stable, continuous loop indefinitely.

By reducing the need for “human confirmation” for every trivial file write, Oh My OpenCode returns decision authority, pacing, and trust to the developer. The human is no longer the “next-step commander” but the final reviewer.

This non-interruptive flow allows the engineering rhythm to resemble real development, where the agent autonomously finds and fixes its own errors within the harness.

7. Infrastructure Is the Final Frontier

Currently, the weakest link in the agentic experience is the environment. An agent’s ability to write perfect Rust or Go is useless if it is paralyzed by infrastructure friction.

We are talking about the worst experiences in the current stack:

Setting up sandboxes
Configuring runtime environments
Starting dependent services
Aligning test fixtures

The next evolution of the agentic workflow isn’t “smarter models” but infrastructure abstraction. For agents to evolve into true engineering systems, databases, CI/CD pipelines, and runtime configurations must become first-class contextual objects.

The agent must be able to manipulate the environment as easily as it manipulates a variable in a function.

8. Conclusion: The Rise of the “AI Manager”

We are witnessing the transition of our profession from “Programmer” to “AI Manager.” Your value is no longer stored in your knowledge of syntax or your ability to debug a race condition manually; it is in your ability to construct and maintain long-running, stable contexts.

In this new paradigm, the LLM is just a commodity ingredient. The real differentiator is the “Chef”—the architect who understands how to orchestrate multiple models, manage state-drift, and build a professional system rather than just a prompt.

When the context orchestrators matter more than the underlying models, what specialized “professional system” will you choose to build?