Cypress Wait Frames

Cypress command to wait for any CSS/DOM property to be idle after a specified number of frames.

Installation

pnpm add cypress-wait-frames

Import the package in your commands.js:

import 'cypress-wait-frames'

If using TypeScript, optionally install the latest version of csstype for CSS properties autocompletion:

pnpm add -D csstype

Do I need this?

Cypress retry ability on built-in assertions is very powerful and most likely you don't need this package or to use cy.wait. For example:

cy.scrollTo(0, 1200)

// No need for cy.wait(t) to make sure scroll is completed

cy.window().eq('scrollY').should('be.approximately', 1200, 2) // Will retry until it passes

Documentation on retry-ability is very detailed and it might already contain the answer you're looking for.

When I find it useful

There are cases where it's very hard to retain retry-ability and you might find yourself guessing timings using cy.wait or increasing the retry-ability timeout.

For example when asserting properties not available within Cypress queries:

cy.get('h1').eq(15).scrollIntoView()

// Need to add cy.wait(t) to make sure scroll is completed

cy.get('h1')
  .eq(15)
  .then((el) => {
    cy.wrap(el[0].getBoundingClientRect().top).should('be.approximately', 0, 2)
  })

But scenarios can be disparate and more complex. Bottom line is that if you find yourself using cy.wait() as last resort to obtain values or to wait for DOM/CSS properties to be idle, this package might be useful.

Usage

Window

cy.waitFrames({
  subject: cy.window,
  property: 'outerWidth'
})

cy.log('Resized!') // Executed once 'outerWidth' isn't changed for 20 frames (default).

DocumentElement

cy.waitFrames({
  subject: () => cy.get('html'),
  property: 'clientWidth',
  frames: 10
})

cy.log('Resized!') // Executed once 'clientWidth' isn't changed for 10 frames.

HTMLElement / SVGElement

cy.waitFrames({
  subject: () => cy.get('a').eq(0),
  property: 'getBoundingClientRect.top'
}).then(([{ value }]) => {
  cy.wrap(value).should('be.approximately', 0, 2) // Asserts that top is 0 after 20 frames (default).
})

Options

| Property | Default | Type | Description | Required | | ---------- | ---------- | --------------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------ | | subject | undefined | () => Cypress.Chainable<Cypress.AutWindow \| JQuery<HTMLElement \| SVGElement>> | Subject to watch. | :white_check_mark: | | property | undefined | string \| string[] | One or more properties to watch. | :white_check_mark: | | frames | 20 | number | Number of frames to wait. | :x: | | timeout | 30 * 1000 | number | Timeout in milliseconds before the command should fail. | :x: |

Yields

A Cypress Promise which resolves to an array of objects (one for each property) or throws an error if timeout is reached:

| Property | Type | Description | | ---------- | ---------------------------- | ----------------------------------------------- | | subject | AUTWindow | HTMLElement | Subject yielded from subject option chainer. | | value | Primitive | Property value at which the function resolved. | | property | string | Awaited property name. | | time | DOMHighResTimestamp | Time in ms that took to resolve since invoking. |

Properties

DOM properties

cy.waitFrames({
  subject: () => cy.get('html'),
  property: 'clientWidth'
})

CSS properties

cy.waitFrames({
  subject: () => cy.get('#my-element'),
  property: 'background-color'
})

:bulb: Use kebab-case for CSS properties. getComputedStyle is used internally to get the values.

Nested properties / methods

You can watch for methods or objects maximum 1 nested property which returns a primitive.

cy.waitFrames({
  subject: cy.window,
  property: 'visualViewport.offsetTop'
})

cy.waitFrames({
  subject: () => cy.get('a').eq(0),
  property: 'getBoundingClientRect.top'
})

:warning: Methods with arity greater than 0 are not supported, (e.g. getAttribute('href')).

Mixed properties / methods

You can watch for multiple properties as well, waitFrames will resolve once all properties are idle:

cy.waitFrames({
  subject: () => cy.get('a').eq(0),
  property: ['background-color', 'scrollTop', 'getBoundingClientRect.top']
})

License

MIT