In a Cypress `.within()` block, why can `cy.get()` time out on a visible element?

## What the scope actually restricts `.within()` re-roots Cypress's document-level queries at one element, and it restricts them to that element's **descendants in the DOM tree**. Visual position is irrelevant. A calendar popup that appears directly under the check-in field on screen may be a child of `<body>`, and to a scoped query that makes it as unreachable as a widget on another page. That is precisely what modern date pickers, modals, dropdowns and toasts do. To escape a parent's `overflow: hidden` or stacking context, the component renders its floating layer into a container at the end of `<body>` and positions it over the trigger. The markup and the pixels disagree, and the scope follows the markup: ```javascript cy.get('.guest-form').within(() => { cy.get('#check-in').click() // opens the calendar cy.get('.calendar-day').first() // times out: the popup is not inside .guest-form }) ``` ## Why the error message hides the cause When a scoped `cy.get()` finds nothing, the failure reads: > Timed out retrying after 4000ms: Expected to find element: `.calendar-day`, but never found it. There is no mention of the scope. The message describes the selector, so the natural reading is "the calendar never rendered" — and the tester goes looking for a missing render, a slow API or a short timeout, none of which is the problem. `cy.contains()` is kinder here: a scoped `cy.contains()` failure says *within the element: `<form>`*, which names the scope directly. The reliable tells that you are looking at a scoping failure rather than a timing one are: - The element is visible in the runner's DOM snapshot at the moment of failure. - The same selector passes when the identical query is written outside the block. - The element's ancestors in the DevTools inspector do not include the scoped container. ## Three ways out 1. **Escape temporarily.** Inside the block, `cy.root()` yields the scoped element, and `.closest()` walks up from it to a shared ancestor — from which you can query back down and reach anything on the page: ```javascript cy.get('.guest-form').within(() => { cy.get('#check-in').click() cy.root().closest('body').find('.calendar-day').first().click() cy.get('#guests').type('2') // still scoped to .guest-form }) ``` 2. **Close the block.** End the `.within()` and start a new chain for the popup. This is usually the most readable option, because the two elements really do live in different parts of the tree and the test now says so. 3. **Scope to a container that holds both.** If the popup mounts into a known wrapper, scope to that wrapper rather than to the form, or drop the scope for the popup interaction alone. ## When not to scope at all Scoping earns its keep when several queries share a genuine DOM ancestor. It costs you when it does not: | situation | scope? | |---|---| | a repeated card or row with fields inside it | yes — that is what it is for | | a form plus its portal-rendered date picker | no — they are siblings under `<body>` | | a modal that mounts at the end of `<body>` | scope to the modal, not to what opened it | | a toast confirming a booking | no — query it on its own chain | A useful habit on an unfamiliar app is to confirm the DOM parentage once, in the inspector, before writing the block. Five minutes there saves an afternoon of reading a timeout as flake. ## A triage order that settles it in a minute 1. **Re-run the failing query unscoped.** Move the identical `cy.get()` outside the block. If it passes, the element exists and the scope is the problem; if it still fails, you have an ordinary missing-element or timing problem and the scope is a red herring. 2. **Read the ancestors.** In the failure's DOM snapshot, walk up from the element. If the scoped container is not among its ancestors, no timeout value will ever make the query pass. 3. **Decide where the boundary belongs.** Either escape from inside the block, split the chain, or move the scope to a container that genuinely holds both elements. Steps one and two are worth doing in that order, because raising `defaultCommandTimeout` is the tempting move and it turns a fast, honest failure into a slow one. ## The related trap Two more things behave the way the tree says rather than the way the screen says: - `cy.get('@alias')` is not scoped — it resolves a stored subject, so it can appear to "escape" a block that never applied to it in the first place. - A scoped query that matches an element which is *later* moved out of the container will start failing without any test change, because the query is re-evaluated against the live DOM on each retry, not against the set it matched the first time.