김경종
129 lines
11 KiB
Markdown
129 lines
11 KiB
Markdown
## 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.
|