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

---
title: 'invoke | Cypress Documentation'
description: Invoke a function on the previously yielded subject in Cypress.
sidebar_label: invoke
slug: /api/commands/invoke
---

<ProductHeading product="app" />

# invoke

Invoke a function on the previously yielded subject.

:::info

If you want to get a property that is not a function on the previously yielded
subject, use [`.its()`](/api/commands/its).

:::

:::caution

If you chain further commands off of `.invoke()`, it will be called multiple
times. If you only want the method to be called once, end your chain with
`.invoke()` and start fresh with `cy` afterwards.

:::

## Syntax

```javascript
.invoke(functionName)
.invoke(options, functionName)
.invoke(functionName, args...)
.invoke(options, functionName, args...)

```

### Usage

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

```javascript
cy.get('.input').invoke('val').should('eq', 'foo') // Invoke the 'val' function
cy.get('.modal').invoke('show') // Invoke the jQuery 'show' function
cy.wrap({ animate: fn }).invoke('animate') // Invoke the 'animate' function
```

<Icon name="exclamation-triangle" color="red" /> **Incorrect Usage**

```javascript
cy.invoke('convert') // Errors, cannot be chained off 'cy'
cy.wrap({ name: 'Jane' }).invoke('name') // Errors, 'name' is not a function
cy.wrap({ animate: fn })
  .invoke('animate')
  .then(() => {}) // 'animate' will be called multiple times
```

### Arguments

<Icon name="angle-right" /> **functionName _(String, Number)_**

Name of function to be invoked.

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

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

| Option    | Default                                                           | Description                                                                         |
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `log`     | `true`                                                            | Displays the command in the [Command log](/app/core-concepts/open-mode#Command-Log) |
| `timeout` | [`defaultCommandTimeout`](/app/references/configuration#Timeouts) | Time to wait for `.invoke()` to resolve before [timing out](#Timeouts)              |

<Icon name="angle-right" /> args...**

Additional arguments to be given to the function call. There is no limit to the
number of arguments.

<HeaderYields />

- `.invoke()` yields the return value of the method.
- `.invoke()` is a query, and it is _safe_ to chain further commands.
- If you chain additional commands off of `.invoke()`, the function will be
  called multiple times!

## Examples

### Function

#### Assert on a function's return value

```javascript
const fn = () => {
  return 'bar'
}

cy.wrap({ foo: fn }).invoke('foo').should('eq', 'bar') // true
```

#### Use `.invoke()` to test HTML content

:::info

[Check out our example recipe where we use `cy.invoke('text')` to test against HTML content in 'Bootstrapping your App'](/app/references/recipes#Server-Communication)

:::

#### Properties that are functions are invoked

In the example below, we use `.invoke()` to force a hidden div to be
`'display: block'` so we can interact with its children elements.

```javascript
cy.get('div.container')
  .should('be.hidden') // element is hidden
  .invoke('show') // call jquery method 'show' on the '.container'
  .should('be.visible') // element is visible now
  .find('input') // drill down into a child "input" element
  .type('Cypress is great') // and type text
```

#### Use `.invoke('show')` and `.invoke('trigger')`

:::info

[Check out our example recipe where we use `cy.invoke('show')` and `cy.invoke('trigger')` to click an element that is only visible on hover](/app/references/recipes#Testing-the-DOM)

:::

### Function with Arguments

#### Send specific arguments to the function

```javascript
const fn = (a, b, c) => {
  return a + b + c
}

cy.wrap({ sum: fn })
  .invoke('sum', 2, 4, 6)
  .should('be.gt', 10) // true
  .and('be.lt', 20) // true
```

#### Use `cy.invoke('removeAttr', 'target')` to get around new tab

:::info

[Check out our example recipe where we use `cy.invoke('removeAttr', 'target')` to test clicking on a link without opening in a new tab](/app/references/recipes#Testing-the-DOM)

:::

#### Arguments are automatically forwarded to the function

```javascript
cy.get('img').invoke('attr', 'src').should('include', 'myLogo')
```

### Arrays

In the above examples, the subject was an object, but `cy.invoke` also works on
arrays and allows using numerical index to pick a function to run.

```javascript
const reverse = (s) => Cypress._.reverse(s)
const double = (n) => n * n

// picks function with index 1 and calls it with argument 4
cy.wrap([reverse, double]).invoke(1, 4).should('eq', 16)
```

### jQuery method

If the parent command yields a jQuery element, we can invoke a jQuery method,
like `attr`, `text`, or `val`. To confirm the element's `id` attribute for
example:

```html
<div id="code-snippet">The code example</div>
```

```js
cy.contains('The code example')
  .invoke('attr', 'id')
  .should('equal', 'code-snippet')
```

**Tip:** Cypress has a built-in Chai-jQuery assertion to confirm the attribute.
The above example can be written simply as:

```js
cy.contains('The code example').should('have.attr', 'id', 'code-snippet')
```

## Notes

### Third Party Plugins

#### Using a Kendo DropDown

If you are using `jQuery` then the `jQuery` wrapped elements will automatically
have your 3rd party plugins available to be called.

```javascript
cy.get('input')
  .invoke('getKendoDropDownList')
  .then((dropDownList) => {
    // yields the return of $input.getKendoDropDownList()
    return dropDownList.select('apples')
  })
```

We can rewrite the previous example in a more terse way and add an assertion.

```javascript
cy.get('input')
  .invoke('getKendoDropDownList')
  .invoke('select', 'apples')
  .invoke('val')
  .should('match', /apples/)
```

### Retries

`.invoke()` automatically retries invoking the specified method until the
returned value satisfies the attached assertions. The example below passes after
1 second.

```javascript
let message = 'hello'
const english = {
  greeting() {
    return message
  },
}

setTimeout(() => {
  message = 'bye'
}, 1000)

// initially the english.greeting() returns "hello" failing the assertion.
// .invoke('greeting') tries again and again until after 1 second
// the returned message becomes "bye" and the assertion passes
cy.wrap(english).invoke('greeting').should('equal', 'bye')
```

<DocsImage
  src="/img/api/invoke/invoke-retries.gif"
  alt="Invoke retries example"
  width-600
/>

## Rules

<HeaderRequirements />

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

<HeaderAssertions />

- `.invoke()` will wait for the `function` to exist on the subject before
  running.
- `.invoke()` will throw an error if the invoked `function` returns a promise.
  If you want to invoke a function that returns a promise, use [`.then()`](/api/commands/then) instead.
- `.invoke()` will automatically [retry](/app/core-concepts/retry-ability)
  until all chained assertions have passed.

<HeaderTimeouts />

- `.invoke()` can time out waiting for assertions you've added to pass.

## Command Log

**_Invoke jQuery show method on element_**

```javascript
cy.get('.connectors-div')
  .should('be.hidden')
  .invoke('show')
  .should('be.visible')
```

The commands above will display in the Command Log as:

<DocsImage
  src="/img/api/invoke/invoke-jquery-show-on-element-for-testing.png"
  alt="Command Log for invoke"
/>

When clicking on `invoke` within the command log, the console outputs the
following:

<DocsImage
  src="/img/api/invoke/log-function-invoked-and-return.png"
  alt="Console Log for invoke"
/>

## History

| Version                                    | Changes                                                       |
| ------------------------------------------ | ------------------------------------------------------------- |
| [12.0.0](/app/references/changelog#12-0-0) | `.invoke()` no longer supports promises or async functions    |
| [3.8.0](/app/references/changelog#3-8-0)   | Added support for `options` argument                          |
| [3.7.0](/app/references/changelog#3-7-0)   | Added support for arguments of type Number for `functionName` |

## See also

- [`.its()`](/api/commands/its)
- [`.then()`](/api/commands/then)
- [`cy.wrap()`](/api/commands/wrap)