New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: Add TypeScript support for Cypress action events #1187
Changes from 1 commit
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -172,6 +172,8 @@ declare namespace Cypress { | |
Server: { | ||
defaults(options: Partial<ServerOptions>): void | ||
} | ||
|
||
on: Actions | ||
} | ||
|
||
/** | ||
|
@@ -600,6 +602,12 @@ declare namespace Cypress { | |
*/ | ||
not(selector: string, options?: Partial<Loggable & Timeoutable>): Chainable<JQuery> | ||
|
||
/** | ||
* These events come from Cypress as it issues commands and reacts to their state. These are all useful to listen to for debugging purposes. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
on: Actions | ||
|
||
/** | ||
* Get the parent DOM element of a set of DOM elements. | ||
* | ||
|
@@ -2934,6 +2942,130 @@ declare namespace Cypress { | |
(fn: (currentSubject: Subject) => void): Chainable<Subject> | ||
} | ||
|
||
/** | ||
* These events come from the application currently under test (your application). These are the most useful events for you to listen to. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
interface Actions { | ||
/** | ||
* Fires when an uncaught exception occurs in your application. | ||
* Cypress will fail the test when this fires. | ||
* Return `false` from this event and Cypress will not fail the test. Also useful for debugging purposes because the actual `error` instance is provided to you. | ||
* @example | ||
* // likely want to do this in a support file | ||
* // so it's applied to all spec files | ||
* // cypress/support/index.js | ||
* | ||
* Cypress.on('uncaught:exception', (err, runnable) => { | ||
* // returning false here prevents Cypress from | ||
* // failing the test | ||
* return false | ||
* }) | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should there be linkability to individual events? Right now this will jump to the table of actions. Also I don't know if that is the official URL. I noticed the Cypress team use a redirect URL for Cypress commands. I couldn't find anything that matched that pattern ( |
||
*/ | ||
(action: 'uncaught:exception', fn: (error: Error, runnable: Mocha.IRunnable) => false | void): void | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The docs said it is the mocha runnable. I'm assuming this is the interface the docs meant There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I included an example only in this action. This action at least gives an template for other actions to have examples added. |
||
/** | ||
* Fires when your app calls the global `window.confirm()` method. | ||
* Cypress will auto accept confirmations. Return `false` from this event and the confirmation will be cancelled. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:confirm', fn: (text: string) => false | void): void | ||
/** | ||
* Fires when your app calls the global `window.alert()` method. Cypress will auto accept alerts. You cannot change this behavior. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:alert', fn: (text: string) => void): void | ||
/** | ||
* Fires as the page begins to load, but before any of your applications JavaScript has executed. This fires at the exact same time as `cy.visit()` `onBeforeLoad` callback. Useful to modify the window on a page transition. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:before:load', fn: (win: Window) => void): void | ||
/** | ||
* Fires after all your resources have finished loading after a page transition. This fires at the exact same time as a `cy.visit()` `onLoad` callback. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:load', fn: (win: Window) => void): void | ||
/** | ||
* Fires when your application is about to navigate away. The real event object is provided to you. Your app may have set a `returnValue` on the event, which is useful to assert on. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:before:unload', fn: (event: BeforeUnloadEvent) => void): void | ||
/** | ||
* Fires when your application is has unloaded and is navigating away. The real event object is provided to you. This event is not cancelable. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'window:unload', fn: (event: Event) => void): void | ||
/** | ||
* Fires whenever Cypress detects that your application's URL has changed. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'url:changed', fn: (url: string) => void): void | ||
/** | ||
* Fires when the test has failed. It is technically possible to prevent the test from actually failing by binding to this event and invoking an async `done` callback. However this is **strongly discouraged**. Tests should never legitimately fail. This event exists because it's extremely useful for debugging purposes. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'fail', fn: (error: Error, mocha: Mocha.IRunnable) => void): void | ||
/** | ||
* Fires whenever the viewport changes via a `cy.viewport()` or naturally when Cypress resets the viewport to the default between tests. Useful for debugging purposes. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'viewport:changed', fn: (viewport: Viewport) => void): void | ||
/** | ||
* Fires whenever **Cypress** is scrolling your application. This event is fired when Cypress is {% url 'waiting for and calculating actionability' interacting-with-elements %}. It will scroll to 'uncover' elements currently being covered. This event is extremely useful to debug why Cypress may think an element is not interactive. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'scrolled', fn: ($el: JQuery) => void): void | ||
/** | ||
* Fires when a cy command is first invoked and enqueued to be run later. Useful for debugging purposes if you're confused about the order in which commands will execute. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'command:enqueued', fn: (command: EnqueuedCommand) => void): void | ||
/** | ||
* Fires when cy begins actually running and executing your command. Useful for debugging and understanding how the command queue is async. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'command:start', fn: (command: CommandQueue) => void): void | ||
/** | ||
* Fires when cy finishes running and executing your command. Useful for debugging and understanding how commands are handled. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'command:end', fn: (command: CommandQueue) => void): void | ||
/** | ||
* Fires whenever a command begins its retrying routines. This is called on the trailing edge after Cypress has internally waited for the retry interval. Useful to understand **why** a command is retrying, and generally includes the actual error causing the retry to happen. When commands fail the final error is the one that actually bubbles up to fail the test. This event is essentially to debug why Cypress is failing. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'command:retry', fn: (command: CommandQueue) => void): void | ||
/** | ||
* Fires whenever a command emits this event so it can be displayed in the Command Log. Useful to see how internal cypress commands utilize the {% url 'Cypress.log()' cypress-log %} API. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'log:added', fn: (log: any, interactive: boolean) => void): void | ||
/** | ||
* Fires whenever a command's attributes changes. This event is debounced to prevent it from firing too quickly and too often. Useful to see how internal cypress commands utilize the {% url 'Cypress.log()' cypress-log %} API. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'log:changed', fn: (log: any, interactive: boolean) => void): void | ||
/** | ||
* Fires before the test and all **before** and **beforeEach** hooks run. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'test:before:run', fn: (attributes: ObjectLike, test: Mocha.ITest) => void): void | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It was hard to tell what this object might look like. I couldn't find a clear emitter of this event. I found emitting of the |
||
/** | ||
* Fires after the test and all **afterEach** and **after** hooks run. | ||
* @see https://docs.cypress.io/api/events/catalog-of-events.html#App-Events | ||
*/ | ||
(action: 'test:after:run', fn: (attributes: ObjectLike, test: Mocha.ITest) => void): void | ||
} | ||
|
||
// $CommandQueue from `command_queue.coffee` - a lot to type. Might be more useful if it was written in TS | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I didn't spend too much time fleshing out this entire interface. There is some implicit method definitions that come straight from lodash. I don't know if it is worth the effort before There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. absolutely, looks good |
||
interface CommandQueue extends ObjectLike { | ||
logs(filters: any): any | ||
add(obj: any): any | ||
get(): any | ||
toJSON(): string[] | ||
create(): CommandQueue | ||
} | ||
|
||
/** | ||
* The clock starts at the unix epoch (timestamp of 0). This means that when you instantiate new Date in your application, it will have a time of January 1st, 1970. | ||
*/ | ||
|
@@ -2960,6 +3092,14 @@ declare namespace Cypress { | |
expiry?: string | ||
} | ||
|
||
interface EnqueuedCommand { | ||
name: string | ||
args: any[] | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. yes |
||
type: string | ||
chainerId: string | ||
fn(...args: any[]): any | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I didn't dig far enough to find out what the shape of this was |
||
} | ||
|
||
interface Exec { | ||
code: number | ||
stdout: string | ||
|
@@ -2994,6 +3134,11 @@ declare namespace Cypress { | |
whitelist: (xhr: any) => boolean | ||
} | ||
|
||
interface Viewport { | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I found this in |
||
viewportWidth: number | ||
viewportHeight: number | ||
} | ||
|
||
interface WaitXHR { | ||
duration: number | ||
id: string | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
Cypress.on('uncaught:exception', (error, runnable) => { | ||
error // $ExpectType Error | ||
runnable // $ExpectType IRunnable | ||
}) | ||
|
||
Cypress.on('window:confirm', (text) => { | ||
text // $ExpectType string | ||
}) | ||
|
||
Cypress.on('window:alert', (text) => { | ||
text // $ExpectType string | ||
}) | ||
|
||
Cypress.on('window:before:load', (win) => { | ||
win // $ExpectType Window | ||
}) | ||
|
||
Cypress.on('window:load', (win) => { | ||
win // $ExpectType Window | ||
}) | ||
|
||
Cypress.on('window:before:unload', (event) => { | ||
event // $ExpectType BeforeUnloadEvent | ||
}) | ||
|
||
Cypress.on('window:unload', (event) => { | ||
event // $ExpectType Event | ||
}) | ||
|
||
Cypress.on('url:changed', (url) => { | ||
url // $ExpectType string | ||
}) | ||
|
||
Cypress.on('fail', (error, mocha) => { | ||
error // $ExpectType Error | ||
mocha // $ExpectType IRunnable | ||
}) | ||
|
||
Cypress.on('viewport:changed', (viewport) => { | ||
viewport // $ExpectType Viewport | ||
}) | ||
|
||
Cypress.on('scrolled', ($el) => { | ||
$el // $ExpectType JQuery<HTMLElement> | ||
}) | ||
|
||
Cypress.on('command:enqueued', (command) => { | ||
command // $ExpectType EnqueuedCommand | ||
}) | ||
|
||
Cypress.on('command:start', (command) => { | ||
command // $ExpectType CommandQueue | ||
}) | ||
|
||
Cypress.on('command:end', (command) => { | ||
command // $ExpectType CommandQueue | ||
}) | ||
|
||
Cypress.on('command:retry', (command) => { | ||
command // $ExpectType CommandQueue | ||
}) | ||
|
||
Cypress.on('log:added', (log, interactive: boolean) => { | ||
log // $ExpectTyped any | ||
}) | ||
|
||
Cypress.on('log:changed', (log, interactive: boolean) => { | ||
log // $ExpectTyped any | ||
}) | ||
|
||
Cypress.on('test:before:run', (attributes , test) => { | ||
attributes // $ExpectType ObjectLike | ||
test // $ExpectType ITest | ||
}) | ||
|
||
Cypress.on('test:after:run', (attributes , test) => { | ||
attributes // $ExpectType ObjectLike | ||
test // $ExpectType ITest | ||
}) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One thing we REALLY do not want is to put direct urls to any resource, because these are likely to change. The same url should go through our
on.cypress.io
redirect service. Usually it is just document title, this url would behttps://on.cypress.io/catalog-of-events#App-Events
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh. Thanks. That was one of my review comments. I was trying to figure out what the redirect URL was
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Updated the URLs. Is there a conventions for those URL redirects? I tried a few including
https://on.cypress.io/events/catalog-of-events#App-Events