Skip to content

Commit 4d8bb53

Browse files
smastromsmastrom
committed
edit README
1 parent e7ee8db commit 4d8bb53

File tree

1 file changed

+50
-108
lines changed

1 file changed

+50
-108
lines changed

‎README.md

+50-108
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ import 'cypress-wait-frames'
2121

2222
<br />
2323

24-
If using TypeScript, install the latest version of [csstype](https://www.npmjs.com/package/csstype) for CSS properties autocompletion:
24+
If using TypeScript, optionally install the latest version of [csstype](https://www.npmjs.com/package/csstype) for CSS properties autocompletion:
2525

2626
```bash
2727
pnpm add -D csstype
@@ -45,9 +45,9 @@ Documentation on [retry-ability](https://docs.cypress.io/guides/core-concepts/re
4545

4646
<br />
4747

48-
## When to use it
48+
## When I find it useful
4949

50-
There are cases where it's impossible to retain retry-ability and you might find yourself guessing timings using `cy.wait`.
50+
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.
5151

5252
For example when asserting properties not available within Cypress queries:
5353

@@ -63,120 +63,67 @@ cy.get('h1')
6363
})
6464
```
6565

66-
Or when futher assertions must rely on 100% accurate values:
67-
68-
```js
69-
cy.get('#TriggerComplexTransition').click()
70-
71-
// Need to add cy.wait(t) to make sure desktopHeight is accurate
72-
73-
cy.viewport('macbook-15').get('#TransitionedElement').invoke('height').as('desktopHeight')
74-
75-
cy.get('@desktopHeight').then((desktopHeight) => {
76-
cy.viewport('ipad-2')
77-
.get('#TransitionedElement')
78-
.invoke('height')
79-
.should('be.equal', desktopHeight / 2)
80-
})
81-
```
82-
83-
But scenarios can be disparate and more complex. Bottom line is that if you find yourself using `cy.wait()` as last resort, this package might be for you.
66+
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 wait for DOM/CSS properties to be idle, this package might be for you.
8467

8568
<br />
8669

8770
## Usage
8871

89-
Instead of guessing timings using `cy.wait` you can use `cy.waitFrames` to wait for a one or more properties to be idle after a specified number of frames.
90-
91-
Specify a `subject` to watch, one or more `property` and a number of `frames`. Command will resolve once queried properties haven't changed for that number of frames.
72+
### Window
9273

9374
```js
94-
cy.get('h1').eq(15).scrollIntoView()
95-
9675
cy.waitFrames({
97-
subject: () => cy.get('h1').eq(15),
98-
property: 'getBoundingClientRect.top',
99-
frames: 20 // Wait for the property to be idle for 20 frames
100-
}).then(([{ value }]) => {
101-
cy.wrap(value).should('be.approximately', 0, 2) // Passes in any environment
102-
})
103-
```
104-
105-
You can also use it to just to wait for a property to be idle:
106-
107-
```js
108-
Cypress.Commands.add('waitForResize', () => {
109-
cy.waitFrames({
110-
subject: cy.window,
111-
property: 'outerWidth',
112-
frames: 20
113-
})
76+
subject: cy.window,
77+
property: 'outerWidth'
11478
})
115-
```
116-
117-
```js
118-
cy.waitForResize()
11979

120-
cy.log('Resized!') // This is executed once outerWidth isn't changed for 20 frames.
80+
cy.log('Resized!') // Executed once 'outerWidth' isn't changed for 20 frames (default).
12181
```
12282

123-
### Options
124-
125-
| Property | Default | Type | Description | Required |
126-
| ---------- | ---------- | ------------------- | ---------------------------------- | ------------------ |
127-
| `subject` | undefined | () => Chainable\<T> | Chainable to watch for properties. | :white_check_mark: |
128-
| `property` | undefined | string \| string[] | One or more properties to watch. | :white_check_mark: |
129-
| `frames` | 20 | number | Number of frames to wait. | :x: |
130-
| `timeout` | 30 \* 1000 | number | Timeout in milliseconds. | :x: |
131-
132-
<br />
133-
134-
## Yields
135-
136-
A [Cypress Promise](https://docs.cypress.io/api/utilities/promise) which resolves to an array of objects (one for each property) or throws an error if `timeout` is reached:
137-
138-
| Property | Type | Description |
139-
| ---------- | ------------------------------------------------------------------- | ----------------------------------------------- |
140-
| `subject` | `AUTWindow` \| `Document` \| `HTMLElement` \| `JQuery<HTMLElement>` | Subject yielded from `subject` option chainer. |
141-
| `value` | `string \| number` \| `null` \| `undefined` | Property value at which the function resolved. |
142-
| `property` | `string` | Awaited property name. |
143-
| `time` | `DOMHighResTimestamp` | Time in ms that took to resolve since invoking. |
144-
145-
<br />
146-
147-
## Subjects
148-
149-
### Window
83+
### DocumentElement
15084

15185
```js
15286
cy.waitFrames({
153-
subject: cy.window
87+
subject: () => cy.get('html'),
88+
property: 'clientWidth',
89+
frames: 10
15490
})
155-
```
15691

157-
:bulb: Use `cy.window` to watch for _window-only_ DOM properties like `scrollY` or `outerWidth`.
92+
cy.log('Resized!') // Executed once 'clientWidth' isn't changed for 10 frames.
93+
```
15894

159-
### DocumentElement / HTML
95+
### HTMLElement / SVGElement
16096

16197
```js
16298
cy.waitFrames({
163-
subject: cy.document
99+
subject: () => cy.get('a').eq(0),
100+
property: 'getBoundingClientRect.top'
101+
}).then(([{ value }]) => {
102+
cy.wrap(value).should('be.approximately', 0, 2) // Asserts that top is 0 after 20 frames (default).
164103
})
165104
```
166105

167-
:bulb: Use `cy.document` to watch for DOM/CSS properties on the `documentElement` such as `clientWidth`, `pointer-events`, `overflow` etc.
106+
### Options
168107

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

171-
```js
172-
cy.waitFrames({
173-
subject: () => cy.get('a').eq(0) // or () => cy.get('.my-selector')
174-
})
175-
```
115+
<br />
116+
117+
## Yields
176118

177-
:bulb: Use `() => cy.get` to watch for DOM/CSS properties on any other HTMLElement.
119+
A [Cypress Promise](https://docs.cypress.io/api/utilities/promise) which resolves to an array of objects (one for each property) or throws an error if `timeout` is reached:
178120

179-
:warning: When using `cy.get`, make sure to pass a function which returns the chainable.
121+
| Property | Type | Description |
122+
| ---------- | ---------------------------- | ----------------------------------------------- |
123+
| `subject` | `AUTWindow` \| `HTMLElement` | Subject yielded from `subject` option chainer. |
124+
| `value` | `Primitive` | Property value at which the function resolved. |
125+
| `property` | `string` | Awaited property name. |
126+
| `time` | `DOMHighResTimestamp` | Time in ms that took to resolve since invoking. |
180127

181128
<br />
182129

@@ -186,25 +133,25 @@ cy.waitFrames({
186133

187134
```js
188135
cy.waitFrames({
189-
subject: cy.window,
190-
property: 'scrollY',
191-
frames: 10
136+
subject: () => cy.get('html'),
137+
property: 'clientWidth'
192138
})
193139
```
194140

195141
### CSS properties
196142

197143
```js
198144
cy.waitFrames({
199-
subject: () => cy.get('.my-element'),
200-
property: 'background-color', // or '--my-var'
201-
frames: 10
145+
subject: () => cy.get('#my-element'),
146+
property: 'background-color'
202147
})
203148
```
204149

205-
:bulb: Use _kebab-case_ for CSS properties. `getComputedStyle` is used internally to get the values.
150+
:bulb: Use _kebab-case_ for CSS properties. [getComputedStyle](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle) is used internally to get the values.
151+
152+
### Nested properties / methods
206153

207-
### Objects / methods properties
154+
You can watch for methods or objects **maximum 1 nested property** which returns a primitive.
208155

209156
```js
210157
cy.waitFrames({
@@ -215,29 +162,24 @@ cy.waitFrames({
215162

216163
```js
217164
cy.waitFrames({
218-
subject: () => cy.get('.my-element'),
165+
subject: () => cy.get('a').eq(0),
219166
property: 'getBoundingClientRect.top'
220167
})
221168
```
222169

223-
:warning: Bear in mind that only methods or objects with **maximum 1 property** which returns a primitive are supported.
170+
:warning: Methods with arity greater than 0 are not supported, (e.g. `getAttribute('href')`).
224171

225-
Methods with arity greater than 0 are not supported, _e.g. `getAttribute('href')`_.
172+
### Mixed properties / methods
226173

227-
### Multiple properties / methods
228-
229-
You can watch for multiple properties as well:
174+
You can watch for multiple properties as well, `waitFrames` will resolve once all properties are idle:
230175

231176
```js
232177
cy.waitFrames({
233-
subject: () => cy.get('.my-element'),
234-
property: ['background-color', 'scrollTop', 'getBoundingClientRect.top'],
235-
frames: 10
178+
subject: () => cy.get('a').eq(0),
179+
property: ['background-color', 'scrollTop', 'getBoundingClientRect.top']
236180
})
237181
```
238182

239-
:bulb: `waitFrames` will resolve once all properties are idle.
240-
241183
<br />
242184

243185
## License

0 commit comments

Comments
 (0)