Use Playwright's locator picker without freezing your test run

A locator migration script opens the application, prints “picker active,” and then appears to freeze. Nothing is wrong with the event loop. Playwright is waiting for a person to hover over the rendered page and click the intended element.

That human pause is the purpose of page.pickLocator(), not an inconvenience to hide with retries. The useful workflow keeps the interactive step local, captures the returned locator for review, and sends only a deterministic behavior test to CI.

What happens while the picker is active

Playwright added page.pickLocator() in version 1.59. The documented sequence is short: the page enters locator-picking mode, hovered elements are highlighted, Playwright shows the corresponding locator, and a click ends the mode and resolves the call with a Locator. The method returns a promise because the human decision can take an arbitrary amount of time.

The Page object matters. If a test has opened two tabs and the picker was started on the background tab, staring at the foreground tab will make the process look broken. page.bringToFront() activates the page, so call it just before the picker when several pages may exist.

Headed execution matters for the same reason. A headless browser has no window in which a person can hover and click. A virtual display can make a browser technically headed on a server, but it does not supply the human decision. This is why an X server is not a solution for CI automation.

The returned value is a normal Locator. Its toString() method gives a human-readable representation, and later actions resolve the locator against the current DOM. It is not an ElementHandle and does not permanently bind to the exact node that received the pointer event.

The picker does not write code, choose a file, or know the business assertion. It also does not promise that the generated locator is the best long-term contract. A test ID might be durable, a role and name might better describe user intent, and a locator based on changing copy might be unsuitable. That decision stays with the reviewer.

One more boundary is easy to miss: the click used to choose the element is part of picker mode. Do not assume that it also performs the application's normal click behavior. The documented outcome is selection and a returned Locator. Exercise the returned locator in a separate behavior step if the application action needs to be tested.

Build a local picker that cannot enter CI by accident

A manual picker should announce what it is waiting for, focus the correct page, show the chosen expression, and clean up when the test ends. It should also refuse to run when the CI environment variable is present. That guard catches the most expensive mistake before a worker spends its full timeout waiting for input.

The following manual spec uses Playwright Test fixtures and a normal authenticated setup can be added through the project's existing storageState configuration. Keep the file outside the configured testDir, or give manual tools their own directory that the CI project ignores.

import { expect, test } from '@playwright/test';

test('pick one locator for local review', async ({ page }) => {
  test.skip(Boolean(process.env.CI), 'page.pickLocator() needs a local human');
  test.setTimeout(120_000);

  const targetUrl = process.env.TARGET_URL;
  expect(targetUrl, 'set TARGET_URL to the page you want to inspect').toBeTruthy();

  await page.goto(targetUrl!);
  await page.bringToFront();

  console.log([
    '',
    'Locator picker is active.',
    'Hover over the intended element and click once.',
    'The selected locator will be printed below.',
    '',
  ].join('\n'));

  try {
    const picked = await page.pickLocator();
    console.log(`Selected: ${picked.toString()}`);
    console.log(`Current matches: ${await picked.count()}`);
  } finally {
    await page.cancelPickLocator();
  }
});

Run that spec explicitly, in headed mode, with one worker. An explicit file path prevents the manual tool from becoming part of a broad test command.

TARGET_URL="http://localhost:3000/orders/ORD-1048" \
  npx playwright test tools/pick-locator.manual.spec.ts \
  --headed --workers=1

A finite test timeout is intentional. Disabling timeouts entirely makes an abandoned picker indistinguishable from a hung worker. Two minutes in this sample is a policy input, not a measured recommendation. Choose a limit that fits the local workflow and print it in the instructions.

Do not automatically append the result to a spec file. A terminal line such as Selected: getByRole(...) is a proposal. Copy it into a review, add its scope, and write the product assertion. Automatic source rewriting would convert a pointer location into permanent intent without a human checking either.

Credentials need equal care. If the page requires authentication, use the same local storage-state mechanism that ordinary tests use and keep secrets out of the command line and logs. The picked locator should be safe to print. Session cookies, request headers, and page HTML generally are not.

How to diagnose a picker that never returns

Start with the last message your tool emitted. If “picker active” appears and the browser shows a highlight as the pointer moves, the call is working and waiting for a click. More timeout will not make an unattended job finish.

If no window appears, confirm that the command includes --headed and that a launch configuration is not forcing headless: true. Also check whether the browser closed during fixture teardown. A page-close listener makes that transition visible:

import type { Locator, Page } from '@playwright/test';

export async function pickWithin(page: Page, limitMs: number): Promise<Locator> {
  await page.bringToFront();
  console.log({ event: 'picker-start', url: page.url(), pageClosed: page.isClosed() });

  page.once('close', () => {
    console.error({ event: 'picker-page-closed', url: page.url() });
  });

  const pendingPick = page.pickLocator();
  let timer: ReturnType<typeof setTimeout> | undefined;
  const deadline = new Promise<never>((_, reject) => {
    timer = setTimeout(
      () => reject(new Error(`No element was picked within ${limitMs} ms`)),
      limitMs,
    );
  });

  try {
    const locator = await Promise.race([pendingPick, deadline]);
    console.log({ event: 'picker-complete', locator: locator.toString() });
    return locator;
  } catch (error) {
    await page.cancelPickLocator().catch(() => undefined);
    await pendingPick.catch(() => undefined);
    throw error;
  } finally {
    if (timer) clearTimeout(timer);
  }
}

This wrapper makes the tool's deadline explicit and calls the public cancellation API during error cleanup. It deliberately does not depend on a particular rejection message from the pending pick. The official contract documents cancellation of the mode, not a stable error string for every language binding and page-close race.

If a click occurs but the promise still appears pending, verify which page received it. Log context.pages() with each page's URL and title, then bring the intended one forward. Browser extensions, authentication popups, and application-created tabs can steal focus. Do not start a picker on every page at once; the resulting highlights and pending operations are hard to attribute.

If hovering shows the wrong boundary, inspect overlays. A full-screen loading layer, cookie banner, or transparent element can own the pointer even when the desired control is visible beneath it. The picker is accurately reporting the hit target. Hiding the overlay through test-only JavaScript would select an element a user cannot currently reach. Wait for the legitimate ready state or fix the product layer.

If the test times out before the human can click, look at the reporter's call site. A normal Playwright test timeout governs the whole test, including setup and the picker wait. Raising only an action timeout does not necessarily give the overall test more time. Set a local test timeout around the manual workflow and keep it bounded.

API logging can establish whether navigation, focus, and picker activation happened in the expected order:

DEBUG=pw:api TARGET_URL="http://localhost:3000/settings/profile" \
  npx playwright test tools/pick-locator.manual.spec.ts \
  --headed --workers=1

Read the log as chronology, not as a pass condition. The final line before the pause should align with the picker call. A navigation timeout, closed page, or failed login before that point is a different problem.

Read a picker timeline without guessing from the timeout

Two runs can end with the reporter pointing at page.pickLocator() and the same overall test-timeout message. In one, the picker was healthy and no person selected an element. In the other, authentication and page setup consumed almost the whole test budget, so teardown began shortly after picker mode opened. Raising the picker's local patience would not repair the second run because the enclosing test owns the deadline.

Read three moments: when the test began, when the tool printed picker-start, and when the reporter ended the test. A healthy waiting period begins on the expected URL with pageClosed set to false, leaves enough of the configured test interval for a selection, and shows the picker highlight moving with the pointer. A completed period adds picker-complete with a locator string. If the start message appears only near the overall deadline, the short gap before failure belongs to setup budget exhaustion. The trace or reporter steps before the picker show which navigation, fixture, or assertion spent that interval.

The value pageClosed: false is easy to overread. It describes the Page at the instant the start record was created. It does not prove that the Page remained open, stayed in front, or kept the same URL. A later close event is decisive evidence of teardown or application-driven closure. No close event plus a moving highlight and no completion record describes an active human wait. No highlight in the visible tab, despite a live start record, calls for the page list and foreground-tab check because the picker may be active on another Page.

The URL field can also mislead when it is logged only once. A healthy value is the intended business route both immediately before activation and at selection. A broken value is a sign-in, error, or unrelated popup route. A misleading value is the correct route at picker-start followed by a client-side redirect while the promise is pending. Record the route again on completion or cancellation so the handoff does not attribute a navigation failure to locator picking.

Do not use the generated locator field as evidence that a click exercised the product. Its healthy value only proves that picker mode returned a Locator. The behavior run still needs a separate action and result assertion. Conversely, a missing locator field after cancellation is expected. Treating every absent value as a picker defect turns ordinary operator cancellation into false incident noise.

Turn a picked element into a test that proves intent

Suppose a reviewer clicks a Save button on an order page and the picker returns a role locator. Copying that expression into the suite is not yet a repair. The page has a shipping form, a coupon form, and an order form, each with the same button name.

Find the stable business boundary first. A dialog can be scoped by its accessible name. A row can be scoped by an order ID rendered in the row or by a product-owned test ID. A form can be scoped by its label. Then use the picked locator inside that boundary and assert a state that only the intended action can produce.

import { expect, test } from '@playwright/test';

test('saves shipping details for the selected order', async ({ page }) => {
  await page.goto('/orders/ORD-1048');

  const shipping = page.getByRole('form', { name: 'Shipping address' });
  await shipping.getByLabel('City').fill('Pune');

  const save = shipping.getByRole('button', { name: 'Save' });
  await expect(save).toHaveCount(1);
  await save.click();

  await expect(page.getByRole('status')).toHaveText('Shipping address saved');

  await page.reload();
  await expect(
    page.getByRole('form', { name: 'Shipping address' }).getByLabel('City'),
  ).toHaveValue('Pune');
});

The reload is the decisive check. A generic toast can appear when the wrong form submits, while persisted shipping data identifies the product transition. This is a different responsibility from locator generation.

A second worked case involves a virtualized list. The desired row may not exist in the DOM until it scrolls into view. Starting the picker before the row renders cannot reveal a locator for it. Navigate or scroll through normal user controls first, confirm the record is visible, and then activate the picker. If the row is recycled after scrolling, prefer a locator based on its visible record key rather than an index captured from the viewport.

The eventual test should reproduce that journey:

import { expect, test } from '@playwright/test';

test('opens the audit record selected from a virtualized result set', async ({ page }) => {
  await page.goto('/audit');
  await page.getByRole('searchbox', { name: 'Filter records' }).fill('EVT-9281');

  const row = page.getByRole('row', { name: /EVT-9281/ });
  await expect(row).toBeVisible();
  await row.getByRole('link', { name: 'Open' }).click();

  await expect(page).toHaveURL(/\/audit\/EVT-9281$/);
  await expect(page.getByRole('heading', { name: 'Event EVT-9281' })).toBeVisible();
});

The picked Open link supplied a clue, but the row identity and destination assertions make the test durable. An index such as .nth(7) would bind the test to whichever recycled record occupied that slot.

A third case is a popup. The application opens a printable invoice in another Page, but the picker starts on the opener. Capture the popup through the action that creates it, wait for its content, focus that Page, and invoke the picker there.

import { expect, test } from '@playwright/test';

test('picks a control from the invoice popup', async ({ page }) => {
  test.skip(Boolean(process.env.CI), 'manual locator selection');
  test.setTimeout(120_000);

  await page.goto('/orders/ORD-1048');
  const popupPromise = page.waitForEvent('popup');
  await page.getByRole('link', { name: 'Printable invoice' }).click();
  const invoice = await popupPromise;

  await expect(invoice.getByRole('heading', { name: 'Invoice ORD-1048' })).toBeVisible();
  await invoice.bringToFront();

  try {
    const picked = await invoice.pickLocator();
    console.log(`Invoice locator: ${picked.toString()}`);
  } finally {
    await invoice.cancelPickLocator();
  }
});

Calling pickLocator() on the opener cannot select content owned by a different Page. The URLs and titles in a diagnostic page list reveal this near-miss quickly.

Similar tools solve different problems

Playwright codegen is usually the better entry point when someone wants to record a user journey. It opens a browser and inspector, observes a sequence, and generates actions and assertions for review. page.pickLocator() is narrower: code pauses at a point chosen by your tool and receives one Locator object.

The Inspector available during debugging is another option. It is well suited to stepping through a failed test, editing a locator, and seeing matches. A custom picker is useful when the selection must happen after application-specific setup, when an internal migration tool needs the value in memory, or when a team wraps selection with its own metadata.

locator.normalize() also solves a different problem. It starts with an existing locator and asks Playwright for a best-practice representation of its match. The picker starts with a human pointing at a rendered element. Use normalization when the old selector is known; use picking when the intended visual target is easier to indicate than to describe initially. Both results still need scope and behavior review.

Trace Viewer is evidence after a run, not an interactive source-code editor. It can show the locator, DOM snapshots, network activity, and console entries around a failure. Use it to decide whether a committed locator found the wrong node, whether an overlay blocked it, or whether the application failed after a correct click.

An ordinary DevTools element picker identifies DOM markup and is useful for inspecting styles and attributes. It does not apply Playwright's locator preferences or return a Playwright Locator. Copying a long CSS path from DevTools recreates the structural-selector problem that locator tooling is meant to reduce.

None of these tools repairs an inaccessible control. If an icon-only button has no accessible name, stop and fix the product contract or agree on a test ID. A generated locator that reaches an unnamed SVG path is not a substitute for an operable interface.

What to save from a selection session

The terminal expression is the smallest part of a useful review record. Save the page route, user role, locale, feature flags that affect the area, and the visible business object that contained the target. A selector generated for an administrator on the English desktop layout may tell you little about the support-agent mobile view.

Record the candidate's match count after selection and again after the page is returned to the state where the action will run. The first count proves what the picker saw. The second catches locators that depend on a transient tooltip, open menu, or hover-only label. If the value changes, do not patch it with first(). Identify which temporary state contributed to the locator and decide whether that state belongs in the test.

A concise review note for the shipping example could use this shape. The values below are example fixture data, not timing or reliability measurements:

selection:
  route: "/orders/ORD-1048"
  role: "support-agent"
  locale: "en-IN"
  target: "Save button inside Shipping address form"
  picked: "getByRole('button', { name: 'Save' })"
  matches_on_page: 3
review:
  accepted: "getByRole('form', { name: 'Shipping address' }).getByRole('button', { name: 'Save' })"
  matches_in_scope: 1
  product_proof: "City remains Pune after reload"
  rejected_shortcut: ".first() would select the Coupon form"

This record exposes the judgment that source code alone can hide. The initially picked locator was not bad; it was incomplete because the page had three valid Save buttons. The accepted expression adds a user-visible form boundary, and the reload verifies persistence.

Keep a negative check beside high-risk migrations. If two orders are visible, act on one and assert that the other remains unchanged. If a menu has Edit actions for account and billing settings, open the intended panel and assert the other panel stays closed. Negative evidence is especially valuable when two wrong actions produce the same toast or redirect.

Do not store full HTML or authenticated URLs by default. Page markup can contain customer data, tokens embedded in attributes, and internal identifiers unrelated to locator review. A small, deliberate set of fields is easier to inspect and safer to attach to a ticket. Redact query parameters unless they are the business key being tested.

Treat a changed picker result after a Playwright upgrade as a review signal, not immediate breakage. The committed locator remains ordinary test code and does not regenerate itself. Run the manual tool against a small set of known pages, compare whether the new suggestions express scope better, and migrate only where behavior tests support the change. There is no benefit in churning stable locators to match the newest textual representation.

Close the session after the evidence is captured. An abandoned headed browser can retain authenticated state, hold a local development port open, or leave a picker waiting in a tab someone later mistakes for the application. Let the Playwright fixture perform its normal teardown, and keep cancelPickLocator() in a finally block so both a completed selection and an interrupted one follow the same cleanup path.

For team rollouts, pair one developer who knows the page model with one tester who knows the user journey. The developer can identify volatile markup; the tester can identify the wrong-but-plausible outcome. That short review catches more risk than collecting hundreds of picker outputs and approving them by pattern.

Split ownership when the selected element exposes a product defect. The person running the tool owns the session record and a reproducible route. The test owner owns the final scope and the assertion that proves the user outcome. The frontend feature owner owns missing accessible names, duplicate test IDs, transparent hit targets, and markup that makes identical actions impossible to distinguish. The test-platform owner owns discovery rules that keep interactive calls out of CI and the manual helper's cancellation behavior.

The handoff should contain the Page URL before activation and at exit, user role, locale, relevant feature state, list of open page URLs, start and completion or cancellation records, raw picked expression, accepted scoped expression, match counts in and out of scope, and the expected product result. Include the first trace when navigation or teardown is disputed. Do not attach an authenticated HTML dump. The receiving team needs the smallest evidence that reproduces ownership of the element, not a copy of every customer value on the page.

Keep interactive selection out of the delivery pipeline

Place manual picker files where broad test discovery cannot find them. A dedicated tools/ directory outside testDir is simple. If repository layout requires manual specs under the test tree, exclude a clear suffix such as *.manual.spec.ts from CI configuration and run those files only by explicit local command.

Add a lightweight pipeline check so an interactive call cannot slip into ordinary end-to-end specs. The following workflow also runs the deterministic locator-contract tests that were created from reviewed selections:

name: playwright-locator-contracts
on: [pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - name: Reject interactive picker calls in CI specs
        run: |
          if rg -n "pickLocator\(" tests e2e; then
            echo "Move page.pickLocator() to a local manual tool."
            exit 1
          fi
      - run: npx playwright test tests/locator-contracts --trace=retain-on-failure
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: locator-contract-results
          path: test-results

Adjust the searched paths to the repository. Do not scan the manual tools directory if that is where approved picker code lives.

For an existing suite, inventory interactive call sites before enabling that rejection step. The guard will break first on any exploratory picker left under a discovered test path, even if nobody intended CI to execute it. Move approved manual tools and document their explicit launch command in the same change that introduces the guard. Landing the guard alone creates a red pipeline without giving developers a supported place to work.

Land deterministic outcome assertions next, before changing committed locators. A reviewed selection is safest when the old test already proves which record or form changes. Then convert a small feature whose data and permissions are stable, run its tests without any picker call, and inspect first-attempt failures. Expand only after that batch remains deterministic across the browser projects, roles, locales, and viewport states the feature actually supports.

Success has three observable signals. CI finishes without waiting for human input. Local selection sessions always end with either a completion record or an intentional cancellation record. Converted tests resolve the accepted locator at the action boundary and prove the intended product state without invoking the picker. The number of expressions collected in a workshop is not a rollout metric because unscoped suggestions can accumulate without improving one test.

Manual validation has a concrete maintenance cost. If a control materially differs across three roles and two responsive states, reviewing every combination creates six page states for that control. Six is illustrative here, not a measured recommendation. Localization can multiply the set again. Choose combinations from supported product behavior and risk, then record which ones were omitted. The picker saves the time needed to author an initial expression, but it does not remove the review matrix.

Interactive picking does not catch keyboard-only failures. A person can point at and select a button that never enters the Tab order, loses focus after a dialog opens, or ignores the keyboard activation the product promises. Run separate keyboard and accessibility checks for those behaviors. Pointer selection supplies no evidence about them.

The cost of this separation is an extra handoff. A person selects, copies, scopes, and reviews a locator before CI can verify it. That is slower than committing generated text immediately, but it prevents an unbounded wait and forces the business assertion into source control.

Avoid the picker when the requirement is already expressible with a role, label, placeholder, visible text, or owned test ID. Writing the locator directly is faster and easier to review.

Do not use it for unattended discovery, crawler-style exploration, or selector self-healing during a failed run. Those workflows need deterministic policies and explicit failure handling. A pending human choice is not a recovery strategy.

Skip it when a target exists only under test-only DOM mutation. Select against the product state users receive. Likewise, do not dismiss overlays or bypass permissions merely to expose a convenient element.

Finally, do not keep a picked expression just because it worked once. Locale, permissions, feature flags, responsive layout, and realistic data can reveal ambiguity. The committed test should state which object owns the action and what changed after it. The picker contributes one observation to that design, no more.