# Cypress Documentation
# Source: https://raw.githubusercontent.com/cypress-io/cypress-documentation/main/docs/api/commands/then.mdx
# Path: docs/api/commands/then.mdx

---
title: 'then | Cypress Documentation'
description: Enables you to work with the subject yielded from the previous command in Cypress.
sidebar_label: then
---

<ProductHeading product="app" />

# then

Enables you to work with the subject yielded from the previous command.

:::info

**Note:** `.then()` assumes you are already familiar with core concepts such as
[closures](/app/core-concepts/variables-and-aliases#Closures).

:::

:::info

**Note:** Prefer [`.should()` with callback](/api/commands/should#Function) over
`.then()` for assertions as they are automatically rerun until no assertions
throw within it but be aware of [differences](/api/commands/should#Differences).

:::

## Syntax

```javascript
.then(callbackFn)
.then(options, callbackFn)
```

### Usage

<Icon name="check-circle" color="green" /> **Correct Usage**

```javascript
cy.get('.nav').then(($nav) => {}) // Yields .nav as first arg
cy.location().then((loc) => {}) // Yields location object as first arg
```

### Arguments

<Icon name="angle-right" /> **options _(Object)_**

Pass in an options object to change the default behavior of `.then()`.

| Option    | Default                                                           | Description                                                          |
| --------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `.then()` to resolve before [timing out](#Timeouts) |

<Icon name="angle-right" /> **callbackFn _(Function)_**

Pass a function that takes the previously yielded subject as its first argument.

<HeaderYields />

Whatever is returned from the callback function becomes the new subject and will
flow into the next command (with the exception of `undefined` or `null`).

- If the return value is a chain of Cypress commands (eg
  `return cy.get('button')`), Cypress will wait for them to resolve and use
  their return value as the new subject.
- If the return value is a Promise, Cypress will wait for it to resolve, and use
  the resolved value as the new subject to continue the chain of commands.
- If the callback returns `undefined` or `null` (or there is no return value),
  the result of the last Cypress command in the callback function will be
  yielded as the new subject instead, and flow into the next command.
- If the callback returns `undefined` or `null` (or there is no return value)
  and the callback does not call any Cypress commands, the subject will not be
  modified, and the previous subject will carry over to the next command.

The callback function of `.then()` is not retried. It is
[unsafe](/app/core-concepts/retry-ability#Only-queries-are-retried) to return
DOM elements directly from the callback and then use further commands on them.
Instead, use Cypress queries to locate the elements you're interested in acting
or asserting on.

## Examples

:::info

We have several more examples in our
[Core Concepts Guide](/app/core-concepts/variables-and-aliases) which go into
the various ways you can use `.then()` to store, compare, and debug values.

:::

### DOM element

#### The `button` element is yielded

```javascript
cy.get('button').then(($btn) => {
  const cls = $btn.attr('class')

  cy.wrap($btn).click().should('not.have.class', cls)
})
```

#### The number is yielded from previous command

```js
cy.wrap(1)
  .then((num) => {
    cy.wrap(num).should('equal', 1) // true
  })
  .should('equal', 1) // true
```

### Change subject

#### The el subject is changed with another command

```javascript
cy.get('button')
  .then(($btn) => {
    const cls = $btn.attr('class')

    cy.wrap($btn).click().should('not.have.class', cls).find('i')
    // since there is no explicit return
    // the last Cypress command's yield is yielded
  })
  .should('have.class', 'spin') // assert on i element
```

#### The number subject is changed with another command

```javascript
cy.wrap(1).then((num) => {
  cy.wrap(num)).should('equal', 1) // true
  cy.wrap(2)
}).should('equal', 2) // true
```

#### The number subject is changed by returning

```javascript
cy.wrap(1)
  .then((num) => {
    cy.wrap(num)
      .should('equal', 1) // true
      .then(() => {
        return 2
      })
  })
  .should('equal', 2) // true
```

#### Returning `undefined` will not modify the yielded subject

```javascript
cy.get('form')
  .then(($form) => {
    console.log('form is:', $form)
    // undefined is returned here, but $form will be
    // yielded to allow for continued chaining
  })
  .find('input')
  .then(($input) => {
    // we have our $input element here since
    // our form element was yielded and we called
    // .find('input') on it
  })
```

### Raw HTMLElements are wrapped with jQuery

```javascript
cy.get('div')
  .then(($div) => {
    return $div[0] // type => HTMLDivElement
  })
  .then(($div) => {
    $div // type => JQuery<HTMLDivElement>
  })
```

### Promises

Cypress waits for Promises to resolve before continuing

#### Example using Q

```javascript
cy.get('button')
  .click()
  .then(($button) => {
    const p = Q.defer()

    setTimeout(() => {
      p.resolve()
    }, 1000)

    return p.promise
  })
```

#### Example using bluebird

```javascript
cy.get('button')
  .click()
  .then(($button) => {
    return Promise.delay(1000)
  })
```

#### Example using jQuery deferred's

```javascript
cy.get('button')
  .click()
  .then(($button) => {
    const df = $.Deferred()

    setTimeout(() => {
      df.resolve()
    }, 1000)

    return df
  })
```

## Notes

### Differences

<ThenShouldAndDifference />

## Rules

<HeaderRequirements />

- `.then()` requires being chained off a previous command.

<HeaderAssertions />

- `.then()` will only run assertions you have chained once, and will not
  [retry](/app/core-concepts/retry-ability).

<HeaderTimeouts />

- `.then()` can time out waiting for a promise you've returned to resolve.

## Command Log

- `.then()` does _not_ log in the Command Log

## History

| Version                                    | Changes                 |
| ------------------------------------------ | ----------------------- |
| [0.14.0](/app/references/changelog#0-14-0) | Added `timeout` option  |
| [< 0.3.3](/app/references/changelog#0-3-3) | `.then()` command added |

## See also

- [`.and()`](/api/commands/and)
- [`.each()`](/api/commands/each)
- [`.invoke()`](/api/commands/invoke)
- [`.its()`](/api/commands/its)
- [`.should()`](/api/commands/should)
- [`.spread()`](/api/commands/spread)
- [Guide: Using Closures to compare values](/app/core-concepts/variables-and-aliases#Closures)
- [Guide: Chains of Commands](/app/core-concepts/introduction-to-cypress#Chains-of-Commands)