cypress 4.12.1 → 5.3.0

package/types/cypress.d.ts

@@ -1,10 +1,10 @@
 declare namespace Cypress {
   type FileContents = string | any[] | object
-  type HistoryDirection = "back" | "forward"
+  type HistoryDirection = 'back' | 'forward'
   type HttpMethod = string
   type RequestBody = string | object
-  type ViewportOrientation = "portrait" | "landscape"
-  type PrevSubject = "optional" | "element" | "document" | "window"
+  type ViewportOrientation = 'portrait' | 'landscape'
+  type PrevSubject = 'optional' | 'element' | 'document' | 'window'
   type PluginConfig = (on: PluginEvents, config: PluginConfigOptions) => void | ConfigOptions | Promise<ConfigOptions>
 
   interface CommandOptions {
@@ -26,6 +26,7 @@ declare namespace Cypress {
      * @see https://on.cypress.io/firefox-gc-issue
      */
     (task: 'firefox:force:gc'): Promise<void>
+    (task: 'net', eventName: string, frame: any): Promise<void>
   }
 
   type BrowserName = 'electron' | 'chrome' | 'chromium' | 'firefox' | 'edge' | string
@@ -107,6 +108,24 @@ declare namespace Cypress {
     fromAutWindow: WindowPosition & { x: number, y: number }
   }
 
+  /**
+   * Spec type for the given test. "integration" is the default, but
+   * tests run using experimentalComponentTesting will be "component"
+   *
+   * @see https://on.cypress.io/experiments
+   */
+  type CypressSpecType = 'integration' | 'component'
+
+  /**
+   * Window type for Application Under Test(AUT)
+   */
+  type AUTWindow = Window & typeof globalThis & ApplicationWindow
+
+  /**
+   * The interface for user-defined properties in Window object under test.
+   */
+  interface ApplicationWindow {} // tslint:disable-line
+
   /**
    * Several libraries are bundled with Cypress by default.
    *
@@ -211,6 +230,7 @@ declare namespace Cypress {
     //  name: "config_passing_spec.coffee",
     //  relative: "cypress/integration/config_passing_spec.coffee",
     //  absolute: "/users/smith/projects/web/cypress/integration/config_passing_spec.coffee"
+    //  specType: "integration"
     // }
     ```
      */
@@ -219,6 +239,7 @@ declare namespace Cypress {
       relative: string // "cypress/integration/config_passing_spec.coffee" or "__all" if clicked all specs button
       absolute: string
       specFilter?: string // optional spec filter used by the user
+      specType?: CypressSpecType
     }
 
     /**
@@ -324,6 +345,11 @@ declare namespace Cypress {
      */
     getFirefoxGcInterval(): number | null | undefined
 
+    /**
+     * @returns the number of test retries currently enabled for the run
+     */
+    getTestRetries(): number | null
+
     /**
      * Checks if a variable is a valid instance of `cy` or a `cy` chainable.
      *
@@ -387,7 +413,7 @@ declare namespace Cypress {
        * Returns a boolean indicating whether an object is a DOM object.
        */
       isDom(obj: any): boolean
-      isType(element: JQuery | HTMLElement , type: string): boolean
+      isType(element: JQuery | HTMLElement, type: string): boolean
       /**
        * Returns a boolean indicating whether an element is visible.
        */
@@ -492,7 +518,7 @@ declare namespace Cypress {
     off: Actions
   }
 
-  type CanReturnChainable = void | Chainable
+  type CanReturnChainable = void | Chainable | Promise<unknown>
   type ThenReturn<S, R> =
     R extends void ? Chainable<S> :
     R extends R | undefined ? Chainable<S | Exclude<R, undefined>> :
@@ -1062,7 +1088,7 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/go
      */
-    go(direction: HistoryDirection | number, options?: Partial<Loggable & Timeoutable>): Chainable<Window>
+    go(direction: HistoryDirection | number, options?: Partial<Loggable & Timeoutable>): Chainable<AUTWindow>
 
     /**
      * Get the current URL hash of the page that is currently active.
@@ -1399,7 +1425,7 @@ declare namespace Cypress {
      * @example
      *    cy.reload()
      */
-    reload(options?: Partial<Loggable & Timeoutable>): Chainable<Window>
+    reload(options?: Partial<Loggable & Timeoutable>): Chainable<AUTWindow>
     /**
      * Reload the page without cache
      *
@@ -1410,7 +1436,7 @@ declare namespace Cypress {
      *    cy.visit('http://localhost:3000/admin')
      *    cy.reload(true)
      */
-    reload(forceReload: boolean): Chainable<Window>
+    reload(forceReload: boolean): Chainable<AUTWindow>
 
     /**
      * Make an HTTP GET request.
@@ -1581,15 +1607,12 @@ declare namespace Cypress {
 
     /**
      * Traverse into an element's shadow root.
-     * Requires `experimentalShadowDomSupport: true` config option
      *
-    @example
-    ```js
-    cy.get('.top-level > my-component')
-      .shadow()
-      .find('.my-button')
-      .click()
-    ```
+     * @example
+     *    cy.get('my-component')
+     *    .shadow()
+     *    .find('.my-button')
+     *    .click()
      * @see https://on.cypress.io/experimental
      */
     shadow(): Chainable<Subject>
@@ -1976,8 +1999,8 @@ declare namespace Cypress {
      *    })
      *
      */
-    visit(url: string, options?: Partial<VisitOptions>): Chainable<Window>
-    visit(options: Partial<VisitOptions> & { url: string }): Chainable<Window>
+    visit(url: string, options?: Partial<VisitOptions>): Chainable<AUTWindow>
+    visit(options: Partial<VisitOptions> & { url: string }): Chainable<AUTWindow>
 
     /**
      * Wait for a number of milliseconds.
@@ -2048,7 +2071,7 @@ declare namespace Cypress {
     })
     ```
      */
-    window(options?: Partial<Loggable & Timeoutable>): Chainable<Window>
+    window(options?: Partial<Loggable & Timeoutable>): Chainable<AUTWindow>
 
     /**
      * Scopes all subsequent cy commands to within this element.
@@ -2177,7 +2200,7 @@ declare namespace Cypress {
   type Agent<T extends sinon.SinonSpy> = SinonSpyAgent<T> & T
 
   interface CookieDefaults {
-    whitelist: string | string[] | RegExp | ((cookie: any) => boolean)
+    preserve: string | string[] | RegExp | ((cookie: any) => boolean)
   }
 
   interface Failable {
@@ -2276,7 +2299,7 @@ declare namespace Cypress {
      * @default {@link Timeoutable#timeout}
      * @see https://docs.cypress.io/guides/references/configuration.html#Timeouts
      */
-    requestTimeout: number,
+    requestTimeout: number
     /**
      * Time to wait for the response (ms)
      *
@@ -2319,6 +2342,54 @@ declare namespace Cypress {
      * @default false
      */
     multiple: boolean
+    /**
+     * Activates the control key during click
+     *
+     * @default false
+     */
+    ctrlKey: boolean
+    /**
+     * Activates the control key during click
+     *
+     * @default false
+     */
+    controlKey: boolean
+    /**
+     * Activates the alt key (option key for Mac) during click
+     *
+     * @default false
+     */
+    altKey: boolean
+    /**
+     * Activates the alt key (option key for Mac) during click
+     *
+     * @default false
+     */
+    optionKey: boolean
+    /**
+     * Activates the shift key during click
+     *
+     * @default false
+     */
+    shiftKey: boolean
+    /**
+     * Activates the meta key (Windows key or command key for Mac) during click
+     *
+     * @default false
+     */
+    metaKey: boolean
+    /**
+     * Activates the meta key (Windows key or command key for Mac) during click
+     *
+     * @default false
+     */
+    commandKey: boolean
+    /**
+     * Activates the meta key (Windows key or command key for Mac) during click
+     *
+     * @default false
+     */
+    cmdKey: boolean
   }
 
   interface ResolvedConfigOptions {
@@ -2353,7 +2424,12 @@ declare namespace Cypress {
      */
     reporter: string
     /**
-     * Whether to take a screenshot on test failure when running headlessly or in CI
+     * Some reporters accept [reporterOptions](https://on.cypress.io/reporters) that customize their behavior
+     * @default "spec"
+     */
+    reporterOptions: { [key: string]: any }
+    /**
+     * Whether Cypress will watch and restart tests on test file changes
      * @default true
      */
     watchForFileChanges: boolean
@@ -2406,7 +2482,7 @@ declare namespace Cypress {
      * If set to `system`, Cypress will try to find a `node` executable on your path to use when executing your plugins. Otherwise, Cypress will use the Node version bundled with Cypress.
      * @default "bundled"
      */
-    nodeVersion: "system" | "bundled"
+    nodeVersion: 'system' | 'bundled'
     /**
      * Path to plugins file. (Pass false to disable)
      * @default "cypress/plugins/index.js"
@@ -2488,18 +2564,12 @@ declare namespace Cypress {
      */
     waitForAnimations: boolean
     /**
-     * Firefox-only: The number of tests that will run between forced garbage collections.
+     * Firefox version 79 and below only: The number of tests that will run between forced garbage collections.
      * If a number is supplied, it will apply to `run` mode and `open` mode.
      * Set the interval to `null` or 0 to disable forced garbage collections.
      * @default { runMode: 1, openMode: null }
      */
     firefoxGcInterval: Nullable<number | { runMode: Nullable<number>, openMode: Nullable<number> }>
-    /**
-     * If `true`, Cypress will add `sameSite` values to the objects yielded from `cy.setCookie()`,
-     * `cy.getCookie()`, and `cy.getCookies()`. This will become the default behavior in Cypress 5.0.
-     * @default false
-     */
-    experimentalGetCookiesSameSite: boolean
     /**
      * Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement
      * algorithm.
@@ -2507,14 +2577,28 @@ declare namespace Cypress {
      */
     experimentalSourceRewriting: boolean
     /**
-     * Enables shadow DOM support. Adds the `cy.shadow()` command and
-     * the `includeShadowDom` option to some DOM commands.
+     * Enables `cy.route2`, which can be used to dynamically intercept/stub/await any HTTP request or response (XHRs, fetch, beacons, etc.)
+     * @default false
+     */
+    experimentalNetworkStubbing: boolean
+    /**
+     * Number of times to retry a failed test.
+     * If a number is set, tests will retry in both runMode and openMode.
+     * To enable test retries only in runMode, set e.g. `{ openMode: null, runMode: 2 }`
+     * @default null
+     */
+    retries: Nullable<number | {runMode: Nullable<number>, openMode: Nullable<number>}>
+    /**
+     * Enables including elements within the shadow DOM when using querying
+     * commands (e.g. cy.get(), cy.find()). Can be set globally in cypress.json,
+     * per-suite or per-test in the test configuration object, or programmatically
+     * with Cypress.config()
+     * @default false
      */
-    experimentalShadowDomSupport: boolean
+    includeShadowDom: boolean
   }
 
-  interface TestConfigOverrides extends Partial<Pick<ConfigOptions, 'baseUrl' | 'defaultCommandTimeout' | 'taskTimeout' | 'animationDistanceThreshold' | 'waitForAnimations' | 'viewportHeight' | 'viewportWidth' | 'requestTimeout' | 'execTimeout' | 'env' | 'responseTimeout'>> {
-    // retries?: number
+  interface TestConfigOverrides extends Partial<Pick<ConfigOptions, 'baseUrl' | 'defaultCommandTimeout' | 'taskTimeout' | 'animationDistanceThreshold' | 'waitForAnimations' | 'viewportHeight' | 'viewportWidth' | 'requestTimeout' | 'execTimeout' | 'env' | 'responseTimeout' | 'retries' | 'includeShadowDom'>> {
     browser?: IsBrowserMatcher | IsBrowserMatcher[]
   }
 
@@ -2614,18 +2698,18 @@ declare namespace Cypress {
     scale: boolean
     onBeforeScreenshot: ($el: JQuery) => void
     onAfterScreenshot: ($el: JQuery, props: {
-      path: string,
-      size: number,
+      path: string
+      size: number
       dimensions: {
-        width: number,
+        width: number
         height: number
-      },
-      multipart: boolean,
-      pixelRatio: number,
-      takenAt: string,
-      name: string,
-      blackout: string[],
-      duration: number,
+      }
+      multipart: boolean
+      pixelRatio: number
+      takenAt: string
+      name: string
+      blackout: string[]
+      duration: number
       testAttemptIndex: number
     }) => void
   }
@@ -2646,13 +2730,13 @@ declare namespace Cypress {
      *
      * @default 'swing'
      */
-    easing: 'swing' | 'linear',
+    easing: 'swing' | 'linear'
     /**
      * Ensure element is scrollable. Error if element is not scrollable
      *
      * @default true
      */
-    ensureScrollable: boolean,
+    ensureScrollable: boolean
   }
 
   interface ScrollIntoViewOptions extends ScrollToOptions {
@@ -2684,7 +2768,7 @@ declare namespace Cypress {
     enable: boolean
     force404: boolean
     urlMatchingOptions: object
-    whitelist(xhr: Request): void
+    ignore(xhr: Request): void
     onAnyRequest(route: RouteOptions, proxy: any): void
     onAnyResponse(route: RouteOptions, proxy: any): void
     onAnyAbort(route: RouteOptions, proxy: any): void
@@ -2701,6 +2785,10 @@ declare namespace Cypress {
     sameSite: SameSiteStatus
   }
 
+  interface ShadowDomOptions {
+    includeShadowDom?: boolean
+  }
+
   /**
    * Options that control `cy.type` command
    *
@@ -2783,16 +2871,16 @@ declare namespace Cypress {
     /**
      * Called before your page has loaded all of its resources.
      *
-     * @param {Window} contentWindow the remote page's window object
+     * @param {AUTWindow} contentWindow the remote page's window object
      */
-    onBeforeLoad(win: Window): void
+    onBeforeLoad(win: AUTWindow): void
 
     /**
      * Called once your page has fired its load event.
      *
-     * @param {Window} contentWindow the remote page's window object
+     * @param {AUTWindow} contentWindow the remote page's window object
      */
-    onLoad(win: Window): void
+    onLoad(win: AUTWindow): void
 
     /**
      * Cypress will automatically apply the right authorization headers
@@ -2831,6 +2919,12 @@ declare namespace Cypress {
      * @default true
      */
     cancelable: boolean
+    /**
+     * The type of the event you want to trigger
+     *
+     * @default 'Event'
+     */
+    eventConstructor: string
   }
 
   /** Options to change the default behavior of .writeFile */
@@ -4857,9 +4951,9 @@ declare namespace Cypress {
   }
 
   interface BrowserLaunchOptions {
-    extensions: string[],
+    extensions: string[]
     preferences: { [key: string]: any }
-    args: string[],
+    args: string[]
   }
 
   interface Dimensions {
@@ -4948,7 +5042,7 @@ declare namespace Cypress {
       })
     ```
      */
-    (action: 'uncaught:exception', fn: (error: Error, runnable: Mocha.IRunnable) => false | void): void
+    (action: 'uncaught:exception', fn: (error: Error, runnable: Mocha.Runnable) => false | void): void
     /**
      * 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 canceled.
@@ -4983,12 +5077,12 @@ declare namespace Cypress {
      * 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://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'window:before:load', fn: (win: Window) => void): void
+    (action: 'window:before:load', fn: (win: AUTWindow) => 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://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'window:load', fn: (win: Window) => void): void
+    (action: 'window:load', fn: (win: AUTWindow) => 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://on.cypress.io/catalog-of-events#App-Events
@@ -5008,7 +5102,7 @@ declare namespace Cypress {
      * 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://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'fail', fn: (error: Error, mocha: Mocha.IRunnable) => void): void
+    (action: 'fail', fn: (error: Error, mocha: Mocha.Runnable) => 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://on.cypress.io/catalog-of-events#App-Events
@@ -5053,16 +5147,16 @@ declare namespace Cypress {
      * Fires before the test and all **before** and **beforeEach** hooks run.
      * @see https://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'test:before:run', fn: (attributes: ObjectLike, test: Mocha.ITest) => void): void
+    (action: 'test:before:run', fn: (attributes: ObjectLike, test: Mocha.Test) => void): void
     /**
      * Fires before the test and all **before** and **beforeEach** hooks run. If a `Promise` is returned, it will be awaited before proceeding.
      */
-    (action: 'test:before:run:async', fn: (attributes: ObjectLike, test: Mocha.ITest) => void | Promise<any>): void
+    (action: 'test:before:run:async', fn: (attributes: ObjectLike, test: Mocha.Test) => void | Promise<any>): void
     /**
      * Fires after the test and all **afterEach** and **after** hooks run.
      * @see https://on.cypress.io/catalog-of-events#App-Events
      */
-    (action: 'test:after:run', fn: (attributes: ObjectLike, test: Mocha.ITest) => void): void
+    (action: 'test:after:run', fn: (attributes: ObjectLike, test: Mocha.Test) => void): void
   }
 
   // $CommandQueue from `command_queue.coffee` - a lot to type. Might be more useful if it was written in TS
@@ -5169,7 +5263,7 @@ declare namespace Cypress {
 
   interface Server extends RouteOptions {
     enable: boolean
-    whitelist: (xhr: any) => boolean
+    ignore: (xhr: any) => boolean
   }
 
   interface Viewport {
@@ -5200,10 +5294,10 @@ declare namespace Cypress {
   }
 
   type Encodings = 'ascii' | 'base64' | 'binary' | 'hex' | 'latin1' | 'utf8' | 'utf-8' | 'ucs2' | 'ucs-2' | 'utf16le' | 'utf-16le'
-  type PositionType = "topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
+  type PositionType = 'topLeft' | 'top' | 'topRight' | 'left' | 'center' | 'right' | 'bottomLeft' | 'bottom' | 'bottomRight'
   type ViewportPreset = 'macbook-15' | 'macbook-13' | 'macbook-11' | 'ipad-2' | 'ipad-mini' | 'iphone-xr' | 'iphone-x' | 'iphone-6+' | 'iphone-6' | 'iphone-5' | 'iphone-4' | 'iphone-3' | 'samsung-s10' | 'samsung-note9'
   interface Offset {
-    top: number,
+    top: number
     left: number
   }
 
@@ -5236,39 +5330,39 @@ declare namespace Cypress {
 declare namespace Mocha {
   interface TestFunction {
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test
 
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: AsyncFunc): Test
   }
   interface ExclusiveTestFunction {
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test
 
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: AsyncFunc): Test
   }
   interface PendingTestFunction {
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: Func): Test
 
         /**
-         * Describe a specification or test-case with the given `title`, TestCptions, and callback `fn` acting
+         * Describe a specification or test-case with the given `title`, TestOptions, and callback `fn` acting
          * as a thunk.
          */
         (title: string, config: Cypress.TestConfigOverrides, fn?: AsyncFunc): Test
@@ -5276,7 +5370,7 @@ declare namespace Mocha {
 
   interface SuiteFunction {
     /**
-     * Describe a "suite" with the given `title`, TestCptions, and callback `fn` containing
+     * Describe a "suite" with the given `title`, TestOptions, and callback `fn` containing
      * nested suites.
      */
     (title: string, config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite
@@ -5284,13 +5378,13 @@ declare namespace Mocha {
 
   interface ExclusiveSuiteFunction {
     /**
-     * Describe a "suite" with the given `title`, TestCptions, and callback `fn` containing
+     * Describe a "suite" with the given `title`, TestOptions, and callback `fn` containing
      * nested suites. Indicates this suite should be executed exclusively.
      */
     (title: string, config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite
   }
 
   interface PendingSuiteFunction {
-    (title: string,  config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite | void
+    (title: string, config: Cypress.TestConfigOverrides, fn: (this: Suite) => void): Suite | void
   }
 }

package/types/index.d.ts

@@ -4,7 +4,7 @@
 //                 Mike Woudenberg <https://github.com/mikewoudenberg>
 //                 Robbert van Markus <https://github.com/rvanmarkus>
 //                 Nicholas Boll <https://github.com/nicholasboll>
-// TypeScript Version: 3.0
+// TypeScript Version: 3.4
 // Updated by the Cypress team: https://www.cypress.io/about/
 
 /// <reference path="./cy-blob-util.d.ts" />
@@ -27,6 +27,7 @@
 // hmm, how to load it better?
 /// <reference path="./cypress-npm-api.d.ts" />
 
+/// <reference path="./net-stubbing.ts" />
 /// <reference path="./cypress.d.ts" />
 /// <reference path="./cypress-global-vars.d.ts" />
 /// <reference path="./cypress-type-helpers.d.ts" />