---
id: api/cypress-api/ensure
title: Cypress.ensure | Cypress Documentation
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: 48b03b5502f7aea1d0454750cce208f775403542
updated_at: '2026-05-20T19:00:20.270Z'
---
# 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 argumentCypress.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 elementCypress.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.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.