In a Cypress test, when is `Cypress.$` safe to use, and why is it empty right after `cy.visit()`?

## `Cypress.$` is jQuery, not a command Cypress bundles jQuery and exposes the function itself as `Cypress.$`. Anything you can do with jQuery you can do with it, including jQuery's utility functions rather than just its element queries — `Cypress.$.each` and `Cypress.$.ajax` are jQuery's `jQuery.each` and `jQuery.ajax`. What it is **not** is a `cy` command. It never joins the command queue, it takes no `timeout`, and it does no waiting of any kind. There is a second, easily confused name. `cy.$$` is a wrapper around jQuery's element-querying half, so `cy.$$('.room-card')` works but `cy.$$.each([1, 2, 3], fn)` does not. Both read the application's DOM synchronously; neither is a queued command. | | queued | waits for anything | returns | |---|---|---|---| | `cy.get('.room-card')` | yes | yes | a Cypress chainer whose subject is a jQuery set | | `Cypress.$('.room-card')` | no | no | a jQuery object, immediately | | `cy.$$('.room-card')` | no | no | a jQuery object, immediately | ## Why it is empty right after `cy.visit()` A Cypress spec body runs top to bottom **once**, and what it does is build a queue. `cy` calls put work on that queue; plain JavaScript statements execute as the file is read. So in: ```js cy.visit('/rooms') const $rooms = Cypress.$('.room-card') ``` the order of events is: 1. `cy.visit('/rooms')` is **enqueued**. No navigation has happened. 2. `Cypress.$('.room-card')` executes **now**, against whatever page is currently loaded — the blank page a fresh test starts on, or the leftover page from the previous command. 3. `$rooms` is an empty jQuery object, `$rooms.length` is `0`. 4. Only after the spec body finishes does Cypress start draining the queue and actually navigate. Nothing about this is intermittent. It fails the same way every run, which is at least a mercy — the same misunderstanding applied to `let rooms; cy.get(...).then(($el) => { rooms = $el })` and a read on the next line produces the identical `undefined`. ## Where `Cypress.$` earns its place - **Debugging from DevTools.** Pause a test with `cy.pause()` and query the room list from the browser console to see what is genuinely rendered. This is the use the API exists for. - **Inside a `.then()` callback.** By the time a callback runs, the commands before it have finished, so a synchronous read is meaningful. Even then, working from the subject you were handed — `cy.get('body').then(($body) => $body.find('.room-card'))` — keeps the reasoning local. - **Non-DOM jQuery utilities.** jQuery's `each` over a fixture array, reached as `Cypress.$.each`, is legitimate and has nothing to do with the page at all. ## The trap it exists to enable The tempting use is conditional testing: *if a promo banner is showing on the room list, dismiss it, otherwise carry on.* ```js // fragile - the banner may simply not have rendered yet if (Cypress.$('.promo-banner').length) { cy.get('.promo-banner .dismiss').click() } ``` A synchronous read answers "is it there **at this instant**", and the honest answer during an app's render is often "not yet". The branch is decided before the page has settled, so the test takes a different path on a slow CI machine than it does on your laptop — and it is the branch that is wrong, not the click, which makes it miserable to diagnose. The DOM has to already be in a known, settled state for a synchronous existence check to mean anything, and if you can guarantee that, you usually did not need the branch. ## What to reach for instead Almost every reason people give for using `Cypress.$` has a queued equivalent that behaves the way they wanted in the first place: | what you wanted | the queued way | |---|---| | "read the room cards after navigating" | `cy.get('.room-card').then(($cards) => ...)` | | "grab the element into a variable" | keep working inside `.then()`, or alias it with `.as()` | | "check the promo banner is gone" | assert it, so the assertion decides when the page has settled | | "do jQuery work on a subject" | you already hold jQuery inside the callback - no global needed | The common thread is that a queued command decides *when* it looks, and a synchronous read decides that for you at the worst possible moment. If a piece of test code needs to know what the page looks like, the queue is where that knowledge is reliable. ## The sentence to say out loud "`Cypress.$` is the bundled jQuery function, it runs the instant the line runs rather than joining the command queue, so anything above it that is still queued has not happened yet." Everything else about the API — why it is empty after `cy.visit()`, why it is fine inside `.then()`, why branching on it is a flake generator — falls straight out of that one sentence.