{
"doc": {
"id": "app/guides/network-requests",
"title": "Network Requests: Cypress Guide",
"description": "Strategies for testing network requests in Cypress, stubbing and waiting for network responses, and best practices for testing GraphQL queries and mutations.",
"section": "app",
"source_path": "/llm/markdown/app/guides/network-requests.md",
"version": "e6988a974973e9090ce70406c38cb2b9e0eac9fa",
"updated_at": "2026-05-15T15:50:22.536Z",
"headings": [
{
"id": "app/guides/network-requests#network-requests",
"text": "Network Requests",
"level": 1
},
{
"id": "app/guides/network-requests#what-youll-learn",
"text": "What you'll learn",
"level": 5
},
{
"id": "app/guides/network-requests#testing-strategies",
"text": "Testing Strategies",
"level": 2
},
{
"id": "app/guides/network-requests#use-server-responses",
"text": "Use Server Responses",
"level": 3
},
{
"id": "app/guides/network-requests#stub-responses",
"text": "Stub Responses",
"level": 3
},
{
"id": "app/guides/network-requests#real-world-example",
"text": "Real World Example",
"level": 3
},
{
"id": "app/guides/network-requests#stubbing",
"text": "Stubbing",
"level": 2
},
{
"id": "app/guides/network-requests#routing",
"text": "Routing",
"level": 2
},
{
"id": "app/guides/network-requests#fixtures",
"text": "Fixtures",
"level": 2
},
{
"id": "app/guides/network-requests#organizing",
"text": "Organizing",
"level": 3
},
{
"id": "app/guides/network-requests#waiting",
"text": "Waiting",
"level": 2
},
{
"id": "app/guides/network-requests#flake",
"text": "Flake",
"level": 3
},
{
"id": "app/guides/network-requests#real-world-example",
"text": "Real World Example",
"level": 3
},
{
"id": "app/guides/network-requests#failures",
"text": "Failures",
"level": 3
},
{
"id": "app/guides/network-requests#assertions",
"text": "Assertions",
"level": 3
},
{
"id": "app/guides/network-requests#working-with-graphql",
"text": "Working with GraphQL",
"level": 2
},
{
"id": "app/guides/network-requests#alias-multiple-queries-or-mutations",
"text": "Alias multiple queries or mutations",
"level": 3
},
{
"id": "app/guides/network-requests#expectations-for-query-or-mutation-results",
"text": "Expectations for Query or Mutation Results",
"level": 3
},
{
"id": "app/guides/network-requests#modifying-a-query-or-mutation-response",
"text": "Modifying a Query or Mutation Response",
"level": 3
},
{
"id": "app/guides/network-requests#command-log",
"text": "Command Log",
"level": 2
},
{
"id": "app/guides/network-requests#see-also",
"text": "See also",
"level": 2
}
]
},
"content": {
"type": "root",
"children": [
{
"type": "heading",
"depth": 1,
"children": [
{
"type": "text",
"value": "Network Requests"
}
]
},
{
"type": "heading",
"depth": 5,
"children": [
{
"type": "text",
"value": "What you'll learn"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Strategies for testing network requests in Cypress"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "How to stub and wait for network responses"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Best practices for testing GraphQL queries and mutations"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Note: If you're looking for a resource to make an HTTP request take a look at "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/request.md",
"children": [
{
"type": "text",
"value": "cy.request()"
}
]
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Testing Strategies"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress helps you test the entire lifecycle of HTTP requests within your application. Cypress provides you access to the objects with information about the request, enabling you to make assertions about its properties. Additionally you can even stub and mock a request's response."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Common testing scenarios:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Asserting on a request's body"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Asserting on a request's url"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Asserting on a request's headers"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stubbing a response's body"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stubbing a response's status code"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stubbing a response's headers"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Delaying a response"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Waiting for a response to happen"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Within Cypress, you have the ability to choose whether to stub responses or allow them to actually hit your server. You can also mix and match within the same test by choosing to stub certain requests, while allowing others to hit your server."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Let's investigate both strategies, why you would use one versus the other, and why you should regularly use both."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Use Server Responses"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Requests that are not stubbed actually reach your server. By not stubbing your responses, you are writing true end-to-end tests. This means you are driving your application the same way a real user would."
}
]
},
{
"type": "blockquote",
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When requests are not stubbed, this guarantees that the contract between your client and server is working correctly."
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In other words, you can have confidence your server is sending the correct data in the correct structure to your client to consume. It is a good idea to have end-to-end tests around your application's critical paths. These typically include user login, signup, or other critical paths such as billing."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "There are downsides to not stubbing responses you should be aware of:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Since no responses are stubbed, that means your server has to actually send real responses. This can be problematic because you may have to seed a database before every test to generate state. For instance, if you were testing pagination, you'd have to seed the database with every object that it takes to replicate this feature in your application."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Since real responses go through every single layer of your server (controllers, models, views, etc) the tests are often much slower than stubbed responses."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If you are writing a traditional server-side application where most of the responses are HTML you will likely have few stubbed responses. However, most modern applications that serve JSON can take advantage of stubbing."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Benefits"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "More likely to work in production"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Test coverage around server endpoints"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Great for traditional server-side HTML rendering"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Downsides"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Requires seeding data"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Much slower"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Harder to test edge cases"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Suggested Use"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Use sparingly"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Great for the critical paths of your application"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Helpful to have one test around the happy path of a feature"
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Stub Responses"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stubbing responses enables you to control every aspect of the response, including the response `body`, the `status`, `headers`, and even network `delay`. Stubbing is extremely fast, most responses will be returned in less than 20ms."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Stubbing responses is a great way to control the data that is returned to your client."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "You don't have to do any work on the server. Your application will have no idea its requests are being stubbed, so there are no code changes needed."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Benefits"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Control of response bodies, status, and headers"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Can force responses to take longer to simulate network delay"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "No code changes to your server or client code"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Fast, < 20ms response times"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Downsides"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "No guarantee your stubbed responses match the actual data the server sends"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "No test coverage on some server endpoints"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Not as useful if you're using traditional server side HTML rendering"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Suggested Use"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Use for the vast majority of tests"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Mix and match, typically have one true end-to-end test, and then stub the rest"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Perfect for JSON APIs"
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Real World Example"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The Cypress "
},
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app",
"children": [
{
"type": "text",
"value": "Real World App (RWA)"
}
]
},
{
"type": "text",
"value": " end-to-end tests predominately rely on server responses, and only stub network responses "
},
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app/blob/07a6483dfe7ee44823380832b0b23a4dacd72504/cypress/tests/ui/notifications.spec.ts#L250-L264",
"children": [
{
"type": "text",
"value": "on a few occasions"
}
]
},
{
"type": "text",
"value": " to conveniently create edge-case or hard-to-create application states."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "This practice allows the project to achieve full "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/tooling/code-coverage.md",
"children": [
{
"type": "text",
"value": "code-coverage"
}
]
},
{
"type": "text",
"value": " for the front end and back end of the app, but this has also required creating intricate database seeding or test data factory scripts that can generate appropriate data in compliance with the business-logic of the app."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Check out any of the "
},
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app/tree/develop/cypress/tests/ui",
"children": [
{
"type": "text",
"value": "Real World App test suites"
}
]
},
{
"type": "text",
"value": " to see Cypress network handling in action."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Stubbing"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress enables you to stub a response and control the `body`, `status`, `headers`, or even delay."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "`cy.intercept()`"
}
]
},
{
"type": "text",
"value": " is used to control the behavior of HTTP requests. You can statically define the body, HTTP status code, headers, and other response characteristics."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "cy.intercept()"
}
]
},
{
"type": "text",
"value": " for more information and for examples on stubbing responses."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Routing"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept( { method: 'GET', // Route all GET requests url: '/users/*', // that have a URL that matches '/users/*' }, [] // and force the response to be: []).as('getUsers') // and assign an alias"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When you use "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "`cy.intercept()`"
}
]
},
{
"type": "text",
"value": " to define a route, Cypress displays this under \"Routes\" in the Command Log."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When a new test runs, Cypress will restore the default behavior and remove all routes and stubs. For a complete reference of the API and options, refer to the documentation for "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "`cy.intercept()`"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Fixtures"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "A fixture is a fixed set of data located in a file that is used in your tests. The purpose of a test fixture is to ensure that there is a well known and fixed environment in which tests are run so that results are repeatable. Fixtures are accessed within tests by calling the "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/fixture.md",
"children": [
{
"type": "text",
"value": "`cy.fixture()`"
}
]
},
{
"type": "text",
"value": " command."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "With Cypress, you can stub network requests and have it respond instantly with fixture data."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "When stubbing a response, you typically need to manage potentially large and complex JSON objects. Cypress allows you to integrate fixture syntax directly into responses."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// we set the response to be the activites.json fixturecy.intercept('GET', '/activities/*', { fixture: 'activities.json' })"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Organizing"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Cypress automatically scaffolds out a suggested folder structure for organizing your fixtures on every new project. By default it will create an `example.json` file when you add your project to Cypress."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "/cypress/fixtures/example.json"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Your fixtures can be further organized within additional folders. For instance, you could create another folder called `images` and add images:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "/cypress/fixtures/images/cats.png/cypress/fixtures/images/dogs.png/cypress/fixtures/images/birds.png"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "To access the fixtures nested within the `images` folder, include the folder in your "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/fixture.md",
"children": [
{
"type": "text",
"value": "`cy.fixture()`"
}
]
},
{
"type": "text",
"value": " command."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.fixture('images/dogs.png') // yields dogs.png as Base64"
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Waiting"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Whether or not you choose to stub responses, Cypress enables you to declaratively "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "`cy.wait()`"
}
]
},
{
"type": "text",
"value": " for requests and their responses."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Not sure how to structure intercepts and waits for your specific use case? Use the `/cypress-author` skill with your AI coding tool to generate the right pattern, or `/cypress-explain` to understand why a pattern is used before you change it. See "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/tooling/ai-skills.md",
"children": [
{
"type": "text",
"value": "Cypress AI Skills"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "This following section utilizes a concept known as "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/app/core-concepts/variables-and-aliases.md",
"children": [
{
"type": "text",
"value": "Aliasing"
}
]
},
{
"type": "text",
"value": ". If you're new to Cypress you might want to check that out first."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Here is an example of aliasing requests and then subsequently waiting on them:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "End-to-End Test"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Component Test"
}
]
}
]
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/activities/*', { fixture: 'activities' }).as('getActivities')cy.intercept('/messages/*', { fixture: 'messages' }).as('getMessages')// visiting the dashboard should make requests that match// the two routes abovecy.visit('http://localhost:8888/dashboard')// pass an array of Route Aliases that forces Cypress to wait// until it sees a response for each request that matches// each of these aliasescy.wait(['@getActivities', '@getMessages'])// these commands will not run until the wait command resolves abovecy.get('h1').should('contain', 'Dashboard')"
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/activities/*', { fixture: 'activities' }).as('getActivities')cy.intercept('/messages/*', { fixture: 'messages' }).as('getMessages')// mounting the dashboard should make requests that match// the two routes abovecy.mount()// pass an array of Route Aliases that forces Cypress to wait// until it sees a response for each request that matches// each of these aliasescy.wait(['@getActivities', '@getMessages'])// these commands will not run until the wait command resolves abovecy.get('h1').should('contain', 'Dashboard')"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If you would like to check the response data of each response of an aliased route, you can use several `cy.wait()` calls."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept({ method: 'POST', url: '/myApi',}).as('apiCheck')cy.visit('/')cy.wait('@apiCheck').then((interception) => { assert.isNotNull(interception.response.body, '1st API call has data')})cy.wait('@apiCheck').then((interception) => { assert.isNotNull(interception.response.body, '2nd API call has data')})cy.wait('@apiCheck').then((interception) => { assert.isNotNull(interception.response.body, '3rd API call has data')})"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Waiting on an aliased route has big advantages:"
}
]
},
{
"type": "list",
"ordered": true,
"start": 1,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Tests are more robust with much less flake."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Failure messages are much more precise."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "You can assert about the underlying request object."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Let's investigate each benefit."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Flake"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "One advantage of declaratively waiting for responses is that it decreases test flake. You can think of "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "`cy.wait()`"
}
]
},
{
"type": "text",
"value": " as a guard that indicates to Cypress when you expect a request to be made that matches a specific routing alias. This prevents the next commands from running until responses come back and it guards against situations where your requests are initially delayed."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Auto-complete Example:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "What makes this example below so powerful is that Cypress will automatically wait for a request that matches the `getSearch` alias. Instead of forcing Cypress to test the side effect of a successful request (the display of the Book results), you can test the actual cause of the results."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/search*', [{ item: 'Book 1' }, { item: 'Book 2' }]).as( 'getSearch')// our autocomplete field is throttled// meaning it only makes a request after// 500ms from the last keyPresscy.get('[data-testid=\"autocomplete\"]').type('Book')// wait for the request + response// thus insulating us from the// throttled requestcy.wait('@getSearch')cy.get('[data-testid=\"results\"]') .should('contain', 'Book 1') .and('contain', 'Book 2')"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Real World Example"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The Cypress "
},
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app",
"children": [
{
"type": "text",
"value": "Real World App (RWA)"
}
]
},
{
"type": "text",
"value": " has various tests for testing an auto-complete field within a large user journey test that properly await requests triggered upon auto-complete input changes. Check out the example:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app/blob/07a6483dfe7ee44823380832b0b23a4dacd72504/cypress/tests/ui/new-transaction.spec.ts#L36-L50",
"children": [
{
"type": "text",
"value": "Auto-complete test code"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://cloud.cypress.io/projects/7s5okt/runs/2352/test-results/3bf064fd-6959-441c-bf31-a9f276db0627/video",
"children": [
{
"type": "text",
"value": "Auto-complete test run video recording"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": true,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://cloud.cypress.io/projects/7s5okt/runs/2352/test-results/3bf064fd-6959-441c-bf31-a9f276db0627/video",
"children": [
{
"type": "text",
"value": "Auto-complete test run video recording"
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "in Cypress Dashboard."
}
]
}
]
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Failures"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In our example above, we added an assertion to the display of the search results."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The search results working are coupled to a few things in our application:"
}
]
},
{
"type": "list",
"ordered": true,
"start": 1,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Our application making a request to the correct URL."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Our application correctly processing the response."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Our application inserting the results into the DOM."
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In this example, there are many possible sources of failure. In most testing tools, if our request failed to go out, we would normally only ever get an error once we attempt to find the results in the DOM and see that there is no matching element. This is problematic because it's unknown why the results failed to be displayed. Was there a problem with our rendering code? Did we modify or change an attribute such as an `id` or `class` on an element? Perhaps our server sent us different Book items."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "With Cypress, by adding a "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "`cy.wait()`"
}
]
},
{
"type": "text",
"value": ", you can more easily pinpoint your specific problem. If the response never came back, you'll receive an error like this:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Now we know exactly why our test failed. It had nothing to do with the DOM. Instead we can see that either our request never went out or a request went out to the wrong URL."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Assertions"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Another benefit of using "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "`cy.wait()`"
}
]
},
{
"type": "text",
"value": " on requests is that it allows you to access the actual request object. This is useful when you want to make assertions about this object."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In our example above we can assert about the request object to verify that it sent data as a query string in the URL. Although we're mocking the response, we can still verify that our application sends the correct request."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// any request to \"/search/*\" endpoint will// automatically receive an array with two book objectscy.intercept('/search/*', [{ item: 'Book 1' }, { item: 'Book 2' }]).as( 'getSearch')cy.get('[data-testid=\"autocomplete\"]').type('Book')// this yields us the interception cycle object// which includes fields for the request and responsecy.wait('@getSearch').its('request.url').should('include', '/search?query=Book')cy.get('[data-testid=\"results\"]') .should('contain', 'Book 1') .and('contain', 'Book 2')"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The interception object that "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "`cy.wait()`"
}
]
},
{
"type": "text",
"value": " yields you has everything you need to make assertions including:"
}
]
},
{
"type": "list",
"ordered": false,
"start": null,
"spread": false,
"children": [
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "URL"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Method"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Status Code"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Request Body"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Request Headers"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Response Body"
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Response Headers"
}
]
}
]
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Examples"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// spy on POST requests to /users endpointcy.intercept('POST', '/users').as('new-user')// trigger network calls by manipulating web app's// user interface, thency.wait('@new-user').should('have.property', 'response.statusCode', 201)// we can grab the completed interception object// again to run more assertions using cy.get()cy.get('@new-user') // yields the same interception object .its('request.body') .should( 'deep.equal', JSON.stringify({ id: '101', firstName: 'Joe', lastName: 'Black', }) )// and we can place multiple assertions in a// single \"should\" callbackcy.get('@new-user').should(({ request, response }) => { expect(request.url).to.match(/\\/users$/) expect(request.method).to.equal('POST') // it is a good practice to add assertion messages // as the 2nd argument to expect() expect(response.headers, 'response headers').to.include({ 'cache-control': 'no-cache', expires: '-1', 'content-type': 'application/json; charset=utf-8', location: '/users/101', })})"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Tip: you can inspect the full request cycle object by logging it to the console"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.wait('@new-user').then(console.log)"
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Working with GraphQL"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The strategies below follow best known practices for waiting and asserting against GraphQL queries or mutations."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Waiting and asserting on GraphQL API requests rely on matching a query or mutation name in the POST body."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Using "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "cy.intercept()"
}
]
},
{
"type": "text",
"value": " we can override the response to a GraphQL query or mutation by declaring an intercept at the beginning of the test or closer to the expectation."
}
]
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Alias multiple queries or mutations"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In the `beforeEach`, we will use "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md",
"children": [
{
"type": "text",
"value": "cy.intercept()"
}
]
},
{
"type": "text",
"value": " to capture all requests for a GraphQL endpoint (e.g. `/graphql`), use conditionals to match the query or mutation and set an alias for using `req.alias`."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "First, we'll create a set of utility functions to help match and alias our queries and mutations."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// utils/graphql-test-utils.js// Utility to match GraphQL mutation based on the operation nameexport const hasOperationName = (req, operationName) => { const { body } = req return ( Object.prototype.hasOwnProperty.call(body, 'operationName') && body.operationName === operationName )}// Alias query if operationName matchesexport const aliasQuery = (req, operationName) => { if (hasOperationName(req, operationName)) { req.alias = `gql${operationName}Query` }}// Alias mutation if operationName matchesexport const aliasMutation = (req, operationName) => { if (hasOperationName(req, operationName)) { req.alias = `gql${operationName}Mutation` }}"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In our test file, we can import these utilities and use them to alias the queries and mutations for our tests in a `beforeEach`."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// app.cy.jsimport { aliasQuery, aliasMutation } from '../utils/graphql-test-utils'context('Tests', () => { beforeEach(() => { cy.intercept('POST', 'http://localhost:3000/graphql', (req) => { // Queries aliasQuery(req, 'GetLaunchList') aliasQuery(req, 'LaunchDetails') aliasQuery(req, 'GetMyTrips') // Mutations aliasMutation(req, 'Login') aliasMutation(req, 'BookTrips') }) }) // ...})"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Expectations for Query or Mutation Results"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Expectations can be made against the response of an intercepted GraphQL query or mutation using "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/wait.md",
"children": [
{
"type": "text",
"value": "cy.wait()"
}
]
},
{
"type": "text",
"value": "."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// app.cy.jsimport { aliasQuery } from '../utils/graphql-test-utils'context('Tests', () => { beforeEach(() => { cy.intercept('POST', 'http://localhost:3000/graphql', (req) => { // Queries aliasQuery(req, 'Login') // ... }) }) it('should verify login data', () => { cy.wait('@gqlLoginQuery') .its('response.body.data.login') .should('have.property', 'id') .and('have.property', 'token') })})"
},
{
"type": "heading",
"depth": 3,
"children": [
{
"type": "text",
"value": "Modifying a Query or Mutation Response"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "In the test below, the response is modified to test the UI for a single page of results."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "// app.cy.jsimport { hasOperationName, aliasQuery } from '../utils/graphql-test-utils'context('Tests', () => { beforeEach(() => { cy.intercept('POST', 'http://localhost:3000/graphql', (req) => { // Queries aliasQuery(req, 'GetLaunchList') // ... }) }) it('should not display the load more button on the launches page', () => { cy.intercept('POST', 'http://localhost:3000/graphql', (req) => { if (hasOperationName(req, 'GetLaunchList')) { // Declare the alias from the initial intercept in the beforeEach req.alias = 'gqlGetLaunchListQuery' // Set req.fixture or use req.reply to modify portions of the response req.reply((res) => { // Modify the response body directly res.body.data.launches.hasMore = false res.body.data.launches.launches = res.body.data.launches.launches.slice(5) }) } }) // Must visit after cy.intercept cy.visit('/') cy.wait('@gqlGetLaunchListQuery') .its('response.body.data.launches') .should((launches) => { expect(launches.hasMore).to.be.false expect(launches.length).to.be.lte(20) }) cy.get('#launch-list').its('length').should('be.gte', 1).and('be.lt', 20) cy.contains('button', 'Load More').should('not.exist') })})"
},
{
"type": "heading",
"depth": 2,
"children": [
{
"type": "text",
"value": "Command Log"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "By default, Cypress logs all `XMLHttpRequest`s and `fetch`es made by the application under test in the Command Log. Here is an example of what this looks like:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Note: Logging can be disabled by passing `{ log: false }` with the static response."
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/users*', { body: ['user1', 'user2'], log: false }).as('getUsers')"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "To disable logs for all xhr/fetch requests, checkout our "
},
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/intercept.md#Disabling-logs-for-a-request",
"children": [
{
"type": "text",
"value": "example"
}
]
},
{
"type": "text",
"value": " on the intercept api page."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The circular indicator on the left side indicates if the request went to the destination server or not. If the circle is solid, the request went to the destination server; if it is outlined, the response was stubbed by `cy.intercept()` and not sent outbound."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If we re-run our previous test to make the same requests, but this time, add a `cy.intercept()` to stub the response to `/users`, we can see that the indicator changes. After adding the following line:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/users*', ['user1', 'user2']).as('getUsers')"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The Command Log will look like this:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The `fetch` request now has an open circle, to indicate that it has been stubbed. Also, note that the alias for the `cy.intercept()` is now displayed on the right-hand side of the Command Log. If you mouse over the alias, you can see more information about how the request was handled:"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Additionally, the request will be flagged if the request and/or response was modified by a `cy.intercept()` handler function. If we add this code to modify outgoing requests to `/users`:"
}
]
},
{
"type": "code",
"lang": null,
"meta": null,
"value": "cy.intercept('/users*', (req) => { req.headers['authorization'] = 'bearer my-bearer-auth-token'}).as('addAuthHeader')"
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "The request log for `/users` will reflect that the `req` object was modified, but the request was still fulfilled from the destination (filled indicator):"
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "As you can see, \"req modified\" is displayed in the badge, to indicate the request object was modified. \"res modified\" and \"req + res modified\" can also be displayed, depending on if `res` was modified inside of a `req.continue()` callback."
}
]
},
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "As with all command logs, logs for network requests can be clicked to display additional information in the Console. For example, after clicking the previous request for `/users?limit=100` and opening Developer Tools, we can see the following:"
}
]
},
{
"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/intercept.md",
"children": [
{
"type": "text",
"value": "`cy.intercept()` docs"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-example-kitchensink/blob/master/cypress/e2e/2-advanced-examples/network_requests.cy.js",
"children": [
{
"type": "text",
"value": "Network requests in Kitchen Sink example"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "/llm/markdown/api/commands/request.md",
"children": [
{
"type": "text",
"value": "See how to make a request with `cy.request()`"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "link",
"title": null,
"url": "https://github.com/cypress-io/cypress-realworld-app",
"children": [
{
"type": "text",
"value": "Real World App (RWA)"
}
]
},
{
"type": "text",
"value": " test suites to see Cypress network handling in action."
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "Read the blog post "
},
{
"type": "link",
"title": null,
"url": "https://www.cypress.io/blog/2019/12/23/asserting-network-calls-from-cypress-tests/",
"children": [
{
"type": "text",
"value": "Asserting Network Calls from Cypress Tests"
}
]
}
]
}
]
},
{
"type": "listItem",
"spread": false,
"checked": null,
"children": [
{
"type": "paragraph",
"children": [
{
"type": "text",
"value": "If you want to test the application in offline mode, read "
},
{
"type": "link",
"title": null,
"url": "https://www.cypress.io/blog/2020/11/12/testing-application-in-offline-network-mode/",
"children": [
{
"type": "text",
"value": "Testing an Application in Offline Network Mode"
}
]
}
]
}
]
}
]
}
]
},
"token_estimate": 4049
}