Skip to content

Commit e4e2544

Browse files
committed
docs: Add documentation for using child/dual commands in TS
1 parent 99f3921 commit e4e2544

File tree

1 file changed

+79
-0
lines changed

1 file changed

+79
-0
lines changed

content/guides/tooling/typescript-support.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,14 @@ by any users of your custom command.
120120

121121
</Alert>
122122

123+
<Alert type="info">
124+
125+
Please note, types of all the parameters taken by implementation callback are
126+
inferred automatically based on declared interface. Thus, in the example above
127+
the `value` will be of type `string` implicitly.
128+
129+
</Alert>
130+
123131
In your specs, you can now use the custom command as expected
124132

125133
```typescript
@@ -132,6 +140,77 @@ it('works', () => {
132140
})
133141
```
134142

143+
#### Adding child or dual commands
144+
145+
When you add a custom command with `prevSubject` Cypress will infer subject type
146+
automatically based on kind of specified `prevSubject`(s)
147+
148+
```typescript
149+
// in cypress/support/index.ts
150+
// load type definitions that come with Cypress module
151+
/// <reference types="cypress" />
152+
153+
declare global {
154+
namespace Cypress {
155+
interface Chainable {
156+
/**
157+
* Custom command to type few random words into input elements
158+
* @param count=3
159+
* @example cy.get('input').typeRandomWords()
160+
*/
161+
typeRandomWords(count?: number, options?: Partial<TypeOptions>): Chainable<Element>
162+
}
163+
}
164+
}
165+
```
166+
167+
```typescript
168+
// cypress/support/index.ts
169+
Cypress.Commands.add('typeRandomWords', {prevSubject: 'element'}, (
170+
subject /* :JQuery<HTMLElement> */, count = 3, options?,
171+
) => {
172+
return cy.wrap(subject).type(generateRandomWords(cound), options)
173+
})
174+
```
175+
176+
177+
#### Overwriting child or dual commands
178+
179+
When overwriting either built-in or custom commands which make use of `prevSubject`
180+
you have to help the type-checker to understand this.
181+
182+
```typescript
183+
interface TypeOptions extends Cypress.TypeOptions {
184+
sensitive: boolean
185+
}
186+
187+
Cypress.Commands.overwrite<'type', 'element'>('type', (
188+
originalFn, element, text, options?: Partial<TypeOptions>,
189+
) => {
190+
if (options && options.sensitive) {
191+
// turn off original log
192+
options.log = false
193+
// create our own log with masked message
194+
Cypress.log({
195+
$el: element,
196+
name: 'type',
197+
message: '*'.repeat(text.length),
198+
})
199+
}
200+
201+
return originalFn(element, text, options)
202+
})
203+
```
204+
205+
As you can see there are generic parameters `<'type', 'element'>` are used:
206+
207+
1. This is the command name, should equal to actual first parameter passed to `cy.overwite`
208+
2. Type of prevSubject that is used by the original command. Possible values:
209+
- 'element' will infer second param as `JQuery<HTMLElement>`
210+
- 'window' will infer second param as `Window`
211+
- 'document' will infer second param as `Document`
212+
- 'optional' will infer second param as `unknown`
213+
135214
#### Examples:
136215

137216
- Find

0 commit comments

Comments
 (0)