From e675e2d4e1e61548f0488007ac5aca95ea603bf5 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Thu, 1 Jun 2017 15:27:07 -0400 Subject: [PATCH] docs: cleanup of api content --- docs/source/api/commands/and.md | 6 +-- docs/source/api/commands/route.md | 2 +- docs/source/api/commands/server.md | 65 +++++++++++++-------------- docs/source/api/commands/setcookie.md | 34 +++++++------- docs/source/api/commands/should.md | 33 +++++--------- docs/source/api/commands/siblings.md | 4 +- docs/source/api/commands/spread.md | 16 +++---- docs/source/api/commands/spy.md | 15 ++++--- docs/source/api/commands/stub.md | 20 ++++----- docs/source/api/commands/submit.md | 5 ++- docs/source/api/commands/then.md | 33 ++++++-------- docs/source/api/commands/tick.md | 10 ++--- docs/source/api/commands/title.md | 7 ++- docs/source/api/commands/trigger.md | 17 +++---- docs/source/api/commands/type.md | 19 ++++---- docs/source/api/commands/uncheck.md | 10 ++--- docs/source/api/commands/url.md | 6 +-- docs/source/api/commands/viewport.md | 13 +++--- docs/source/api/commands/visit.md | 15 +++---- docs/source/api/commands/wait.md | 38 ++++++++-------- docs/source/api/commands/window.md | 4 +- docs/source/api/commands/within.md | 1 - docs/source/api/commands/writefile.md | 1 - 23 files changed, 168 insertions(+), 206 deletions(-) diff --git a/docs/source/api/commands/and.md b/docs/source/api/commands/and.md index fb5034d516..80f217b957 100644 --- a/docs/source/api/commands/and.md +++ b/docs/source/api/commands/and.md @@ -79,7 +79,7 @@ cy ## Timeout -`.and` will continue to retry the assertion to the duration of the previous cy commands `timeout` or the `defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) +`.and()` will continue to retry the assertion to the duration of the previous cy commands `timeout` or the `defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts). ```javascript cy.get('input', {timeout: 10000}).should('have.value', '10').and('have.class', 'error') @@ -204,14 +204,12 @@ Take this *explicit* assertion for example: expect({foo: 'bar'}).to.have.property('foo').and.eq('bar') ``` -`cy.and` reproduces this same assertion behavior. +`.and()` reproduces this same assertion behavior. **How do I know which assertions change the subject and which keep it the same?** The chainers that come from [Chai](https://on.cypress.io/guides/bundled-tools#chai) or [Chai-jQuery](https://on.cypress.io/guides/bundled-tools#chai-jquery) will always document what they return. -Alternatively, it is very easy to use Cypress itself to figure this out. - You can [read more about debugging assertions](https://on.cypress.io/guides/making-assertions#debugging-assertions) here. # Command Log diff --git a/docs/source/api/commands/route.md b/docs/source/api/commands/route.md index 861c726c00..685e5464fb 100644 --- a/docs/source/api/commands/route.md +++ b/docs/source/api/commands/route.md @@ -59,9 +59,9 @@ Option | Default | Notes `force404` | `false` | Forcibly send XHR's a 404 status when the XHR's do not match any existing [`cy.routes`](https://on.cypress.io/api/routes) `headers` | `null` | Response headers for stubbed routes `method` | `GET` | Method to match against requests +`onAbort` | `null` | Callback function which fires anytime an XHR is aborted `onRequest` | `null` | Callback function when a request is sent `onResponse` | `null` | Callback function when a response is returned -`onAbort` | `null` | Callback function which fires anytime an XHR is aborted `response` | `null` | Response body when stubbing routes `status` | `200` | Response status code when stubbing routes `url` | `null` | String or RegExp url to match against request urls diff --git a/docs/source/api/commands/server.md b/docs/source/api/commands/server.md index ff1ceb1e5b..b14ffdbf3b 100644 --- a/docs/source/api/commands/server.md +++ b/docs/source/api/commands/server.md @@ -4,12 +4,13 @@ comments: true description: '' --- -Start a server to begin routing responses to `.route()` and `.request()`. +Start a server to begin routing responses to `cy.route()` and `cy.request()`. -{% note info New to Cypress? %} -[Read about Network Requests first.](https://on.cypress.io/guides/network-requests-xhr) +{% note info %} +**Note:** `cy.server()` assumes you are already familiar with core concepts such as [network requests](https://on.cypress.io/guides/network-requests-xhr) {% endnote %} + # Syntax ```javascript @@ -19,7 +20,7 @@ cy.server(options) ## Usage -`.server()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. +`cy.server()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. **{% fa fa-check-circle green %} Valid Usage** @@ -31,23 +32,24 @@ cy.server() **{% fa fa-angle-right %} options** ***(Object)*** -Pass in an options object to change the default behavior of `.server()`. These options are used for 2 different purposes +Pass in an options object to change the default behavior of `cy.server()`. These options are used for 2 different purposes: -1. As defaults that are merged into [`.route()`](https://on.cypress.io/api/route). -2. As configuration behavior for *all* requests. + - As defaults that are merged into [`cy.route()`](https://on.cypress.io/api/route). + + - As configuration behavior for *all* requests. ***The following options are merged in as default options to [`.route()`](https://on.cypress.io/api/route)*** Option | Default | Notes --- | --- | --- -`method` | `"GET"` | method to match against requests -`response` | `null` | response body when stubbing routes -`status` | `200` | response status code when stubbing routes `delay` | `0` | delay for stubbed responses (in ms) `headers` | `null` | response headers for stubbed routes +`method` | `"GET"` | method to match against requests +`onAbort` | `undefined` | callback function which fires anytime an XHR is aborted `onRequest` | `undefined` | callback function when a request is sent `onResponse` | `undefined` | callback function when a response is returned -`onAbort` | `undefined` | callback function which fires anytime an XHR is aborted +`response` | `null` | response body when stubbing routes +`status` | `200` | response status code when stubbing routes ***The following options control the behavior of the server affecting all requests:*** @@ -60,7 +62,7 @@ Option | Default | Notes ## Yields -`.server()` yields the Cypress server instance. +`cy.server()` yields the Cypress server instance. ## Timeout @@ -71,7 +73,7 @@ Option | Default | Notes **After starting a server:** -- Any request that does not match a [`.route()`](https://on.cypress.io/api/route) will be sent a `404` status code. +- Any request that does not match a [`cy.route()`](https://on.cypress.io/api/route) will be sent a `404` status code. - Any request that matches the `options.whitelist` function will **NOT** be logged or stubbed. In other words it is "whitelisted" and ignored. - You will see requests named as `(XHR Stub)` or `(XHR)` in the Command Log. @@ -81,11 +83,11 @@ cy.server() ## Options -## Change defaults for [`.route()`](https://on.cypress.io/api/route) +**Change defaults for [`.route()`](https://on.cypress.io/api/route)** -By default [`cy.route`](https://on.cypress.io/api/route) inherits some of its options from `cy.server()`. +By default [`cy.route()`](https://on.cypress.io/api/route) inherits some of its options from `cy.server()`. -In this example, our matching requests will be delayed 1000ms and have a status of 422, but its response will be what was set in [`.route()`](https://on.cypress.io/api/route). +In this example, our matching requests will be delayed 1000ms and have a status of `422`, but its `response` will be what was set in [`cy.route()`](https://on.cypress.io/api/route). ```javascript cy.server({ @@ -124,7 +126,6 @@ cy.route('/activities/**', 'fixture:activities.json') ```javascript // Application Code - $(function(){ $.get('/activities') @@ -136,10 +137,10 @@ $(function(){ **Change the default response headers for all routes** -When you stub requests, you can automatically control their response headers. This is useful when you want to send back meta data in the headers, such as *pagination* or *token* information. +When you stub requests, you can automatically control their response `headers`. This is useful when you want to send back meta data in the `headers`, such as *pagination* or *token* information. {% note info %} -Cypress automatically sets `Content-Length` and `Content-Type` based on the response body you stub. +Cypress automatically sets `Content-Length` and `Content-Type` based on the response `body` you stub. {% endnote %} ```javascript @@ -150,9 +151,8 @@ cy.server({ }) cy.route('GET', '/users/1', {id: 1, name: 'Amanda'}).as('getUser') cy.visit('/users/1/profile') -cy.wait('@getUser') - .its('responseHeaders') - .should('have.property', 'x-token', 'abc-123-foo-bar') // true +cy.wait('@getUser').its('responseHeaders') + .should('have.property', 'x-token', 'abc-123-foo-bar') // true ``` ```javascript @@ -173,13 +173,13 @@ xhr.send() **Change the default whitelisting** -`.server()` comes with a `whitelist` function that will filter out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`. +`cy.server()` comes with a `whitelist` function that by default filters out any requests that are for static assets like `.html`, `.js`, `.jsx`, and `.css`. -Any request that passes the `whitelist` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific [`.route()`](https://on.cypress.io/api/route)). +Any request that passes the `whitelist` will be ignored - it will not be logged nor will it be stubbed in any way (even if it matches a specific [`cy.route()`](https://on.cypress.io/api/route)). The idea is that we never want to interfere with static assets that are fetched via AJAX. -The default whitelist function in Cypress is: +***The default whitelist function in Cypress is:*** ```javascript var whitelist = function(xhr){ @@ -189,7 +189,7 @@ var whitelist = function(xhr){ } ``` -You can override this function with your own specific logic. +***You can override this function with your own specific logic:*** ```javascript cy.server({ @@ -210,7 +210,6 @@ You can disable all stubbing and its effects and restore it to the default behav ```javascript cy.server() cy.route('POST', '/users', {}).as('createUser') - cy.server({enable: false}) ``` @@ -226,16 +225,16 @@ However between tests, when a new test runs, the previous configuration is resto When a new test runs, any outstanding requests still in flight are automatically aborted. In fact this happens by default whether or not you've even started a `cy.server()`. -**Server can be started before you [`cy.visit`](https://on.cypress.io/api/visit)** +**Server can be started before you [`cy.visit()`](https://on.cypress.io/api/visit)** -Oftentimes your application may make initial requests immediately when it loads (such as authenticating a user). Cypress makes it possible to start your server and define routes before a [`cy.visit`](https://on.cypress.io/api/visit). Upon the next visit, the server + routes will be instantly applied before your application loads. +Oftentimes your application may make initial requests immediately when it loads (such as authenticating a user). Cypress makes it possible to start your server and define routes before a [`cy.visit()`](https://on.cypress.io/api/visit). Upon the next visit, the server + routes will be instantly applied before your application loads. You can [read more about XHR strategy here](https://on.cypress.io/guides/network-requests-xhr). # See also -- [route](https://on.cypress.io/api/route) -- [wait](https://on.cypress.io/api/wait) -- [request](https://on.cypress.io/api/request) -- [visit](https://on.cypress.io/api/visit) - [Network Requests](https://on.cypress.io/guides/network-requests-xhr) +- [request](https://on.cypress.io/api/request) +- [route](https://on.cypress.io/api/route) +- [visit](https://on.cypress.io/api/visit) +- [wait](https://on.cypress.io/api/wait) diff --git a/docs/source/api/commands/setcookie.md b/docs/source/api/commands/setcookie.md index de8ee343b4..815d230c20 100644 --- a/docs/source/api/commands/setcookie.md +++ b/docs/source/api/commands/setcookie.md @@ -20,7 +20,7 @@ cy.setCookie(name, value, options) **{% fa fa-check-circle green %} Valid Usage** ```javascript -cy.setCookie('auth_key', '123key') +cy.setCookie('auth_key', '123key') // Set the 'auth_key' cookie to '123key' ``` ## Arguments @@ -39,17 +39,17 @@ Pass in an options object to change the default behavior of `cy.setCookie()`. Option | Default | Notes --- | --- | --- -`path` | `/` | the cookie path -`domain` | `window.location.hostname` | the domain the cookie is visible to -`secure` | `false` | whether the cookie is a secure cookie -`httpOnly` | `false` | whether the cookie is an HTTP only cookie -`expiry` | 20 years into the future | when the cookie expires, specified in seconds since [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time). -`timeout` | [`responseTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to wait for the `cy.setCookie()` command to be processed +`domain` | `window.location.hostname` | The domain the cookie is visible to +`expiry` | 20 years into the future | When the cookie expires, specified in seconds since [Unix Epoch](https://en.wikipedia.org/wiki/Unix_time). +`httpOnly` | `false` | Whether the cookie is an HTTP only cookie `log` | `true` | Whether to display command in Command Log +`path` | `/` | The cookie path +`secure` | `false` | Whether the cookie is a secure cookie +`timeout` | [`responseTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to wait for the `cy.setCookie()` command to be processed ## Yields -`.setCookie()` yields a cookie object literal with the following properties: +`cy.setCookie()` yields a cookie object literal with the following properties: - `name` - `value` @@ -61,7 +61,7 @@ Option | Default | Notes ## Timeout -`.setCookie()` will wait up for the duration of [`responseTimeout`](https://on.cypress.io/guides/configuration#timeouts) for the automation server to process this command. +`cy.setCookie()` will wait up for the duration of [`responseTimeout`](https://on.cypress.io/guides/configuration#timeouts) for the automation server to process this command. # Examples @@ -70,10 +70,9 @@ Option | Default | Notes **Set a cookie** ```javascript -cy - .getCookies().should('be.empty') - .setCookie('session_id', '189jd09sufh33aaiidhf99d09') - .getCookie('session_id').should('have.property', 'value', '189jd09sufh33aaiidhf99d09') +cy.getCookies().should('be.empty') +cy.setCookie('session_id', '189jd09sufh33aaiidhf99d09') +cy.getCookie('session_id').should('have.property', 'value', '189jd09sufh33aaiidhf99d09') ``` # Command Log @@ -81,10 +80,9 @@ cy **Set a cookie** ```javascript -cy - .getCookies().should('be.empty') - .setCookie('fakeCookie1', '123ABC') - .getCookie('fakeCookie1').should('have.property', 'value', '123ABC') +cy.getCookies().should('be.empty') +cy.setCookie('fakeCookie1', '123ABC') +cy.getCookie('fakeCookie1').should('have.property', 'value', '123ABC') ``` The commands above will display in the command log as: @@ -99,6 +97,6 @@ When clicking on `setCookie` within the command log, the console outputs the fol - [clearCookie](https://on.cypress.io/api/clearcookie) - [clearCookies](https://on.cypress.io/api/clearcookies) +- [Cypress Cookies API](https://on.cypress.io/api/cookies) - [getCookie](https://on.cypress.io/api/getcookie) - [getCookies](https://on.cypress.io/api/getcookies) -- [Cypress Cookies API](https://on.cypress.io/api/cookies) diff --git a/docs/source/api/commands/should.md b/docs/source/api/commands/should.md index afe541ad23..f7393a1583 100644 --- a/docs/source/api/commands/should.md +++ b/docs/source/api/commands/should.md @@ -10,8 +10,8 @@ Make an assertion. An alias of [`.and()`](https://on.cypress.io/api/and) {% endnote %} -{% note info New to Cypress? %} -[Read about making assertions first.](https://on.cypress.io/guides/making-assertions) +{% note info %} +**Note:** `.should()` assumes you are already familiar with core concepts such as [assertions](https://on.cypress.io/guides/making-assertions) {% endnote %} # Syntax @@ -60,7 +60,6 @@ A method to be called on the chainer. Pass a function that can have any number of explicit assertions within it. Whatever was passed to the function is what is yielded. - ## Yields In most cases, `.should()` yields the previous cy command's yield. @@ -81,7 +80,7 @@ cy ## Timeout -`.should` will continue to retry the assertion to the duration of the previous cy commands `timeout` or the `defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) +`.should()` will continue to retry the assertion to the duration of the previous cy commands `timeout` or the `defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts). ```javascript cy.get('input', {timeout: 10000}).should('have.value', '10') @@ -145,9 +144,7 @@ cy.get('#header a').should('have.attr', 'href', '/users') Passing a function to `.should()` enables you to assert on the yielded subject. This gives you the opportunity to *massage* what you'd like to assert on. -Just be sure *not* to include any code that has side effects in your callback function. - -The callback function will be retried over and over again until no assertions within it throw. +Just be sure *not* to include any code that has side effects in your callback function. The callback function will be retried over and over again until no assertions within it throw. ```html
@@ -184,6 +181,8 @@ cy **Assert explicitly within `.should()`** +Any errors raised by failed assertions will immediately bubble up and cause the test to fail. + ```html
  • Walk the dog
    • @@ -201,9 +200,6 @@ cy.get("#todos li").should(function($lis){ }) ``` -{% note warning %} -Any errors raised by failed assertions will immediately bubble up and cause the test to fail. -{% endnote %} **Using a callback function will not change the subject** @@ -234,7 +230,6 @@ In this example we use [`.and()`](https://on.cypress.io/api/and) which is identi cy.get('option:first').should('be.selected').and('have.value', 'Metallica') ``` - ## Wait until the assertions pass Cypress won't resolve your commands until all of its assertions pass. @@ -251,11 +246,9 @@ $('button').click(function(){ ``` ```javascript -cy - .get('button') - .click() - .should('have.class', 'active') - .and('not.have.class', 'inactive') +cy.get('button').click() + .should('have.class', 'active') + .and('not.have.class', 'inactive') ``` You can [read more about how Cypress resolves your assertions](https://on.cypress.io/guides/making-assertions#resolving-assertions) here. @@ -266,8 +259,6 @@ You can [read more about how Cypress resolves your assertions](https://on.cypres The chainers that come from [Chai](https://on.cypress.io/guides/bundled-tools#chai) or [Chai-jQuery](https://on.cypress.io/guides/bundled-tools#chai-jquery) will always document what they return. -Alternatively, it is very easy to use Cypress itself to figure this out. - You can [read more about debugging assertions](https://on.cypress.io/guides/making-assertions#debugging-assertions) here. # Command Log @@ -275,11 +266,7 @@ You can [read more about debugging assertions](https://on.cypress.io/guides/maki **Assert that there should be 8 children in a nav** ```javascript -// -cy - .get('.left-nav>.nav') - .children() - .should('have.length', 8) +cy.get('.left-nav>.nav').children().should('have.length', 8) ``` The commands above will display in the command log as: diff --git a/docs/source/api/commands/siblings.md b/docs/source/api/commands/siblings.md index 6f39680bf3..f898fb1162 100644 --- a/docs/source/api/commands/siblings.md +++ b/docs/source/api/commands/siblings.md @@ -54,9 +54,7 @@ Option | Default | Notes ## Timeout -`.siblings()` will continue to look for the sibling element(s) for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) - - +`.siblings()` will continue to look for the sibling element(s) for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts). # Examples diff --git a/docs/source/api/commands/spread.md b/docs/source/api/commands/spread.md index c40dc0371c..2d902a5fb0 100644 --- a/docs/source/api/commands/spread.md +++ b/docs/source/api/commands/spread.md @@ -7,7 +7,7 @@ description: '' Expand an array into multiple arguments. {% note info %} -Similar of [`.then()`](https://on.cypress.io/api/then), but always expects an array as it's subject. +Similar to [`.then()`](https://on.cypress.io/api/then), but always expects an array as it's subject. {% endnote %} # Syntax @@ -23,7 +23,7 @@ Similar of [`.then()`](https://on.cypress.io/api/then), but always expects an ar **{% fa fa-check-circle green %} Valid Usage** ```javascript -cy.getCookies.spread(function() {}) // Yield all el's with class '.users' +cy.getCookies.spread(function() {}) // Yield all cookies ``` **{% fa fa-exclamation-triangle red %} Invalid Usage** @@ -52,12 +52,11 @@ Whatever was passed to the function is what is yielded. **Expand the array of aliased routes** ```javascript -cy - .server() - .route('/users/').as('getUsers') - .route('/activities/').as('getActivities') - .route('/comments/').as('getComments') - .wait(['@getUsers', '@getActivities', '@getComments']) +cy.server() +cy.route('/users/').as('getUsers') +cy.route('/activities/').as('getActivities') +cy.route('/comments/').as('getComments') +cy.wait(['@getUsers', '@getActivities', '@getComments']) .spread(function(getUsers, getActivities, getComments){ // each XHR is now an individual argument }) @@ -79,5 +78,6 @@ cy.getCookies().spread(function(cookie1, cookie2, cookie3){ # See also +- [getCookies](https://on.cypress.io/api/getCookies) - [then](https://on.cypress.io/api/then) - [wait](https://on.cypress.io/api/wait) diff --git a/docs/source/api/commands/spy.md b/docs/source/api/commands/spy.md index c31d3ec7d5..12be6ab43b 100644 --- a/docs/source/api/commands/spy.md +++ b/docs/source/api/commands/spy.md @@ -14,7 +14,7 @@ cy.spy(object, method) ## Usage -`.spy()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. +`cy.spy()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. **{% fa fa-check-circle green %} Valid Usage** @@ -26,7 +26,7 @@ cy.spy(user, 'addFriend') **{% fa fa-angle-right %} object** ***(Object)*** -The object that has the `method` to be wrapped. +The `object` that has the `method` to be wrapped. **{% fa fa-angle-right %} method** ***(String)*** @@ -34,9 +34,9 @@ The name of the `method` on the `object` to be wrapped. ## Yields -Unlike most Cypress commands, `cy.spy` is *synchronous* and returns a value (the spy) instead of a Promise-like chain-able object. +Unlike most Cypress commands, `cy.spy()` is *synchronous* and returns a value (the spy) instead of a Promise-like chain-able object. -`cy.spy` returns a [Sinon.js spy](http://sinonjs.org/docs/#spies). All [methods](http://sinonjs.org/docs/#spies-api) found on Sinon.JS spies are supported. +`cy.spy()` returns a [Sinon.js spy](http://sinonjs.org/docs/#spies). All [methods](http://sinonjs.org/docs/#spies-api) found on Sinon.JS spies are supported. ## Timeout @@ -82,11 +82,11 @@ You will see the following in the command log: **Automatic reset/restore between tests** -`cy.spy` creates spies in a [sandbox](http://sinonjs.org/docs/#sandbox), so all spies created are automatically reset/restored between tests without you having to explicitly reset/restore them. +`cy.spy()` creates spies in a [sandbox](http://sinonjs.org/docs/#sandbox), so all spies created are automatically reset/restored between tests without you having to explicitly reset/restore them. **Difference between cy.spy() and cy.stub()** -The main difference between `cy.spy` and [`cy.stub`](https://on.cypress.io/api/stub) is that `cy.spy` does not replace the method, it only wraps it. So, while invocations are recorded, the original method is still called. This can be very useful when testing methods on native browser objects. You can verify a method is being called by your test and still have the original method action invoked. +The main difference between `cy.spy()` and [`cy.stub()`](https://on.cypress.io/api/stub) is that `cy.spy()` does not replace the method, it only wraps it. So, while invocations are recorded, the original method is still called. This can be very useful when testing methods on native browser objects. You can verify a method is being called by your test and still have the original method action invoked. **Assertion Support** @@ -115,7 +115,8 @@ When clicking on the `spy-1` event within the command log, the console outputs t # See also +- [as](https://on.cypress.io/api/as) +- [clock](https://on.cypress.io/api/clock) - [Guide: Stubs, Spies and Clocks ](https://on.cypress.io/guides/stubs-spies-clocks) - [Recipe: Controlling Behavior with Spies, Stubs, and Clocks](https://github.com/cypress-io/cypress-example-recipes#controlling-behavior-with-spies-stubs-and-clocks) - [stub](https://on.cypress.io/api/stub) -- [clock](https://on.cypress.io/api/clock) diff --git a/docs/source/api/commands/stub.md b/docs/source/api/commands/stub.md index fe33a14ed5..90c9abe1a4 100644 --- a/docs/source/api/commands/stub.md +++ b/docs/source/api/commands/stub.md @@ -16,7 +16,7 @@ cy.stub(object, method, replacerFn) ## Usage -`.stub()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. +`cy.stub()` cannot be chained off any other cy commands, so should be chained off of `cy` for clarity. **{% fa fa-check-circle green %} Valid Usage** @@ -28,7 +28,7 @@ cy.stub(user, 'addFriend') **{% fa fa-angle-right %} object** ***(Object)*** -The object that has the `method` to be replaced. +The `object` that has the `method` to be replaced. **{% fa fa-angle-right %} method** ***(String)*** @@ -36,14 +36,13 @@ The name of the `method` on the `object` to be wrapped. **{% fa fa-angle-right %} replacerFn** ***(Function)*** -The function used to replaces the `method` on the `object`. - +The function used to replace the `method` on the `object`. ## Yields -Unlike most Cypress commands, `cy.stub` is *synchronous* and returns a value (the stub) instead of a Promise-like chain-able object. +Unlike most Cypress commands, `cy.stub()` is *synchronous* and returns a value (the stub) instead of a Promise-like chain-able object. -`cy.stub` returns a [Sinon.js stub](http://sinonjs.org/docs/#stubs). All methods found on Sinon.JS [spies](http://sinonjs.org/docs/#spies-api) and [stubs](http://sinonjs.org/docs/#stubs-api) are supported. +`cy.stub()` returns a [Sinon.js stub](http://sinonjs.org/docs/#stubs). All methods found on Sinon.JS [spies](http://sinonjs.org/docs/#spies-api) and [stubs](http://sinonjs.org/docs/#stubs-api) are supported. ## Timeout @@ -129,15 +128,15 @@ You will see the following in the command log: **Automatic reset/restore between tests** -`cy.stub` creates stubs in a [sandbox](http://sinonjs.org/docs/#sandbox), so all stubs created are automatically reset/restored between tests without you having to explicitly reset/restore them. +`cy.stub()` creates stubs in a [sandbox](http://sinonjs.org/docs/#sandbox), so all stubs created are automatically reset/restored between tests without you having to explicitly reset/restore them. **Difference between cy.spy() and cy.stub()** -The main difference between `cy.spy` and [`cy.stub`](https://on.cypress.io/api/stub) is that `cy.spy` does not replace the method, it only wraps it. So, while invocations are recorded, the original method is still called. This can be very useful when testing methods on native browser objects. You can verify a method is being called by your test and still have the original method action invoked. +The main difference between `cy.spy()` and [`cy.stub()`](https://on.cypress.io/api/stub) is that `cy.spy()` does not replace the method, it only wraps it. So, while invocations are recorded, the original method is still called. This can be very useful when testing methods on native browser objects. You can verify a method is being called by your test and still have the original method action invoked. **Assertion Support** -Cypress has built-in [sinon-as-promised](https://github.com/bendrucker/sinon-as-promised) support, so the stubs returned by `cy.stub` supports the `.resolves` and `.rejects` API provided by `sinon-as-promised`. +Cypress has built-in [sinon-as-promised](https://github.com/bendrucker/sinon-as-promised) support, so the stubs returned by `cy.stub()` supports the `.resolves` and `.rejects` API provided by `sinon-as-promised`. # Command Log @@ -162,8 +161,9 @@ When clicking on the `(stub-1)` event within the command log, the console output # See also +- [as](https://on.cypress.io/api/as) +- [clock](https://on.cypress.io/api/clock) - [Guide: Stubs, Spies and Clocks ](https://on.cypress.io/guides/stubs-spies-clocks) - [Recipe: Controlling Behavior with Spies, Stubs, and Clocks](https://github.com/cypress-io/cypress-example-recipes#controlling-behavior-with-spies-stubs-and-clocks) - [Recipe: Unit Test - Stubbing Dependencies](https://github.com/cypress-io/cypress-example-recipes#unit-test---stubbing-dependencies) - [spy](https://on.cypress.io/api/spy) -- [clock](https://on.cypress.io/api/clock) diff --git a/docs/source/api/commands/submit.md b/docs/source/api/commands/submit.md index 15d6d2535c..5abd844b90 100644 --- a/docs/source/api/commands/submit.md +++ b/docs/source/api/commands/submit.md @@ -20,7 +20,7 @@ Submit a form. **{% fa fa-check-circle green %} Valid Usage** ```javascript -cy.get('form').submit() // Submit a form +cy.get('form').submit() // Submit a form ``` **{% fa fa-exclamation-triangle red %} Invalid Usage** @@ -42,7 +42,7 @@ Pass in an options object to change the default behavior of `.submit()`. ## Timeout -`.submit()` will continue to try to submit the form for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) +`.submit()` will continue to try to submit the form for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts). # Example @@ -81,3 +81,4 @@ When clicking on `submit` within the command log, the console outputs the follow # See also - [click](https://on.cypress.io/api/click) +- [type](https://on.cypress.io/api/type) diff --git a/docs/source/api/commands/then.md b/docs/source/api/commands/then.md index 88425f44af..04488eaef7 100644 --- a/docs/source/api/commands/then.md +++ b/docs/source/api/commands/then.md @@ -4,13 +4,13 @@ comments: true description: '' --- -Yield the current yielded subject as the first argument of a function. +Yield the previously yielded subject as the first argument of a function. # Syntax ```javascript -.spread(callbackFn) -.spread(options, callbackFn) +.then(callbackFn) +.then(options, callbackFn) ``` ## Usage @@ -28,7 +28,7 @@ cy.location().then(function(loc) {}) // Yields location object as first arg **{% fa fa-angle-right %} callbackFn** ***(Function)*** -Pass a function that takes the current yielded subject as it's first argument. +Pass a function that takes the previously yielded subject as it's first argument. **{% fa fa-angle-right %} options** ***(Object)*** @@ -42,13 +42,13 @@ Option | Default | Notes `.then()` is modeled identically to the way Promises work in JavaScript. Whatever is returned from the callback function becomes the new subject and will flow into the next command (with the exception of `null` and `undefined`). -When `null` or `undefined` is returned by the callback function, the subject will not be modified and will instead carry over to the next command. +When `null` or `undefined` are returned by the callback function, the subject will not be modified and will instead carry over to the next command. Just like Promises, you can return any compatible "thenable" (anything that has a `.then()` interface) and Cypress will wait for that to resolve before continuing forward through the chain of commands. ## Timeout -`.then` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) or the duration of the `timeout` specified in the command's [options](#options). +`.then()` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) or the duration of the `timeout` specified in the command's [options](#options). # Examples @@ -56,12 +56,6 @@ Just like Promises, you can return any compatible "thenable" (anything that has **The element `input` is yielded** -```html -
    - -
    -``` - ```javascript cy.get('form').find('input').then(function($input){ // work with $input here @@ -81,18 +75,17 @@ cy.then(function(){ }) ``` -**Returning `null` or `undefined` will not modify the subject** +**Returning `null` or `undefined` will not modify the yielded subject** ```javascript cy .get('form').then(function($form){ console.log('form is:', $form) - // undefined is returned here, therefore - // the $form subject will automatically - // carry over and allow for continued chaining + // undefined is returned here, but $form will be + // yielded to allow for continued chaining }).find('input').then(function($input){ - // we have our real $input element here since - // our form element carried over and we called + // we have our $input element here since + // our form element was yielded and we called // .find("input") on it }) ``` @@ -140,8 +133,8 @@ cy.get('button').click().then(function($button){ # See also - [and](https://on.cypress.io/api/and) -- [its](https://on.cypress.io/api/its) - [invoke](https://on.cypress.io/api/invoke) +- [Issuing Commands](https://on.cypress.io/guides/issuing-commands) +- [its](https://on.cypress.io/api/its) - [should](https://on.cypress.io/api/should) - [spread](https://on.cypress.io/api/spread) -- [Issuing Commands](https://on.cypress.io/guides/issuing-commands) diff --git a/docs/source/api/commands/tick.md b/docs/source/api/commands/tick.md index 5d0a37b1e6..fa29c7f7ce 100644 --- a/docs/source/api/commands/tick.md +++ b/docs/source/api/commands/tick.md @@ -34,15 +34,15 @@ The number of `milliseconds` to move the clock. Any timers within the affected r ## Yields -`.tick()` yields a `clock` object with the following methods: +`cy.tick()` yields a `clock` object with the following methods: -**`clock.tick(milliseconds)`** +- **`clock.tick(milliseconds)`** -Move the clock a number of milliseconds. Any timers within the affected range of time will be called. + Move the clock a number of milliseconds. Any timers within the affected range of time will be called. -**`clock.restore()`** +- **`clock.restore()`** -Restore all overridden native functions. This is automatically called between tests, so should not generally be needed. + Restore all overridden native functions. This is automatically called between tests, so should not generally be needed. You can also access the `clock` object via `this.clock` in a [`.then()`](https://on.cypress.io/api/then) callback. diff --git a/docs/source/api/commands/title.md b/docs/source/api/commands/title.md index eb0e93032a..158cfb2763 100644 --- a/docs/source/api/commands/title.md +++ b/docs/source/api/commands/title.md @@ -6,7 +6,6 @@ description: '' Get the title of the document. - # Syntax ```javascript @@ -28,7 +27,7 @@ cy.title() **{% fa fa-angle-right %} options** ***(Object)*** -Pass in an options object to change the default behavior of `cy.title`. +Pass in an options object to change the default behavior of `cy.title()`. Option | Default | Notes --- | --- | --- @@ -47,7 +46,7 @@ Option | Default | Notes ## Title -**Assert that the document's title eq "My Awesome Application"** +**Assert that the document's title is "My Awesome Application"** ```javascript cy.title().should('eq', 'My Awesome Application') @@ -55,7 +54,7 @@ cy.title().should('eq', 'My Awesome Application') # Command Log -**Assert that the document's title include 'New User'** +**Assert that the document's title includes 'New User'** ```javascript cy.title().should('include', 'New User') diff --git a/docs/source/api/commands/trigger.md b/docs/source/api/commands/trigger.md index 08685c87bf..031ce357a9 100644 --- a/docs/source/api/commands/trigger.md +++ b/docs/source/api/commands/trigger.md @@ -40,7 +40,6 @@ cy.location().trigger('mouseleave') // Errors, 'location' does not yield DOM el The name of the `event` to be triggered on the DOM element. - **{% fa fa-angle-right %} position** ***(String)*** The position where the event should be triggered. The `center` position is the default position. Valid positions are `topLeft`, `top`, `topRight`, `left`, `center`, `right`, `bottomLeft`, `bottom`, and `bottomRight`. @@ -64,8 +63,8 @@ Option | Default | Notes `bubbles` | `true` | Whether the event bubbles `cancelable` | `true` | Whether the event is cancelable `interval` | `16` | Interval which to retry triggering the event -`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry triggering the event `log` | `true` | Whether to display command in Command Log +`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry triggering the event You can also include arbitrary event properties (e.g. `clientX`, `shiftKey`) and they will be attached to the event. Passing in coordinate arguments (`clientX`, `pageX`, etc) will override the position coordinates. @@ -75,14 +74,7 @@ You can also include arbitrary event properties (e.g. `clientX`, `shiftKey`) and ## Timeout -`.trigger()` will wait until the element is in an 'interactable' state for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) or the duration of the `timeout` specified in the command's options - - -The DOM element must be in an "interactable" state prior to the triggered event happening (it must be visible and not disabled). - - - -Cypress automatically scrolls the element into view prior to attempting to trigger the event. +`.trigger()` will wait until the element is in an 'interactable' state for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) or the duration of the `timeout` specified in the command's options. # Examples @@ -90,6 +82,8 @@ Cypress automatically scrolls the element into view prior to attempting to trigg **Trigger a `mouseover` on the button** +The DOM element must be in an "interactable" state prior to the triggered event happening (it must be visible and not disabled). + ```javascript cy.get('button').trigger('mouseover') // yields 'button' ``` @@ -114,7 +108,8 @@ Note that some implementations may rely on the `input` event instead, which is f ```javascript cy.get('input[type=range]').as('range') .invoke('val', 25) - .ttrigger('change') + .trigger('change') + cy.get('@range').siblings('p').should('have.text', '25') ``` diff --git a/docs/source/api/commands/type.md b/docs/source/api/commands/type.md index fd94a57c5e..71a1b8441e 100644 --- a/docs/source/api/commands/type.md +++ b/docs/source/api/commands/type.md @@ -6,7 +6,6 @@ description: '' Type into a DOM element. - # Syntax ```javascript @@ -44,15 +43,15 @@ Sequence | Notes `{% raw %}{{{% endraw %}}`| Types the literal `{` key `{backspace}` | Deletes character to the left of the cursor `{del}` | Deletes character to the right of the cursor +`{downarrow}` | Fires down event but does **not** move the cursor `{enter}` | Types the Enter key `{esc}` | Types the Escape key `{leftarrow}` | Moves cursor left `{rightarrow}` | Moves cursor right -`{downarrow}` | Fires down event but does **not** move the cursor -`{uparrow}` | Fires up event but does **not** move the cursor `{selectall}` | Selects all text by creating a `selection range` +`{uparrow}` | Fires up event but does **not** move the cursor -Text passed to `cy.type` may also include any of the these modifier character sequences: +Text passed to `.type()` may also include any of the these modifier character sequences: Sequence | Notes --- | --- @@ -69,9 +68,9 @@ Option | Default | Notes --- | --- | --- `delay` | `10` | Delay after each keypress `force` | `false` | Forces type, disables error checking prior to type -`release` | `true` | Keep a modifier activated between commands `interval` | `16` | Interval to retry type `log` | `true` | Whether to display command in Command Log +`release` | `true` | Keep a modifier activated between commands `timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry the type ## Yields @@ -80,7 +79,7 @@ Option | Default | Notes ## Timeout -`.type()` will continue to retry typing for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) +`.type()` will continue to retry typing for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts). # Examples @@ -100,9 +99,9 @@ cy.get('textarea').type('Hello world') //yields