Cypress Queries, Assertions & Custom Commands

The examples live in a Cypress project that has the cypress package (16.2.0) as its only dependency and no plugins. The configuration reads the base URL from the environment; the specs are TypeScript and are loaded after a support file that registers the custom commands.

Source: Cypress: Configuration

Source: Cypress: Configuration, folders and files

The specs were run with the commands below. CYPRESS_READER_PASSWORD supplies the secret that cy.env() reads (see Custom commands); it is copied from the variable that Bookshelf itself reads. Set it to a local test password; never commit a real one.

Source: Cypress: Command line

Both runs ended with All specs passed!: selecting.cy.ts 7 tests, get-by-role.cy.ts 7, assertions.cy.ts 9, custom-commands.cy.ts 4 and overwrite.cy.ts 3. The project also type-checks with tsc --noEmit, so the type declarations shown below are exactly what a TypeScript project needs. The cypress run commands are headless; cypress open runs the same specs in a headed browser with the Command Log, which is the better place to watch a query retry. Nothing on this page behaves differently between headless and headed runs, between Electron and Chrome, or between a laptop and a CI job; the only difference to watch is that a headed run lets you click a command in the log and inspect what a query yielded.

Each spec file wraps its tests in a describe block with a beforeEach hook that restores the seeded data through Bookshelf’s reset endpoint. selecting.cy.ts and assertions.cy.ts also open the catalogue in the hook, while the other specs visit the pages they need inside the tests. The hook of the first spec, which the tests that are quoted from it assume:

Source: Cypress: Writing and organizing tests

Cypress commands come in kinds, and the kind decides what happens when something is not ready yet. A query (cy.get(), cy.contains(), cy.getByRole(), .find(), .filter(), .first(), .parent(), .its(), .invoke(), .url() and the rest of the list in the Cypress command table) reads the state of the page, is synchronous inside, has no side effects and is retried: Cypress runs it again, from the start of the chain, until it yields something that satisfies the assertions attached to it or the timeout (4 seconds by default, the defaultCommandTimeout setting) expires. An action (.click(), .type(), .select()) waits for the element to be actionable, performs one effect and is never repeated. An assertion (.should(), .and()) is attached to the previous command and is what makes the retry loop meaningful. Commands that are neither, such as cy.request(), cy.visit() or .then(), run once. The practical rule that follows is to end every chain of queries with an assertion that states what you expect, rather than reading a value and checking it in .then(), which runs only once.

Every test needs a way to point at an element. The Cypress best-practices page ranks the options by how well they survive changes to the page:

The ranking is the one in the Cypress documentation; it is a recommendation, not a measurement. Two judgements are worth making explicit. First, a dedicated attribute such as data-cy is the most stable handle because nothing but the test uses it, but it says nothing about whether a real user could find the element. A test that clicks [data-cy="submit"] still passes when the button is hidden from assistive technology. Second, cy.getByRole() and cy.contains() are coupled to what the user perceives, which makes them better evidence that the page works and a little more likely to break during a copy change. Most suites use a mix: roles and names for the controls a user operates, and test ids for containers, list items and values that have no accessible name. The Cypress documentation also notes that none of these approaches is a complete accessibility test.

Cypress does not care which attribute you pick; the documentation uses data-cy, other projects use data-test, data-testid or data-qa. Bookshelf follows the data-testid convention that Testing Library and Playwright popularised (see the example application page), so the specs on this page select [data-testid=...]; replace the attribute name to use data-cy. Unlike Playwright, Cypress has no setting that changes what a "test id" is, so wrapping the attribute in a custom query, as Custom queries does with cy.getByTestId(), is the usual way to avoid repeating the attribute name in every spec. The eslint-plugin-cypress rule cypress/require-data-selectors can enforce data-* selectors at lint time.

cy.get(selector) queries the document for every element that matches a CSS selector (with the jQuery extensions Cypress bundles, such as :first and :contains()), and cy.get('@name') reads an alias. It yields the elements it finds, which may be one, many or, with a negative assertion, none. Because it is a query it retries until the element exists and every assertion chained to it passes; without an explicit assertion, the implicit assertion is that the element exists.

The first spec shows the everyday uses: counting, picking one element, selector lists and attribute selectors.

Source: Cypress: get

.first(), .last() and .eq() read better than the jQuery :first and :eq() selectors, and they behave differently in a way that matters: :first is a jQuery extension that yields one element for the whole page, so ul li:first is the first li of the first list only, while the CSS :first-child yields the first li of every list. When an id contains characters that CSS treats as syntax, such as . or :, escape them (cy.get('#id\\.\\.\\.1234')) or build the selector at runtime with CSS.escape().

cy.contains(content) and cy.contains(selector, content) find elements by their text. The content can be a string, a number or a regular expression, the selector restricts which elements are candidates, and the command yields at most one element.

The matching rules explain most surprises:

Source: Cypress: contains

Because there is no built-in negation, "elements that do not contain this text" is written with .not() and the jQuery :contains() selector (cy.get('li').not(':contains("(")')). The text must also be the whole story for waiting: cy.contains('Saving').should('not.exist') passes immediately when "Saving" has not rendered yet, so first assert that it appeared, or assert on the end state (cy.contains('Saved').should('be.visible')).

Cypress 16.2.0 (13 October 2026) added cy.getByRole(role, options), a built-in query that finds elements the way assistive technology does: by the role the browser exposes (button, link, heading, navigation, textbox, …​) and, optionally, by the accessible name. It does what the findByRole() and findAllByRole() queries of Cypress Testing Library do, without a plugin. The signature, as shipped in 16.2.0 and confirmed by running it:

Source: Cypress: getByRole

.within(callback) makes cy.get(), cy.contains() and cy.getByRole() inside the callback search only inside the subject, and cy.root() yields the subject. It requires a single DOM element as the subject (since Cypress 12 it throws for several). It yields the same subject it was given, and anything returned from the callback, including a cy.wrap(), is ignored, so never chain commands that rely on an inner element after .within(): query the inner element with .find() instead.

Source: Cypress: within

To escape the scope temporarily, start a new chain with cy.root() and walk up to an ancestor outside the subject, for example cy.root().closest('.example').find('#name'). Starting at cy.root() inside .within() is the documented way, because cy.get() is always scoped.

Traversal commands are queries, so they retry like cy.get(). They start from the subject, yield jQuery collections and are the answer to "find the thing next to the thing I can identify".

The next spec uses them to start from a recognisable title and reach the card, its neighbours and its author, and to turn a list into plain data with .then(), .invoke() and .its(). A query chain such as .closest().children() is retried as a whole, which is why this style survives re-renders.

Source: Cypress: Table of contents, queries

A common idiom is to find a table row or list item by its text and then act inside it: cy.contains('tr', 'Jane').contains('button', 'Edit').click(). Both calls are queries, so the whole chain retries until the button exists, and only .click() runs once.

An assertion states what must be true of the subject. Cypress bundles Chai (the BDD expect and should styles and the TDD assert style), Chai-jQuery for DOM elements and Sinon-Chai for spies and stubs, and exposes them through .should(), .and() and the globals expect and assert. .and() is an alias of .should() that reads better in a chain.

A custom command packages a sequence of Cypress commands under one name. Add it with Cypress.Commands.add(name, callbackFn) or Cypress.Commands.add(name, options, callbackFn), or add several at once with Cypress.Commands.addAll(callbackObj). The prevSubject option decides the kind of command:

The support file, cypress/support/e2e.ts, runs before every spec, so commands defined in a file it imports (conventionally cypress/support/commands.ts) are available in all of them. The file below defines one command of each kind plus a query, and declares their types once in the global Cypress.Chainable interface so that IntelliSense and tsc know them.

Source: Cypress: Custom commands, Cypress: TypeScript support

Points worth noting in that file:

The specs that use them:

Source: Cypress: Custom commands

Cypress 12 added Cypress.Commands.addQuery(name, callbackFn), the same API that the built-in queries use. A query obeys three rules: it is synchronous (no promises, no await), it is retriable (Cypress calls the function you return repeatedly) and it is idempotent (calling it many times must not change the application). Use a query when you return DOM elements or data that other commands act or assert on, and a command when the work is asynchronous, has side effects or runs only once.

The callback has two layers. The outer function runs once per use and receives the arguments the test passed; it does set-up, such as validating arguments, creating the log entry and this.set('timeout', options.timeout). It must return the inner function, which receives the previous subject and returns the new subject, and which Cypress may call many times: first repeatedly until it passes or times out, then again to resolve the subject for later commands or an alias. If the inner function throws, Cypress retries it until the timeout, which is the whole of retry-ability. Use function () {} rather than an arrow function for the outer function, because Cypress sets the timeout through this. Cypress.ensure provides the subject checks the built-in queries use, such as Cypress.ensure.isType(subject, ['optional', 'element', 'window', 'document'], 'contains', cy).

getByTestId in the support file above is a query. It builds on the built-in get through cy.now(), which returns the inner function of a query. cy.now is an internal Cypress function, not part of the documented API, but it worked on 16.2.0 and it passes the timeout option through: a failing cy.getByTestId('missing', { timeout: 700 }) reported "Timed out retrying after 700ms" and the default one 4000 ms. If you prefer to stay on documented ground, cy.get() with Cypress.Commands.overwriteQuery() or a plain helper function that returns cy.get(...) achieves the same without a new query.

Source: Cypress: Custom queries

As with commands, the documentation warns against abstractions that merely rename cy.get() (cy.getButton()); good candidates are queries specific to your application that are used everywhere, such as cy.findBreadcrumbs() or cy.getLoginForm().

Cypress.Commands.overwrite(name, callbackFn) replaces an existing command; the callback receives the original function first, then (for a child or dual command) the subject, then the arguments, and must call and return the original. Use it sparingly, because it changes the behaviour for Cypress’s own use too. Cypress.Commands.overwriteQuery(name, callbackFn) does the same for a query and is the only way to change a query: overwrite cannot overwrite queries, and overwriteQuery cannot overwrite commands (the API was added in 12.6.0). The callback of overwriteQuery must be a function, and the original must be invoked with .call(this, ...) or .apply(this, ...) because query functions rely on this.

Source: Cypress: Custom commands, overwrite, Cypress: Custom queries, overwrite

The three overwrites in that spec do different things: type masks the characters in the Command Log (and in screenshots and videos) when { sensitive: true } is passed, so a password typed in a test is not recorded; visit records every URL; and the getByRole overwrite makes native: false the default for that spec. The overwrites are declared in the spec so that they do not leak into the other specs; put them in the support file when they should apply everywhere. The type augmentation for visit is needed because the built-in typings have overloads that make an overwrite with explicit arguments fail tsc. The overwritten type accepts the extra option in TypeScript only because it is declared in the same file.

Overwrites compose with baseUrl: the Cypress documentation points out that many projects write their own "visit the app" command only to swap base URLs between environments. That is unnecessary, because baseUrl is used by cy.visit() and cy.request() and can be overridden with the CYPRESS_BASE_URL environment variable; this project reads BASE_URL in the configuration for the same reason.

Source: Cypress: Changelog

The versions in this list come from the History tables of the command pages and from the changelog and migration guide; they were checked on 25 October 2026.