explain the stubs better

Author: bahmutov

cypress/component/basic/stub-example/README.md

@@ -0,0 +1,34 @@
+# Stub examples
+
+You can pass a [cy.stub](https://on.cypress.io/stub) as a property to the mounted component and then assert it was invoked.
+
+```js
+it('calls the click prop', () => {
+  const onClick = cy.stub().as('clicker')
+  mount(<Clicker click={onClick} />)
+  cy.get('button')
+    .click()
+    .click()
+  cy.get('@clicker').should('have.been.calledTwice')
+})
+```
+
+![Stub](images/stub.png)
+
+## Tests
+
+- [clicker-spec.js](clicker-spec.js) passes a stub to the component and asserts it was called
+- [clicker-with-delay-spec.js](clicker-with-delay-spec.js) passes a stub to the component that is called on click, but only after a delay. Shows the difference between [.then](https://on.cypress.io/then) and [.should](https://on.cypress.io/should). Shows my favorite method of querying stubs via an alias
+
+```js
+const onClick = cy.stub().as('clicker')
+mount(<Clicker click={onClick} />)
+...
+cy.get('@clicker').should('have.been.calledTwice')
+```
+
+## More info
+
+Watch [Assert that the stub was called twice](https://youtu.be/AlltFcsIFvc) showing these specs.
+
+Read [Stubs, spies and clocks](https://on.cypress.io/stubs-spies-and-clocks) and [Retry-ability](https://on.cypress.io/retry-ability).

cypress/component/basic/stub-example/clicker-spec.js

@@ -1,12 +1,35 @@
 import React from 'react'
 import { mount } from 'cypress-react-unit-test'
-import Clicker from './clicker.jsx'
-
-it('passes stub to the component', () => {
-  const onClick = cy.stub().as('clicker')
-  mount(<Clicker click={onClick} />)
-  cy.get('button')
-    .click()
-    .click()
-  cy.get('@clicker').should('have.been.calledTwice')
+
+describe('Clicker', () => {
+  const Clicker = ({ click }) => (
+    <div>
+      <button onClick={click}>Click me</button>
+    </div>
+  )
+
+  it('calls the click prop twice', () => {
+    const onClick = cy.stub()
+    mount(<Clicker click={onClick} />)
+    cy.get('button')
+      .click()
+      .click()
+      .then(() => {
+        // works in this case, but not recommended
+        // because https://on.cypress.io/then does not retry
+        expect(onClick).to.be.calledTwice
+      })
+  })
+
+  it('calls the click prop: best practice', () => {
+    const onClick = cy.stub().as('clicker')
+    mount(<Clicker click={onClick} />)
+    cy.get('button')
+      .click()
+      .click()
+
+    // good practice 💡
+    // auto-retry the stub until it was called twice
+    cy.get('@clicker').should('have.been.calledTwice')
+  })
 })

cypress/component/basic/stub-example/clicker-with-delay-spec.js

@@ -0,0 +1,49 @@
+import React from 'react'
+import { mount } from 'cypress-react-unit-test'
+
+describe('Clicker with delay', () => {
+  const Clicker = ({ click }) => (
+    <div>
+      <button onClick={() => setTimeout(click, 500)}>Click me</button>
+    </div>
+  )
+
+  // Skipped because .then does not retry
+  // and will fail as soon as "expect" throws an error
+  it.skip('calls the click prop: then', () => {
+    const onClick = cy.stub()
+    mount(<Clicker click={onClick} />)
+    cy.get('button')
+      .click()
+      .click()
+      .then(() => {
+        expect(onClick).to.be.calledTwice
+      })
+  })
+
+  it('calls the click prop: should', () => {
+    const onClick = cy.stub()
+    mount(<Clicker click={onClick} />)
+    cy.get('button')
+      .click()
+      .click()
+      // test works because .should retries the assertion
+      // and in this case it will not click multiple times
+      // but just retry the assertion
+      .should(() => {
+        expect(onClick).to.be.calledTwice
+      })
+  })
+
+  it('calls the click prop', () => {
+    const onClick = cy.stub().as('clicker')
+    mount(<Clicker click={onClick} />)
+    cy.get('button')
+      .click()
+      .click()
+
+    // good practice 💡
+    // auto-retry the stub until it was called twice
+    cy.get('@clicker').should('have.been.calledTwice')
+  })
+})