🎯 What You Will Learn
Read Playwright snapshots, locate accessible controls, use live element refs, and recover safely when references become stale.
- Read the accessible tree instead of guessing DOM selectors
- Choose the correct element from its role and name
- Use generated refs only while they are current
- Recover from stale references predictably
What a Snapshot Gives You
A Playwright CLI snapshot is a compact description of the current accessible page. Interactive nodes receive refs that later commands can target.
Because the output follows roles and names, it is often closer to how a user and assistive technology perceive the page than a long CSS selector.
Capture Your First Snapshot
Open the TodoMVC demo and snapshot before touching the page.
"$PWCLI" -s=snapshot-demo open https://demo.playwright.dev/todomvc --headed
"$PWCLI" -s=snapshot-demo snapshot- heading "todos" - textbox "What needs to be done?" [ref=eX]
Read Role and Accessible Name Together
The role tells you what an element does; the accessible name distinguishes it from similar elements. A textbox named What needs to be done? is a stronger target than an anonymous input.
| Snapshot detail | Meaning |
|---|---|
| button | The element's semantic role |
| Save changes | The accessible name users encounter |
| ref=e12 | A temporary CLI handle for the current snapshot |
Interact with the Current Ref
Replace eX with the actual textbox ref shown in your snapshot. Type works after the click gives the textbox focus.
"$PWCLI" -s=snapshot-demo click eX
"$PWCLI" -s=snapshot-demo type "Read accessible snapshots"
"$PWCLI" -s=snapshot-demo press EnterSearch a Large Snapshot
Use find when the snapshot is long. It returns matching nodes with nearby context, which is faster than scanning the whole tree manually.
"$PWCLI" -s=snapshot-demo snapshot
"$PWCLI" -s=snapshot-demo find "Read accessible snapshots"Know When References Change
Navigation, client-side re-rendering, opening a dialog, closing a menu, and switching tabs can all invalidate an earlier ref.
Ref lifetime: Treat a ref as a handle to the latest observed page, not as a permanent selector stored in documentation or scripts.
Recover from a Stale Ref
Do not force the action or fall back to arbitrary JavaScript. Snapshot again, identify the same role and accessible name, then use the new ref.
- Stop after the failed command.
- Capture a fresh snapshot.
- Match the element by role and accessible name.
- Retry once with the new ref and verify the result.
"$PWCLI" -s=snapshot-demo snapshot
"$PWCLI" -s=snapshot-demo find "Toggle Todo"
"$PWCLI" -s=snapshot-demo click eNEWGenerate a Locator for Test Code
When exploration becomes a committed test, generate a user-facing locator from the element and review it before adding it to your test file.
"$PWCLI" -s=snapshot-demo snapshot
"$PWCLI" -s=snapshot-demo generate-locator eXReview generated code: Prefer role, label, text, or an explicit test id. Avoid keeping a brittle DOM path just because a generator produced it.
Recap
- Snapshot before interacting.
- Use role and accessible name to understand the target.
- Refs are temporary handles, not permanent selectors.
- Re-snapshot after meaningful page changes or tab switches.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.