feat: add example how spy retries following assertions (#204)

Author: bahmutov

app/commands/spies-stubs-clocks.html

@@ -74,11 +74,11 @@ <h1>Spies, Stubs &amp; Clocks</h1>
         <div class="col-xs-12">
           <h4><a href="https://on.cypress.io/spy">cy.spy()</a></h4>
           <p>To wrap a method in a spy, use the <a href="https://on.cypress.io/spy"><code>cy.spy()</code></a> command.</p>
-          <pre><code class="javascript">let obj = {
+          <pre><code class="javascript">const obj = {
   foo () {},
 }
 
-let spy = cy.spy(obj, 'foo').as('anyArgs')
+const spy = cy.spy(obj, 'foo').as('anyArgs')
 
 obj.foo()
 
@@ -87,14 +87,36 @@ <h4><a href="https://on.cypress.io/spy">cy.spy()</a></h4>
 
         <div class="col-xs-12"><hr></div>
 
+        <div class="col-xs-12">
+          <p><a href="https://on.cypress.io/spy"><code>cy.spy()</code></a> retries until the
+            assertions that follow it pass.</p>
+          <pre><code class="javascript">const obj = {
+  foo () {},
+}
+
+cy.spy(obj, 'foo').as('foo')
+
+setTimeout(() => {
+  obj.foo()
+}, 500)
+
+setTimeout(() => {
+  obj.foo()
+}, 2500)
+
+cy.get('@foo').should('have.been.calledTwice')</code></pre>
+        </div>
+
+        <div class="col-xs-12"><hr></div>
+
         <div class="col-xs-12">
           <h4><a href="https://on.cypress.io/stub">cy.stub()</a></h4>
           <p>To create a stub and/or replace a function with a stub, use the <a href="https://on.cypress.io/stub"><code>cy.stub()</code></a> command.</p>
           <pre><code class="javascript">let obj = {
   foo () {},
 }
 
-let stub = cy.stub(obj, 'foo').as('foo')
+const stub = cy.stub(obj, 'foo').as('foo')
 
 obj.foo('foo', 'bar')
 
@@ -108,7 +130,7 @@ <h4><a href="https://on.cypress.io/clock">cy.clock()</a></h4>
           <p>To control time in the browser, use the <a href="https://on.cypress.io/clock"><code>cy.clock()</code></a> command.</p>
           <pre><code class="javascript">// create the date in UTC so its always the same
 // no matter what local timezone the browser is running in
-let now = new Date(Date.UTC(2017, 2, 14)).getTime()
+const now = new Date(Date.UTC(2017, 2, 14)).getTime()
 
 cy.clock(now)
 cy.visit('http://localhost:8080/commands/spies-stubs-clocks')
@@ -130,7 +152,7 @@ <h4><a href="https://on.cypress.io/tick">cy.tick()</a></h4>
           <p>To move time in the browser, use the <a href="https://on.cypress.io/tick"><code>cy.tick()</code></a> command.</p>
           <pre><code class="javascript">// create the date in UTC so its always the same
 // no matter what local timezone the browser is running in
-let now = new Date(Date.UTC(2017, 2, 14)).getTime()
+const now = new Date(Date.UTC(2017, 2, 14)).getTime()
 
 cy.clock(now)
 cy.visit('http://localhost:8080/commands/spies-stubs-clocks')

cypress/integration/examples/spies_stubs_clocks.spec.js

@@ -5,22 +5,49 @@ context('Spies, Stubs, and Clock', () => {
     // https://on.cypress.io/spy
     cy.visit('http://localhost:8080/commands/spies-stubs-clocks')
 
-    let obj = {
+    const obj = {
       foo () {},
     }
 
-    let spy = cy.spy(obj, 'foo').as('anyArgs')
+    const spy = cy.spy(obj, 'foo').as('anyArgs')
 
     obj.foo()
 
     expect(spy).to.be.called
   })
 
+  it('cy.spy() retries until assertions pass', () => {
+    cy.visit('http://localhost:8080/commands/spies-stubs-clocks')
+
+    const obj = {
+      /**
+       * Prints the argument passed
+       * @param x {any}
+      */
+      foo (x) {
+        /* eslint-disable-next-line no-console */
+        console.log('obj.foo called with', x)
+      },
+    }
+
+    cy.spy(obj, 'foo').as('foo')
+
+    setTimeout(() => {
+      obj.foo('first')
+    }, 500)
+
+    setTimeout(() => {
+      obj.foo('second')
+    }, 2500)
+
+    cy.get('@foo').should('have.been.calledTwice')
+  })
+
   it('cy.stub() - create a stub and/or replace a function with stub', () => {
     // https://on.cypress.io/stub
     cy.visit('http://localhost:8080/commands/spies-stubs-clocks')
 
-    let obj = {
+    const obj = {
       /**
        * prints both arguments to the console
        * @param a {string}
@@ -32,7 +59,7 @@ context('Spies, Stubs, and Clock', () => {
       },
     }
 
-    let stub = cy.stub(obj, 'foo').as('foo')
+    const stub = cy.stub(obj, 'foo').as('foo')
 
     obj.foo('foo', 'bar')
 
@@ -44,7 +71,7 @@ context('Spies, Stubs, and Clock', () => {
 
     // create the date in UTC so its always the same
     // no matter what local timezone the browser is running in
-    let now = new Date(Date.UTC(2017, 2, 14)).getTime()
+    const now = new Date(Date.UTC(2017, 2, 14)).getTime()
 
     cy.clock(now)
     cy.visit('http://localhost:8080/commands/spies-stubs-clocks')
@@ -57,7 +84,7 @@ context('Spies, Stubs, and Clock', () => {
 
     // create the date in UTC so its always the same
     // no matter what local timezone the browser is running in
-    let now = new Date(Date.UTC(2017, 2, 14)).getTime()
+    const now = new Date(Date.UTC(2017, 2, 14)).getTime()
 
     cy.clock(now)
     cy.visit('http://localhost:8080/commands/spies-stubs-clocks')