docs(cli): clarify generated locator page state

[Devin Rousso (dcrousso)]

generated locators can become ambiguous when page state changes or replays leave duplicate test data

explain how to restore the intended state and handle strict mode violations without hiding ambiguity with .first()

fixes #42790

[github-actions]

Test results for "MCP"

2 failed
❌ [chrome] › mcp/screenshot.spec.ts:142 › browser_take_screenshot (default type should be png) @mcp-ubuntu-latest-chrome
❌ [firefox] › mcp/cli-core.spec.ts:70 › dblclick @mcp-windows-latest-firefox

8690 passed, 1474 skipped

---

Merge workflow run.

[github-actions]

Hi, I'm the Playwright bot and I took a look at the failing CI runs here.

🟢 Both failures are pre-existing noise — this PR is clear

This PR touches one markdown file (references/test-generation.md, a CLI skill reference) and no product code, so neither the MCP screenshot path nor the CLI dblclick path can be reached by the diff. Both failures have independent evidence elsewhere in CI.

Details

Pre-existing flake

• [firefox] › mcp/cli-core.spec.ts:70 › dblclick (mcp-windows-latest-firefox) — a long-running flake specific to that bot: 12 failures out of 705 runs (1.7%), always with the same expect(received).toContain(expected) … Received has value: undefined signature. It has failed on unrelated pushes (shas bae3292f, 7894f565, c874c8a7, 2dec18d7, c8fc3bf8) and on unrelated PRs (chore(video): emit frames with real timestamps, drop frame number quantization #42480, feat(chromium): roll to r1243 #42434, feat(selectors): replace pierceFrames() with frameLocator() #42395, feat(reporter): add chrome://tracing reporter #42354, test(mcp): cover --sandbox at the config resolution level #42339, feat(trace): add action screenshot and aria snapshot events #42167). The same test is green on all 10 other MCP bots — 0 failures in ~7,000 runs.

Infra

• [chrome] › mcp/screenshot.spec.ts:142 › browser_take_screenshot (default type should be png) (mcp-ubuntu-latest-chrome) — the tool returned an error instead of an image:

  Error: browserBackend.callTool: Protocol error (Page.captureScreenshot): Unable to capture screenshot
  

  That's a CDP-level capture failure from the browser, not an assertion about anything this PR changed. The same Unable to capture screenshot error shows up across unrelated tests, bots and shas — page/page-screenshot.spec.ts › should take fullPage screenshots during navigation hit it on 10 distinct shas on tracing-chromium, and mcp/cli-save-as.spec.ts › screenshot --filename hit it on this very same mcp-ubuntu-latest-chrome bot.

  Being honest about the limit: this exact test has failed only this once in 724 runs, so I can't point at a prior failure of this title. The cross-test, cross-sha spread of the identical browser-side error is what I'm leaning on.

Both should go green on a rerun.

_{Triaged by the Playwright bot - agent run}