# cypress-promise

> Convert a Cypress chain into a promise for use with async/await

Latest version **1.1.0** (published 2020-02-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install cypress-promise
pnpm add cypress-promise
yarn add cypress-promise
bun add cypress-promise
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2020-02-10 |
| First published | 2018-04-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 7.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 99 |
| Author | Nicholas Boll |
| Maintainers | nicholasboll |
| Keywords | cypress, promise, async, await |

## Links

- npm: https://www.npmjs.com/package/cypress-promise
- Repository: https://github.com/NicholasBoll/cypress-promise
- Homepage: https://github.com/NicholasBoll/cypress-promise#readme
- Issues: https://github.com/NicholasBoll/cypress-promise/issues
- npm.io page: https://npm.io/package/cypress-promise

## Alternatives

- [promise-throttle](https://npm.io/package/promise-throttle.md) — 44.2K weekly downloads
- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2020-02-10
- 1.0.2 — 2018-04-02
- 1.0.1 — 2018-04-01
- 1.0.0 — 2018-04-01

## README

# Cypress Promise

This library promises to convert a Cypress chain into a real promise, which is required to use `async`/`await` in a Cypress test. This library is experimental and doesn't work inside a `before` or `beforeEach` block.

```ts
import promisify from 'cypress-promise'

it('should run tests with async/await', async () => {
  const foo = await promisify(cy.wrap('foo'))
  const bar = await promisify(cy.wrap('bar'))

  expect(foo).to.equal('foo')
  expect(bar).to.equal('bar')
})
```

An alternative it to use the 'register' polyfill to add `promisify` method to all Cypress chains. This requires `import 'cypress-promise/register'` in your `cypress/support/index` file:

```ts
it('should run tests with async/await', async () => {
  const foo = await cy.wrap('foo').promisify()
  const bar = await cy.wrap('bar').promisify()

  expect(foo).to.equal('foo')
  expect(bar).to.equal('bar')
}
```

Without this library and the `promisify` function/method, the expectation of `bar` would fail with `expected undefined to equal 'bar'`

## Why use this library?
The question about how to use async/await in Cypress test comes up from time to time in the gitter chat as well as in [GitHub Issue #1417](https://github.com/cypress-io/cypress/issues/1417). Sometimes you needs a value out of a chain and using `.then` just increases the nesting level, decreasing readability:

```ts
cy.get('.mySelector')
  .then($el => $el.text())
  .then(text => {
    // do some more commands using this text
    cy.get('.someOtherSelector')
      .then($el => $el.text())
      .should('equal', text)
```

[Aliases](https://docs.cypress.io/guides/core-concepts/variables-and-aliases.html) don't help much in this case - we still have to nest. Ideally you'd want to write the following:

```ts
const text = await cy.get('.mySelector').then($el => $el.text())

// do some more commands using this text
cy.get('.someOtherSelector')
  .then($el => $el.text())
  .should('equal', text)
```

Since [Commands are not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises), that code won't work. This library uses aliases and Cypress life-cycle events to force Cypress to play nicely with Promises:

```ts
import promisify from 'cypress-promise'

const text = await promisify(cy
  .get('.mySelector')
  .then($el => $el.text())
)

// do some more commands using this text
cy.get('.someOtherSelector')
  .then($el => $el.text())
  .should('equal', text)
```

## Best Practices
Cypress chains are powerful and declarative. [Custom Commands](https://medium.com/@NicholasBoll/cypress-io-scaling-e2e-testing-with-custom-commands-6b72b902aab) can be used to chain functions together that read like a series of steps without much extra syntax. Most Cypress commands work on elements and `await`ing them means all you can really do is `cy.wrap` them again. Only use `await` for non-element subjects that need to be used as inputs for other commands.

```ts
// very bad
const body = await promisify(cy.get('body'))
body.click() // This will use jQuery's click instead of Cypress's click, losing the power of Cypress

// bad
const el = await promisify(cy.get('.someSelector'))
// later
cy.wrap(el).click()

// good - use alias for elements. It makes sense and works with Type definitions
cy.get('.someSelector').as('someElement')
// later
cy.get('@someElement').click()

// good - use awaited promises for values to be used in chains
const text = await promisify(cy
  .get('.someSelector')
  .then(el => el.text())
)
cy.get('.someInput').type(text)
```

## Caveats
* `.promisify()` doesn't currently work inside `before` or `beforeEach` blocks. This is tracked by #1
* Cypress throws a warning about using Promises - on every use.
* `promisify()` is extra syntax - it can be easy to forget to call it.
* `.promisify()` will end the chain and return a Promise instead of a Chain, meaning you cannot chain further off of this method. When you think about it, this makes perfect sense, but could trip people up.
* You can't run Cypress commands inside a Promise's `.then` or `.catch`. Cypress will throw an error. I'm not sure it would make sense even if Cypress allowed it.

## Installation
```
npm install cypress-promise -D
```

If you get errors like "regeneratorRuntime is not defined.", you'll have to install `babel-polyfill` and add `import 'babel-polyfill'` to your `cypress/support/index`.

If you want to use the `cy.promisify()`, you'll have to add the following to your `cypress/support/index` file:

```ts
import 'cypress-promise/register'
```

---
_Source: https://npm.io/package/cypress-promise · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
