{
  "doc": {
    "id": "api/commands/spy",
    "title": "spy | Cypress Documentation",
    "description": "Wrap a method in a spy in order to record calls to and arguments of the function in Cypress.",
    "section": "api",
    "source_path": "/llm/markdown/api/commands/spy.md",
    "version": "3cf5b86b3403f604bdf7f3e35025c3bc3865e02c",
    "updated_at": "2026-05-07T17:44:31.931Z",
    "headings": [
      {
        "id": "api/commands/spy#spy",
        "text": "spy",
        "level": 1
      },
      {
        "id": "api/commands/spy#syntax",
        "text": "Syntax",
        "level": 2
      },
      {
        "id": "api/commands/spy#usage",
        "text": "Usage",
        "level": 3
      },
      {
        "id": "api/commands/spy#arguments",
        "text": "Arguments",
        "level": 3
      },
      {
        "id": "api/commands/spy#yields-learn-about-subject-management",
        "text": "Yields Learn about subject management",
        "level": 3
      },
      {
        "id": "api/commands/spy#examples",
        "text": "Examples",
        "level": 2
      },
      {
        "id": "api/commands/spy#method",
        "text": "Method",
        "level": 3
      },
      {
        "id": "api/commands/spy#wrap-a-method-with-a-spy",
        "text": "Wrap a method with a spy",
        "level": 4
      },
      {
        "id": "api/commands/spy#disable-logging-to-command-log",
        "text": "Disable logging to Command Log",
        "level": 4
      },
      {
        "id": "api/commands/spy#more-cy-spy-examples",
        "text": "More cy.spy() examples",
        "level": 4
      },
      {
        "id": "api/commands/spy#aliases",
        "text": "Aliases",
        "level": 3
      },
      {
        "id": "api/commands/spy#notes",
        "text": "Notes",
        "level": 2
      },
      {
        "id": "api/commands/spy#restores",
        "text": "Restores",
        "level": 3
      },
      {
        "id": "api/commands/spy#automatic-reset-restore-between-tests",
        "text": "Automatic reset/restore between tests",
        "level": 4
      },
      {
        "id": "api/commands/spy#differences",
        "text": "Differences",
        "level": 3
      },
      {
        "id": "api/commands/spy#difference-between-cy-spy-and-cy-stub",
        "text": "Difference between cy.spy() and cy.stub()",
        "level": 4
      },
      {
        "id": "api/commands/spy#assertions",
        "text": "Assertions",
        "level": 3
      },
      {
        "id": "api/commands/spy#assertion-support",
        "text": "Assertion Support",
        "level": 4
      },
      {
        "id": "api/commands/spy#command-log",
        "text": "Command Log",
        "level": 2
      },
      {
        "id": "api/commands/spy#history",
        "text": "History",
        "level": 2
      },
      {
        "id": "api/commands/spy#see-also",
        "text": "See also",
        "level": 2
      }
    ]
  },
  "content": {
    "type": "root",
    "children": [
      {
        "type": "heading",
        "depth": 1,
        "children": [
          {
            "type": "text",
            "value": "spy"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Wrap a method in a spy in order to record calls to and arguments of the function."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.spy()` is a utility function, and is not a Cypress command, query or assertion. It is not retryable, chainable, or timeout-able."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Note: `.spy()` assumes you are already familiar with our guide: "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/guides/stubs-spies-and-clocks.md",
            "children": [
              {
                "type": "text",
                "value": "Stubs, Spies, and Clocks"
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Syntax"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.spy(object, method)"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Usage"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Correct Usage"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "cy.spy(user, 'addFriend')cy.spy(user, 'addFriend').as('addFriend')"
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Arguments"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "object (Object)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The `object` that has the `method` to be wrapped."
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "method (String)"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The name of the `method` on the `object` to be wrapped."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Yields "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management",
            "children": [
              {
                "type": "text",
                "value": "Learn about subject management"
              }
            ]
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.spy()` is synchronous and returns a value (the spy) instead of a Promise-like chain-able object. It can be aliased."
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.spy()` returns a "
                  },
                  {
                    "type": "link",
                    "title": null,
                    "url": "https://sinonjs.org/releases/v8/spies/",
                    "children": [
                      {
                        "type": "text",
                        "value": "Sinon.js spy"
                      }
                    ]
                  },
                  {
                    "type": "text",
                    "value": ". All methods found on Sinon.JS spies are supported."
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Examples"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Method"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Wrap a method with a spy"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "// assume App.start calls util.addListenerscy.spy(util, 'addListeners')App.start()expect(util.addListeners).to.be.called"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Disable logging to Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can chain a `.log(bool)` method to disable `cy.spy()` calls from being shown in the Command Log. This may be useful when your stubs are called an excessive number of times."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const spy = cy.spy(obj, 'foo').log(false)"
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "More `cy.spy()` examples"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/recipes.md#Stubbing-and-spying",
            "children": [
              {
                "type": "text",
                "value": "Check out our example recipe testing spying, stubbing and time"
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Aliases"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You can alias spies, similar to how "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/as.md",
            "children": [
              {
                "type": "text",
                "value": "`.as()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " works. This can make your spies easier to identify in error messages and Cypress's command log, and allows you to assert against them later using `cy.get()`."
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const spy = cy.spy(obj, 'foo').as('anyArgs')const withFoo = spy.withArgs('foo').as('withFoo')obj.foo()expect(spy).to.be.calledcy.get('@withFoo').should('be.called') // purposefully failing assertion"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "You will see the following in the command log:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Notes"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Restores"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Automatic reset/restore between tests"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "`cy.spy()` creates spies in a "
          },
          {
            "type": "link",
            "title": null,
            "url": "https://sinonjs.org/releases/v8/sandbox/",
            "children": [
              {
                "type": "text",
                "value": "sandbox"
              }
            ]
          },
          {
            "type": "text",
            "value": ", so all spies created are automatically reset/restored between tests without you having to explicitly reset/restore them."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Differences"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Difference between cy.spy() and cy.stub()"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The main difference between `cy.spy()` and "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/api/commands/stub.md",
            "children": [
              {
                "type": "text",
                "value": "`cy.stub()`"
              }
            ]
          },
          {
            "type": "text",
            "value": " 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."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 3,
        "children": [
          {
            "type": "text",
            "value": "Assertions"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 4,
        "children": [
          {
            "type": "text",
            "value": "Assertion Support"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Cypress has also built-in "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/bundled-libraries.md#Sinon-Chai",
            "children": [
              {
                "type": "text",
                "value": "Sinon-Chai"
              }
            ]
          },
          {
            "type": "text",
            "value": " support, so any "
          },
          {
            "type": "link",
            "title": null,
            "url": "/llm/markdown/app/references/assertions.md#Sinon-Chai",
            "children": [
              {
                "type": "text",
                "value": "assertions supported by `Sinon-Chai`"
              }
            ]
          },
          {
            "type": "text",
            "value": " can be used without any configuration."
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "Command Log"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "Create a spy, alias it, and call it"
          }
        ]
      },
      {
        "type": "code",
        "lang": null,
        "meta": null,
        "value": "const obj = {  foo() {},}const spy = cy.spy(obj, 'foo').as('foo')obj.foo('foo', 'bar')expect(spy).to.be.called"
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "The command above will display in the Command Log as:"
          }
        ]
      },
      {
        "type": "paragraph",
        "children": [
          {
            "type": "text",
            "value": "When clicking on the `spy-1` event within the command log, the console outputs the following:"
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "History"
          }
        ]
      },
      {
        "type": "table",
        "align": [
          null,
          null
        ],
        "children": [
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Version"
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Changes"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#0-20-0",
                    "children": [
                      {
                        "type": "text",
                        "value": "0.20.0"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "Added `.log(bool)` method"
                  }
                ]
              }
            ]
          },
          {
            "type": "tableRow",
            "children": [
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/changelog.md#0-18-8",
                    "children": [
                      {
                        "type": "text",
                        "value": "0.18.8"
                      }
                    ]
                  }
                ]
              },
              {
                "type": "tableCell",
                "children": [
                  {
                    "type": "text",
                    "value": "`cy.spy()` command added"
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "type": "heading",
        "depth": 2,
        "children": [
          {
            "type": "text",
            "value": "See also"
          }
        ]
      },
      {
        "type": "list",
        "ordered": false,
        "start": null,
        "spread": false,
        "children": [
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/as.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`.as()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/clock.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.clock()`"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/guides/stubs-spies-and-clocks.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "Guide: Stubs, Spies and Clocks"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/app/references/recipes.md#Stubbing-and-spying",
                    "children": [
                      {
                        "type": "text",
                        "value": "Recipe: Stubbing, Spying"
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "listItem",
            "spread": false,
            "checked": null,
            "children": [
              {
                "type": "paragraph",
                "children": [
                  {
                    "type": "link",
                    "title": null,
                    "url": "/llm/markdown/api/commands/stub.md",
                    "children": [
                      {
                        "type": "text",
                        "value": "`cy.stub()`"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "token_estimate": 664
}