modify template

plugins/cache/openai-bundled/browser/26.608.12217/docs/playwright.md

@@ -0,0 +1,128 @@
+## Playwright
+
+Playwright is a critical part of the JavaScript API available to you.
+
+You only have access to a limited subset of the Playwright API, so only call functions that are explicitly defined.
+You do have access to `tab.playwright.evaluate(...)`, but only in a read-only page scope.
+Use locators for scoped interactions and targeted checks. For bulk DOM inspection, prefer one bounded read-only `evaluate(...)` that queries and projects the needed data. Avoid loops of locator property calls. In `evaluate(...)`, use basic DOM reads, limit returned elements, and do not assume globals or helpers such as `performance`, `NodeFilter`, `document.createTreeWalker`, or `FormData` exist.
+
+When using Playwright, keep and reuse a recent `tab.playwright.domSnapshot()` when it is available and you need it for locator construction or retry decisions. Treat the latest relevant snapshot as the source of truth for locator construction and retry decisions.
+
+### Snapshot Discipline
+
+- Keep and reuse the latest relevant `domSnapshot()` until it proves stale or you need locator ground truth for UI that was not present in it.
+- Take a fresh `domSnapshot()` after navigation when you need to orient yourself or construct locators on the new page.
+- If a click times out, strict mode fails, or a selector parse error occurs, take a fresh `domSnapshot()` before forming the next locator.
+- Construct locators only from what appears in the latest snapshot. Do not guess labels, accessible names, or selectors.
+- Do not print full snapshot text repeatedly when a smaller excerpt, a `count()`, a specific attribute, or a direct locator check would answer the question with fewer tokens.
+- Do not discover page content by iterating through many results, cards, links, or rows and reading their text or attributes one by one.
+- Do not loop over a broad locator with `all()` and call `getAttribute(...)`, `textContent()`, or `innerText()` on each match. Each read crosses the browser boundary and becomes extremely expensive on large pages.
+- `locator.getAttribute(...)` is a single-element read, not a batch read. If the locator matches multiple elements, expect a strict-mode error rather than an array of attributes.
+- Use one broad observation to orient yourself: usually one fresh snapshot, or one screenshot if the visual structure is clearer than the DOM.
+- After that orientation step, narrow to the relevant section or a small number of strong candidates.
+- If the page is not getting narrower, do not scale up extraction across more elements. Change strategy instead.
+- Do not use `locator(...).allTextContents()`, `locator("body").textContent()`, or `locator("body").innerText()` as exploratory search tools across a page or large container.
+- Use broad text or attribute extraction only after you have already identified the exact container or element you need, and only when a smaller scoped check would not answer the question.
+- When you need many links, media URLs, or result titles, prefer a single `domSnapshot()` and parse the relevant lines, use the site's own search/filter UI, or navigate directly to a focused results page. Only fall back to per-element reads for a small, already-scoped set of candidates.
+- Do not use large body-text dumps, embedded app-state JSON such as `__NEXT_DATA__`, or repeated full-page extraction across multiple candidate pages as an exploratory search strategy.
+- Use large text or embedded JSON extraction only after you have already identified the relevant page, or when a site-specific skill explicitly depends on it.
+
+### Hard Constraints For Playwright In This Runtime
+
+- Do not pass a regex as `name` to `getByRole(...)` in this environment. Use a plain string `name` only.
+- Do not use `.first()`, `.last()`, or `.nth()` unless you have just called `count()` on the same locator and explicitly confirmed why that position is correct.
+- Do not click, fill, or press on a locator until you have verified it resolves to exactly one element when uniqueness is not obvious.
+- Do not retry the same failing locator without a fresh `domSnapshot()`.
+- Do not use a guessed locator as an exploratory probe. If the latest snapshot does not clearly support the locator, do not spend timeout budget testing it.
+- Do not assume browser-side Playwright supports the full upstream API surface. If a method is not explicitly known to exist, do not call it.
+- Do not assume `locator(...).selectOption(...)` exists in this environment.
+
+### Required Interaction Recipe
+
+Before every click, fill, select-like action, or press:
+
+1. Reuse the latest relevant `domSnapshot()` when it still contains the locator ground truth you need. Take a fresh one only when it does not.
+2. Build the most stable locator from the latest snapshot.
+3. If uniqueness is not obvious from the selector itself, call `count()` on that locator.
+4. Proceed only if the locator resolves to exactly one element.
+5. Perform the action.
+6. After the action, collect another observation only when the next decision requires it. Prefer a targeted state check when it answers the question; take a fresh snapshot when you need new locator ground truth.
+
+If `count()` is `0`:
+
+- The selector is wrong, stale, hidden, or the UI state is not ready.
+- Do not click anyway.
+- Do not wait on that locator to see if it eventually works.
+- Re-snapshot and rebuild the locator.
+
+If `count()` is greater than `1`:
+
+- The selector is ambiguous.
+- Scope to the correct container or switch to a stronger attribute.
+- Do not use `.first()` as a shortcut.
+
+### Locator Strategy
+
+Build locators from what the snapshot actually shows, not what looks visually obvious.
+
+Prefer the most stable contract, in this order:
+
+1. `data-testid`
+2. Stable `data-*` attributes
+3. Stable `href` (prefer exact or strong matches over broad substrings)
+4. Scoped semantic role + accessible name using a string `name`
+5. Scoped `getByText(...)`
+6. Scoped CSS selectors via `locator(...)`
+7. A scoped DOM-based click path or node-ID-based click when Playwright cannot produce a unique stable locator
+
+Use the most specific locator that is still durable.
+
+Treat a stable `href` as a strong hint, not proof of uniqueness. If multiple elements share the same `href`, scope to the correct card or container and confirm `count()` before clicking.
+
+Treat generic labels like `Menu`, `Main Menu`, `Help`, `Close`, `Default`, `Color`, `Size`, single-letter size labels such as `S`, `M`, `L`, `XL`, `Sort by`, `Search`, and `Add to cart` as ambiguous by default. Scope them to the correct container before acting.
+
+On search results, product grids, carousels, and modal-heavy pages, repeated `href`s and repeated generic labels are ambiguous by default. First identify the stable card or container, then scope the locator inside that container before clicking.
+
+### Using `getByRole(..., { name })`
+
+- `name` is the accessible name, which may differ from visible text.
+- In the snapshot:
+  - `link "X"` usually reflects the accessible name.
+  - Nested text may be visible text only.
+- Use `getByRole` only when the accessible name is clearly present and likely unique in the latest snapshot.
+
+### Interaction Best Practices
+
+- Scope before acting: find the right container or section first, then target the child element.
+- If you call `count()` on a locator, store the result in a local variable and reuse it unless the DOM changes.
+- Match the locator to the actual element type shown in the snapshot (link vs button vs menuitem vs generic text).
+- Do not assume every click navigates. If opening a menu or filter, wait for the expected UI state, not page load.
+- Prefer structured local signals such as selected control state, visible confirmation text, modal contents, a specific line item, or URL parameters over scraping broad result sections or dumping large parts of the page.
+- Do not add explicit `timeoutMs` to routine `click`, `fill`, `check`, or `setChecked` calls unless you have a concrete reason the target is slow to become actionable.
+- Reserve explicit timeout values for navigation, state transitions, or other known slow operations.
+- If you already know the exact destination URL and no click-side effect matters, prefer `tab.goto(url)` over a brittle locator click.
+- Do not reacquire `tab` inside each `node_repl` call. Reuse the existing `tab` binding to save tokens and preserve state. Only reacquire or reassign it when you intentionally switch tabs, after a kernel reset, or after a failed call that did not create the binding.
+- Do not use fixed sleeps as a default waiting strategy. After an action, prefer a concrete state check or targeted wait. Take a fresh snapshot when you need new locator ground truth.
+- If a fixed delay is truly unavoidable for a known transition, keep it short and follow it immediately with a specific verification step.
+
+### Error Recovery
+
+- A strict mode violation means your locator is ambiguous.
+- Do not retry the same locator after a strict mode violation.
+- After strict mode fails, immediately inspect a fresh snapshot and rebuild the locator using tighter scope, a disambiguating container, or a stable attribute.
+- If a checkbox or radio exists but `check()` or `setChecked()` reports that it is hidden or did not change state, stop retrying the underlying input. Click its scoped visible associated `label[for]` or enclosing visible control once, then verify checked state.
+- A selector parse error means the locator syntax is invalid in this runtime.
+- Do not reuse the same locator form after a selector parse error.
+- A timeout usually means the target is missing, hidden, stale, offscreen, not yet rendered, or the selector is too broad.
+- Do not retry the same locator immediately after a timeout.
+- After a timeout, take a fresh snapshot, confirm the target still exists, and then either refine the locator or fall back to a more stable attribute.
+- If role or accessible-name targeting is unstable, fall back deliberately to a stable attribute (`data-*`, `href`, etc.), not brittle CSS structure.
+- If two locator attempts fail on the same target, stop escalating complexity on role or text locators. Switch to the most stable visible attribute from the snapshot or use a scoped DOM-based click path.
+
+### Fallback Guidance
+
+- Prefer stable `href` values copied from the snapshot over guessed URL patterns.
+- Prefer scoped attribute selectors over global text selectors.
+- Use `getByText(...)` only when role-based or attribute-based locators are not reliable, and scope it to a container whenever possible.
+- Prefer attributes copied directly from the latest snapshot over inferred semantics, fragile CSS chains, or positional selectors.
+- Do not invent likely selectors. If the snapshot does not clearly expose a unique target, fetch a fresh snapshot and reassess before acting.