cypress 3.1.4 → 3.1.5

package/lib/cli.js

@@ -26,8 +26,7 @@ function unknownOption(flag) {
   logger.error('  error: unknown ' + type + ':', flag);
   logger.error();
   this.outputHelp();
-  logger.error();
-  process.exit(1);
+  util.exit(1);
 }
 commander.Command.prototype.unknownOption = unknownOption;
 
@@ -65,9 +64,9 @@ var descriptions = {
   dev: 'runs cypress in development and bypasses binary check',
   forceInstall: 'force install the Cypress binary',
   exit: 'keep the browser open after tests finish',
-  cachePath: 'print the cypress binary cache path',
-  cacheList: 'list the currently cached versions',
-  cacheClear: 'delete the Cypress binary cache',
+  cachePath: 'print the path to the binary cache',
+  cacheList: 'list cached binary versions',
+  cacheClear: 'delete all cached binaries',
   group: 'a named group for recorded runs in the Cypress dashboard',
   parallel: 'enables concurrent runs and automatic load balancing of specs across multiple machines or processes',
   ciBuildId: 'the unique identifier for a run on your CI provider. typically a "BUILD_ID" env var. this value is automatically detected for most CI providers'
@@ -140,8 +139,13 @@ module.exports = {
     });
 
     program.command('cache').usage('[command]').description('Manages the Cypress binary cache').option('list', text('cacheList')).option('path', text('cachePath')).option('clear', text('cacheClear')).action(function (opts) {
+      if (!_.isString(opts)) {
+        this.outputHelp();
+        util.exit(1);
+      }
+
       if (opts.command || !_.includes(['list', 'path', 'clear'], opts)) {
-        unknownOption.call(this, 'cache ' + opts, 'sub-command');
+        unknownOption.call(this, 'cache ' + opts, 'command');
       }
 
       cache[opts]();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cypress",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "main": "index.js",
   "bin": {
     "cypress": "bin/cypress"
@@ -31,7 +31,7 @@
     "@types/minimatch": "3.0.3",
     "@types/mocha": "2.2.44",
     "@types/sinon": "7.0.0",
-    "@types/sinon-chai": "2.7.29",
+    "@types/sinon-chai": "3.2.2",
     "bluebird": "3.5.0",
     "cachedir": "1.3.0",
     "chalk": "2.4.1",

package/types/index.d.ts

@@ -116,10 +116,12 @@ declare namespace Cypress {
      * Cypress version string. i.e. "1.1.2"
      * @see https://on.cypress.io/version
      * @example
-     *    expect(Cypress.version).to.be.a('string')
-     *    if (Cypress.version === '1.2.0') {
-     *       // test something specific
-     *    }
+      ```
+      expect(Cypress.version).to.be.a('string')
+      if (Cypress.version === '1.2.0') {
+        // test something specific
+      }
+      ```
      */
     version: string
 
@@ -143,6 +145,15 @@ declare namespace Cypress {
 
     /**
      * Currently executing spec file.
+     * @example
+    ```
+    Cypress.spec
+    // {
+    //  name: "config_passing_spec.coffee",
+    //  relative: "cypress/integration/config_passing_spec.coffee",
+    //  absolute: "/users/smith/projects/web/cypress/integration/config_passing_spec.coffee"
+    // }
+    ```
      */
     spec: {
       name: string // "config_passing_spec.coffee"
@@ -156,11 +167,45 @@ declare namespace Cypress {
     browser: Browser
 
     /**
+     * Returns all configuration objects.
      * @see https://on.cypress.io/config
+     * @example
+    ```
+    Cypress.config()
+    // {defaultCommandTimeout: 10000, pageLoadTimeout: 30000, ...}
+    ```
      */
     config(): ConfigOptions
+    /**
+     * Returns one configuration value.
+     * @see https://on.cypress.io/config
+     * @example
+    ```
+    Cypress.config('pageLoadTimeout')
+    // 60000
+    ```
+     */
     config<K extends keyof ConfigOptions>(key: K): ConfigOptions[K]
+    /**
+     * Sets one configuration value.
+     * @see https://on.cypress.io/config
+     * @example
+    ```
+    Cypress.config('viewportWidth', 800)
+    ```
+     */
     config<K extends keyof ConfigOptions>(key: K, value: ConfigOptions[K]): void
+    /**
+     * Sets multiple configuration values at once.
+     * @see https://on.cypress.io/config
+     * @example
+    ```
+    Cypress.config({
+      defaultCommandTimeout: 10000,
+      viewportHeight: 900
+    })
+    ```
+     */
     config(Object: Partial<ConfigOptions>): void
 
     // no real way to type without generics
@@ -277,16 +322,20 @@ declare namespace Cypress {
      * @see https://on.cypress.io/variables-and-aliases
      * @see https://on.cypress.io/get
      * @example
-     *    // Get the aliased ‘todos’ elements
-     *    cy.get('ul#todos').as('todos')
-     *    //...hack hack hack...
-     *    // later retrieve the todos
-     *    cy.get('@todos')
+    ```
+    // Get the aliased ‘todos’ elements
+    cy.get('ul#todos').as('todos')
+    //...hack hack hack...
+    // later retrieve the todos
+    cy.get('@todos')
+    ```
      */
     as(alias: string): Chainable<Subject>
 
     /**
-     * Blur a focused element. This element must currently be in focus. If you want to ensure an element is focused before blurring, try using .focus() before .blur().
+     * Blur a focused element. This element must currently be in focus.
+     * If you want to ensure an element is focused before blurring,
+     * try using .focus() before .blur().
      *
      * @see https://on.cypress.io/blur
      */
@@ -355,19 +404,29 @@ declare namespace Cypress {
      * to clear localStorage inside a single test. Yields `localStorage` object.
      *
      * @see https://on.cypress.io/clearlocalstorage
-     * @example
-     *    cy.clearLocalStorage().should(ls => {
-     *      expect(ls.getItem('prop1')).to.be.null
-     *    })
+     * @param {string} [key] - name of a particular item to remove (optional).
+     * @example
+      ```
+      // removes all local storage keys
+      cy.clearLocalStorage()
+        .should(ls => {
+          expect(ls.getItem('prop1')).to.be.null
+        })
+      // removes item "todos"
+      cy.clearLocalStorage("todos")
+      ```
      */
     clearLocalStorage(key?: string): Chainable<Storage>
     /**
      * Clear keys in local storage that match given regular expression.
      *
      * @see https://on.cypress.io/clearlocalstorage
+     * @param {RegExp} re - regular expression to match.
      * @example
-     *    // Clear all local storage matching /app-/
-     *    cy.clearLocalStorage(/app-/)
+    ```
+    // Clear all local storage matching /app-/
+    cy.clearLocalStorage(/app-/)
+    ```
      */
     clearLocalStorage(re: RegExp): Chainable<Storage>
 
@@ -384,7 +443,8 @@ declare namespace Cypress {
     /**
      * Click a DOM element at specific corner / side.
      *
-     * @param {String} position The position where the click should be issued. The `center` position is the default position.
+     * @param {String} position - The position where the click should be issued.
+     * The `center` position is the default position.
      * @see https://on.cypress.io/click
      * @example
      *    cy.get('button').click('topRight')
@@ -397,9 +457,11 @@ declare namespace Cypress {
      * @param {number} y The distance in pixels from the element’s top to issue the click.
      * @see https://on.cypress.io/click
      * @example
-     *    // The click below will be issued inside of the element
-     *    // (15px from the left and 40px from the top).
-     *    cy.get('button').click(15, 40)
+    ```
+    // The click below will be issued inside of the element
+    // (15px from the left and 40px from the top).
+    cy.get('button').click(15, 40)
+    ```
      */
     click(x: number, y: number, options?: Partial<ClickOptions>): Chainable<Subject>
 
@@ -623,9 +685,11 @@ declare namespace Cypress {
     fixture<Contents = any>(path: string, encoding: Encodings, options?: Partial<Timeoutable>): Chainable<Contents> // no log?
 
     /**
-     * Get the DOM element that is currently focused.
+     * Focus on a DOM element.
      *
      * @see https://on.cypress.io/focus
+     * @example
+     * cy.get('input').first().focus() // Focus on the first input
      */
     focus(options?: Partial<Loggable & Timeoutable>): Chainable<Subject>
 
@@ -1327,19 +1391,37 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/then
      */
-    then<S>(fn: (this: ObjectLike, currentSubject: Subject) => Chainable<S>, options?: Partial<Timeoutable>): Chainable<S>
+    then<S>(fn: (this: ObjectLike, currentSubject: Subject) => Chainable<S>): Chainable<S>
+    /**
+     * Enables you to work with the subject yielded from the previous command.
+     *
+     * @see https://on.cypress.io/then
+     */
+    then<S>(options: Partial<Timeoutable>, fn: (this: ObjectLike, currentSubject: Subject) => Chainable<S>): Chainable<S>
     /**
      * Enables you to work with the subject yielded from the previous command / promise.
      *
      * @see https://on.cypress.io/then
      */
-    then<S>(fn: (this: ObjectLike, currentSubject: Subject) => PromiseLike<S>, options?: Partial<Timeoutable>): Chainable<S>
+    then<S>(fn: (this: ObjectLike, currentSubject: Subject) => PromiseLike<S>): Chainable<S>
     /**
      * Enables you to work with the subject yielded from the previous command / promise.
      *
      * @see https://on.cypress.io/then
      */
-    then<S extends object | any[] | string | number | boolean>(fn: (this: ObjectLike, currentSubject: Subject) => S, options?: Partial<Timeoutable>): Chainable<S>
+    then<S>(options: Partial<Timeoutable>, fn: (this: ObjectLike, currentSubject: Subject) => PromiseLike<S>): Chainable<S>
+    /**
+     * Enables you to work with the subject yielded from the previous command / promise.
+     *
+     * @see https://on.cypress.io/then
+     */
+    then<S extends object | any[] | string | number | boolean>(fn: (this: ObjectLike, currentSubject: Subject) => S): Chainable<S>
+    /**
+     * Enables you to work with the subject yielded from the previous command / promise.
+     *
+     * @see https://on.cypress.io/then
+     */
+    then<S extends object | any[] | string | number | boolean>(options: Partial<Timeoutable>, fn: (this: ObjectLike, currentSubject: Subject) => S): Chainable<S>
     /**
      * Enables you to work with the subject yielded from the previous command.
      *
@@ -1348,7 +1430,16 @@ declare namespace Cypress {
      *    cy.get('.nav').then(($nav) => {})  // Yields .nav as first arg
      *    cy.location().then((loc) => {})   // Yields location object as first arg
      */
-    then(fn: (this: ObjectLike, currentSubject: Subject) => void, options?: Partial<Timeoutable>): Chainable<Subject>
+    then(fn: (this: ObjectLike, currentSubject: Subject) => void): Chainable<Subject>
+    /**
+     * Enables you to work with the subject yielded from the previous command.
+     *
+     * @see https://on.cypress.io/then
+     * @example
+     *    cy.get('.nav').then(($nav) => {})  // Yields .nav as first arg
+     *    cy.location().then((loc) => {})   // Yields location object as first arg
+     */
+    then(options: Partial<Timeoutable>, fn: (this: ObjectLike, currentSubject: Subject) => void): Chainable<Subject>
 
     /**
      * Move time after overriding a native time function with [cy.clock()](https://on.cypress.io/clock).
@@ -1502,9 +1593,12 @@ declare namespace Cypress {
     visit(url: string, options?: Partial<VisitOptions>): Chainable<Window>
 
     /**
-     * Wait for a number of milliseconds or wait for an aliased resource to resolve before moving on to the next command.
+     * Wait for a number of milliseconds.
+     * You almost never need to wait for an arbitrary period of time.
+     * There are always better ways to express this in Cypress, see the documentation.
      *
      * @see https://on.cypress.io/wait
+     * @param {number} ms - Milliseconds to wait.
      * @example
      *    cy.wait(1000) // wait for 1 second
      */
@@ -1513,12 +1607,44 @@ declare namespace Cypress {
      * Wait for a specific XHR to respond.
      *
      * @see https://on.cypress.io/wait
+     * @param {string} alias - Name of the alias to wait for.
+     *
+    ```
+    // Wait for the route aliased as 'getAccount' to respond
+    // without changing or stubbing its response
+    cy.server()
+    cy.route('/accounts/*').as('getAccount')
+    cy.visit('/accounts/123')
+    cy.wait('@getAccount').then((xhr) => {
+      // we can now access the low level xhr
+      // that contains the request body,
+      // response body, status, etc
+    })
+    ```
      */
     wait(alias: string, options?: Partial<Loggable & Timeoutable & TimeoutableXHR>): Chainable<WaitXHR>
     /**
      * Wait for list of XHR requests to complete.
      *
      * @see https://on.cypress.io/wait
+     * @param {string[]} aliases - An array of aliased routes as defined using the `.as()` command.
+     *
+    ```
+    // wait for 3 XHR requests to complete
+    cy.server()
+    cy.route('users/*').as('getUsers')
+    cy.route('activities/*').as('getActivities')
+    cy.route('comments/*').as('getComments')
+    cy.visit('/dashboard')
+
+    cy.wait(['@getUsers', '@getActivities', '@getComments'])
+      .then((xhrs) => {
+        // xhrs will now be an array of matching XHR's
+        // xhrs[0] <-- getUsers
+        // xhrs[1] <-- getActivities
+        // xhrs[2] <-- getComments
+      })
+    ```
      */
     wait(alias: string[], options?: Partial<Loggable & Timeoutable & TimeoutableXHR>): Chainable<WaitXHR[]>
 
@@ -1527,11 +1653,13 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/window
      * @example
-     *    cy.visit('http://localhost:8080/app')
-     *    cy.window().then(function(win){
-     *      // win is the remote window
-     *      // of the page at: http://localhost:8080/app
-     *    })
+    ```
+    cy.visit('http://localhost:8080/app')
+    cy.window().then(function(win){
+      // win is the remote window
+      // of the page at: http://localhost:8080/app
+    })
+    ```
      */
     window(options?: Partial<Loggable & Timeoutable>): Chainable<Window>
 
@@ -1540,14 +1668,15 @@ declare namespace Cypress {
      * Useful when working within a particular group of elements such as a `<form>`.
      * @see https://on.cypress.io/within
      * @example
-     *    cy.get('form').within(($form) => {
-     *      // cy.get() will only search for elements within form,
-     *      // not within the entire document
-     *      cy.get('input[name="username"]').type('john')
-     *      cy.get('input[name="password"]').type('password')
-     *      cy.root().submit()
-     *    })
-     *
+    ```
+    cy.get('form').within(($form) => {
+      // cy.get() will only search for elements within form,
+      // not within the entire document
+      cy.get('input[name="username"]').type('john')
+      cy.get('input[name="password"]').type('password')
+      cy.root().submit()
+    })
+    ```
      */
     within(fn: (currentSubject: Subject) => void): Chainable<Subject>
     /**
@@ -1562,10 +1691,13 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/wrap
      * @example
-     *    cy.get('form').within(($form) => {
-     *       // more commands
-     *       cy.wrap($form).should('have.class', 'form-container')
-     *    })
+    ```
+    // wraps DOM element
+    cy.get('form').within(($form) => {
+      // more commands
+      cy.wrap($form).should('have.class', 'form-container')
+    })
+    ```
      */
     wrap<E extends Node = HTMLElement>(element: E | JQuery<E>, options?: Partial<Loggable & Timeoutable>): Chainable<JQuery<E>>
     /**
@@ -1573,9 +1705,11 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/wrap
      * @example
-     *    cy.wrap(new Promise((resolve, reject) => {
-     *      setTimeout(resolve, 1000);
-     *    }).then(result => {})
+    ```
+    cy.wrap(new Promise((resolve, reject) => {
+      setTimeout(resolve, 1000);
+    }).then(result => {})
+    ```
      */
     wrap<F extends Promise<S>, S>(promise: F, options?: Partial<Loggable & Timeoutable>): Chainable<S>
     /**
@@ -1583,10 +1717,12 @@ declare namespace Cypress {
      *
      * @see https://on.cypress.io/wrap
      * @example
-     *    // Make assertions about object
-     *    cy.wrap({ amount: 10 })
-     *      .should('have.property', 'amount')
-     *      .and('eq', 10)
+    ```
+    // Make assertions about object
+    cy.wrap({ amount: 10 })
+      .should('have.property', 'amount')
+      .and('eq', 10)
+    ```
      */
     wrap<S>(object: S, options?: Partial<Loggable & Timeoutable>): Chainable<S>
 
@@ -1594,6 +1730,12 @@ declare namespace Cypress {
      * Write to a file with the specified contents.
      *
      * @see https://on.cypress.io/writefile
+    ```
+    cy.writeFile('path/to/message.txt', 'Hello World')
+      .then((text) => {
+        expect(text).to.equal('Hello World') // true
+      })
+    ```
      */
     writeFile<C extends FileContents>(filePath: string, contents: C, options?: Partial<Loggable>): Chainable<C>
     /**
@@ -3674,26 +3816,28 @@ declare namespace Cypress {
      * 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
-     * })
-     * // stub "window.alert" in a single test
-     * it('shows alert', () => {
-     *    const stub = cy.stub()
-     *    cy.on('window:alert', stub)
-     *    // trigger application code that calls alert(...)
-     *    .then(() => {
-     *      expect(stub).to.have.been.calledOnce
-     *    })
-     * })
      * @see https://on.cypress.io/catalog-of-events#App-Events
+     * @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
+      })
+      // stub "window.alert" in a single test
+      it('shows alert', () => {
+        const stub = cy.stub()
+        cy.on('window:alert', stub)
+        // trigger application code that calls alert(...)
+        .then(() => {
+          expect(stub).to.have.been.calledOnce
+        })
+      })
+    ```
      */
     (action: 'uncaught:exception', fn: (error: Error, runnable: Mocha.IRunnable) => false | void): void
     /**
@@ -3701,23 +3845,28 @@ declare namespace Cypress {
      * Cypress will auto accept confirmations. Return `false` from this event and the confirmation will be cancelled.
      * @see https://on.cypress.io/catalog-of-events#App-Events
      * @example
-     *    cy.on('window:confirm', (str) => {
-     *      console.log(str)
-     *      return false // simulate "Cancel"
-     *    })
+    ```
+    cy.on('window:confirm', (str) => {
+      console.log(str)
+      return false // simulate "Cancel"
+    })
+    ```
      */
     (action: 'window:confirm', fn: ((text: string) => false | void) | Agent<sinon.SinonSpy>): void
     /**
      * Fires when your app calls the global `window.alert()` method.
      * Cypress will auto accept alerts. You cannot change this behavior.
      * @example
-     *    const stub = cy.stub()
-     *    cy.on('window:alert', stub)
-     *    // assume the button calls window.alert()
-     *    cy.get('.my-button').click()
-     *    .then(() => {
-     *      expect(stub).to.have.been.calledOnce
-     *    })
+    ```
+    const stub = cy.stub()
+    cy.on('window:alert', stub)
+    // assume the button calls window.alert()
+    cy.get('.my-button')
+      .click()
+      .then(() => {
+        expect(stub).to.have.been.calledOnce
+      })
+    ```
      * @see https://on.cypress.io/catalog-of-events#App-Events
      */
     (action: 'window:alert', fn: ((text: string) => void) | Agent<sinon.SinonSpy>): void
@@ -3931,26 +4080,29 @@ declare namespace Cypress {
     left: number
   }
 
-  // Diff / Omit taken from https://github.com/Microsoft/TypeScript/issues/12215#issuecomment-311923766
+  // Diff taken from https://github.com/Microsoft/TypeScript/issues/12215#issuecomment-311923766
   type Diff<T extends string, U extends string> = ({[P in T]: P } & {[P in U]: never } & { [x: string]: never })[T]
-  // TODO - remove this if possible. Seems a recent change to TypeScript broke this. Possibly https://github.com/Microsoft/TypeScript/pull/17912
-  type Omit<T, K extends keyof T> = Pick<T, Diff<keyof T, K>> // tslint:disable-line
+  type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>
 }
 
 /**
  * Global variables `cy` added by Cypress with all API commands.
  * @see https://on.cypress.io/api
  * @example
- *    cy.get('button').click()
- *    cy.get('.result').contains('Expected text')
+```
+cy.get('button').click()
+cy.get('.result').contains('Expected text')
+```
  */
 declare const cy: Cypress.Chainable<undefined>
 /**
  * Global variable `Cypress` holds common utilities and constants.
  * @see https://on.cypress.io/api
  * @example
- *    Cypress.config("pageLoadTimeout") // => 60000
- *    Cypress.version // => "1.4.0"
- *    Cypress._ // => Lodash _
+```
+Cypress.config("pageLoadTimeout") // => 60000
+Cypress.version // => "1.4.0"
+Cypress._ // => Lodash _
+```
  */
 declare const Cypress: Cypress.Cypress