Add Cypress.sinon doc (cypress-io#2608)

* Add Cypress.sinon doc

* Add more interlinking between docs for utilities + sinon doc.

* fix missing url tag

* expand the text

* explain the links a little

Co-authored-by: Gleb Bahmutov <[email protected]>

source/_data/sidebar.yml

@@ -152,6 +152,7 @@ api:
     minimatch: minimatch.html
     moment: moment.html
     promise: promise.html
+    sinon: sinon.html
   cypress-api:
     custom-commands: custom-commands.html
     cookies: cookies.html

source/api/utilities/$.md

@@ -78,3 +78,7 @@ cy.$$.each([1, 2, 3], (index, value) => {
   expect(index).to.eq(value)
 }) // fails
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}

source/api/utilities/_.md

@@ -55,3 +55,7 @@ cy
     expect(ids).to.deep.eq([1, 2, 3])
   })
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}

source/api/utilities/blob.md

@@ -62,3 +62,7 @@ return Cypress.Blob.imgSrcToDataURL('/assets/img/logo.png').then((dataUrl) => {
   cy.get('.utility-blob img').click().should('have.attr', 'src', dataUrl)
 })
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}

source/api/utilities/minimatch.md

@@ -66,3 +66,7 @@ Cypress.minimatch('/foo/bar/baz/123/quux?a=b&c=2', '/foo/*', {
   matchBase: false
 })
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}

source/api/utilities/moment.md

@@ -36,3 +36,8 @@ const todaysDate = Cypress.moment().format('MMM DD, YYYY')
 
 cy.get('span').should('contain', 'Order shipped on: ' + todaysDate)
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}
+- {% url `cy.clock()` clock %}

source/api/utilities/promise.md

@@ -69,3 +69,7 @@ it('waits for promises to resolve', function () {
   })
 })
 ```
+
+# See also
+
+- {% url 'Bundled Tools' bundled-tools %}

source/api/utilities/sinon.md

@@ -0,0 +1,66 @@
+---
+title: Cypress.sinon
+---
+
+Cypress automatically includes {% url 'Sinon.JS' http://sinonjs.org/ %} and exposes it as `Cypress.sinon`. Because commands {% url `cy.spy` spy %} and {% url `cy.stub` stub %} are already wrapping Sinon methods, the most common use for `Cypress.sinon` is to provide flexible {% url matchers https://sinonjs.org/releases/latest/matchers/ %} when doing assertions.
+
+# Syntax
+
+```javascript
+Cypress.sinon.match(value)
+Cypress.sinon.match.<matcher name>
+```
+
+## Usage
+
+**{% fa fa-check-circle green %} Correct Usage**
+
+```javascript
+Cypress.sinon.match.string
+```
+
+**{% fa fa-exclamation-triangle red %} Incorrect Usage**
+
+```javascript
+cy.sinon.match.string // Errors, cannot be chained off 'cy'
+```
+
+# Examples
+
+## `match.string`
+
+This example comes from the recipe {% url "Root style" https://github.com/cypress-io/cypress-example-recipes#testing-the-dom %}. Imagine an application code where the method `setProperty` is called to change a CSS variable:
+
+```js
+document.querySelector('input[type=color]').addEventListener('change', (e) => {
+  document.documentElement.style.setProperty('--background-color', e.target.value)
+})
+```
+
+We can write a test to confirm that the method `setProperty` was called with two strings; we don't care about value of the first string, but we do want to check if it was indeed a string.
+
+```javascript
+cy.document()
+  .its('documentElement.style')
+  .then((style) => {
+    cy.spy(style, 'setProperty').as('setColor')
+  })
+
+cy.get('input[type=color]')
+  .invoke('val', '#ff0000')
+  .trigger('change')
+
+// we don't care about '--background-color' exact
+// value but know it should be a string
+cy.get('@setColor')
+  .should('have.been.calledWith', Cypress.sinon.match.string, '#ff0000')
+```
+
+# See also
+
+- {% url 'Spies, stubs & clocks' https://example.cypress.io/commands/spies-stubs-clocks %} example page
+- {% url 'Sinon matchers' https://sinonjs.org/releases/latest/matchers/ %} documentation page
+- {% url 'Bundled Tools' bundled-tools %}
+- {% url `cy.spy()` spy %}
+- {% url `cy.stub()` stub %}
+- {% url "Stubs, Spies, and Clocks" stubs-spies-and-clocks %} guide

source/guides/references/bundled-tools.md

@@ -51,6 +51,8 @@ When writing integration tests, you will likely work a lot with the DOM. Cypress
 
 When writing unit tests, or even in integration-like tests, you often need to ability to stub and spy methods. Cypress includes two methods, {% url `cy.stub()` stub %} and {% url `cy.spy()` spy %} that return Sinon stubs and spies, respectively.
 
+Cypress also exposes a utility so that `sinon` can be called anywhere inside of your tests using {% url `Cypress.sinon` sinon %}.
+
 {% note info %}
 {% url "Check out our guide for working with spies, stubs, and clocks." stubs-spies-and-clocks %}
 {% endnote %}

themes/cypress/languages/en.yml

@@ -175,6 +175,7 @@ sidebar:
     moment: moment
     blob: Blob
     promise: Promise
+    sinon: sinon
     cypress-api: Cypress API
     config: config
     env: env

themes/cypress/languages/ja.yml

@@ -175,6 +175,7 @@ sidebar:
     moment: moment
     blob: Blob
     promise: Promise
+    sinon: sinon
     cypress-api: Cypress API
     config: config
     env: env

themes/cypress/languages/pt-br.yml

@@ -175,6 +175,7 @@ sidebar:
     moment: moment
     blob: Blob
     promise: Promise
+    sinon: sinon
     cypress-api: Cypress API
     config: config
     env: env

themes/cypress/languages/ru.yml

@@ -175,6 +175,7 @@ sidebar:
     moment: moment
     blob: Blob
     promise: Promise
+    sinon: sinon
     cypress-api: Cypress API
     config: config
     env: env

themes/cypress/languages/zh-cn.yml

@@ -177,6 +177,7 @@ sidebar:
     moment: moment
     blob: Blob
     promise: Promise
+    sinon: sinon
     cypress-api: Cypress API
     config: config
     env: env