---
id: api/cypress-api/ensure
title: Cypress.ensure
description: >-
  Cypress.ensure is a collection of helper methods for making assertions. They
  are mostly useful when writing custom queries or custom commands.
section: api
source_path: docs/api/cypress-api/ensure.mdx
version: 3163d68b20e695f2c76d40c85c3f3b956dd19a3b
updated_at: '2026-08-21T20:59:04.402Z'
---
# Cypress.ensure

`Cypress.ensure` is a collection of helper methods for making assertions. They are mostly useful when writing [custom queries](/llm/markdown/api/cypress-api/custom-queries.md) or [custom commands](/llm/markdown/api/cypress-api/custom-commands.md).

Most functions on `Cypress.ensure` accept a [`subject`](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management) argument, check an assertion, and throw an error if the assertion fails. These functions have no return value.

## Syntax

```
// Type of argument
Cypress.ensure.isType(subject, type, commandName, cy)​
Cypress.ensure.isElement(subject, commandName, cy)​
Cypress.ensure.isWindow(subject, commandName, cy)
Cypress.ensure.isDocument(subject, commandName, cy)​

// State of DOM element
Cypress.ensure.isAttached(subject, commandName, cy)​
Cypress.ensure.isNotDisabled(subject, commandName)​
Cypress.ensure.isNotHiddenByAncestors(subject, commandName)​
Cypress.ensure.isNotReadonly(subject, commandName)​
Cypress.ensure.isScrollable(subject, commandName)​
Cypress.ensure.isStrictlyVisible(subject, commandName)​
Cypress.ensure.isVisible(subject, commandName)​
```

Many of these functions accept an optional `onFail` argument. This is a legacy feature used to customize the thrown error, and may be removed in a future release; we recommend against relying on it. If you need more control over the error thrown, write your own `ensure` function instead.

### Usage

**Correct Usage**

*   cypress/support/commands.js
*   cypress/support/commands.ts

```
Cypress.Commands.addQuery('getChildById', function (id) {
  return (subject) => {
    // Verify that the subject is an element, document, or window object
    Cypress.ensure.isType(
      subject,
      ['element', 'document', 'window'],
      'getChildById',
      cy
    )

    return $$(`#${id}`, subject)
  }
})

const queryName = 'verifyElementActionable'

Cypress.Commands.addQuery(queryName, function (...args) {
  return (subject) => {
    // Verify that the subject fulfills a variety of conditions
    Cypress.ensure.isElement(subject, queryName, cy)
    Cypress.ensure.isVisible(subject, queryName, cy)
    Cypress.ensure.isNotDisabled(subject, queryName, cy)
    Cypress.ensure.isNotReadonly(subject, queryName, cy)

    return subject
  }
})
```

```
declare global {
  namespace Cypress {
    interface Chainable {
      getChildById(id: string): Chainable<JQuery>
      verifyElementActionable(...args: any[]): Chainable<JQuery>
    }
  }
}

Cypress.Commands.addQuery('getChildById', function (id) {
  return (subject) => {
    // Verify that the subject is an element, document, or window object
    Cypress.ensure.isType(
      subject,
      ['element', 'document', 'window'],
      'getChildById',
      cy
    )

    return $$(`#${id}`, subject)
  }
})

const queryName = 'verifyElementActionable'

Cypress.Commands.addQuery(queryName, function (...args) {
  return (subject) => {
    // Verify that the subject fulfills a variety of conditions
    Cypress.ensure.isElement(subject, queryName, cy)
    Cypress.ensure.isVisible(subject, queryName, cy)
    Cypress.ensure.isNotDisabled(subject, queryName, cy)
    Cypress.ensure.isNotReadonly(subject, queryName, cy)

    return subject
  }
})
```

## See also

*   ["Custom Queries"](/llm/markdown/api/cypress-api/custom-queries.md) contains more information about writing custom queries, which is the main use-case for the `ensure` functions.