Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To verify an API request made by the application in a Cypress test, register cy.intercept() before the page load or user action that triggers it, alias the route, perform the action, then call cy.wait('@alias') and assert on the yielded request and response. Use cy.request() instead when the test itself should call an endpoint directly. These commands test different paths: cy.intercept() observes application traffic; cy.request() makes a direct call from Cypress.
Choose the Cypress command that matches the request
The key question is who initiates the HTTP call. If the browser application makes the request as a result of loading a page or interacting with it, use cy.intercept() with cy.wait(). If the test needs to call an endpoint directly and inspect its contract, use cy.request(). Cypress documents these as distinct API-testing approaches: intercepting application network requests and making direct API requests.
| Test goal | Use | What it verifies |
|---|---|---|
| Observe or stub a request initiated by the front-end application | cy.intercept() and cy.wait('@alias') |
The matching application request and, when available, its response |
| Call an endpoint from the test and check its response contract | cy.request() |
The direct call’s status, body, headers, or duration |
| Run Node-side work, such as database access or file I/O | cy.task() |
Work performed by the Node process, outside browser application traffic |
Because cy.request() is made by the Cypress Node process rather than the browser, cy.intercept() does not catch it. To verify a direct request, assert on the response yielded by cy.request(), not on an intercept alias. See the Cypress FAQ for the related question about why cy.intercept() does not match cy.request() calls.
Free tools Windows power users keep installed
One-click scans. No signup required.
Verify a request made by the application
Set up the intercept before the event that can generate the request. Give it an alias, perform the action, and wait for that alias. The interception yielded by cy.wait() includes the request and, if a response was received, the response. The example below checks the outgoing order payload, response status and returned identifier, then checks a separate visible UI result.
describe('placing an order', () => {
it('sends the order and shows confirmation', () => {
cy.intercept('POST', '/api/orders').as('createOrder')
cy.visit('/checkout')
cy.get('[data-testid="place-order"]').click()
cy.wait('@createOrder').then(({ request, response }) => {
expect(request.body).to.include({ productId: 'sku-123' })
expect(response.statusCode).to.eq(201)
expect(response.body).to.have.property('id')
})
cy.get('[data-testid="order-confirmation"]').should('be.visible')
})
})Registering the intercept before cy.visit() matters when the request happens during page load. In the example it is registered before both the visit and the click, so either event can safely trigger the matched route. Assertions on the network cycle establish what was sent and returned; the final retryable UI assertion establishes that the application displayed the expected result. One does not substitute for the other.
Match the route narrowly
Include the HTTP method and a URL or route matcher specific enough that an unrelated request cannot satisfy the wait. Cypress supports URL strings, glob patterns, regular expressions, and route matcher properties. When you provide multiple matcher properties, all of them must match. For example, a matcher can constrain the method, pathname and query instead of relying on a broad path fragment:
cy.intercept({
method: 'GET',
pathname: '/api/products',
query: { category: 'books' }
}).as('getBooks')Use the URL form that best fits the app’s requests. A literal string is suitable for a stable endpoint; a glob or regular expression can handle variable URL portions; a route matcher is useful when several request attributes matter. Avoid matching every request to a host if the test is supposed to prove that one particular call occurred.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchAssert only what the test is responsible for
Check request properties to verify that the app constructed the call correctly, and response properties to verify the server contract or a deliberately supplied stub. Common assertion targets include the URL, query, headers, body, response status and response body. If the test concerns an error path, verify the relevant error behavior too. Keep the assertions tied to the test’s purpose rather than checking unrelated implementation details.
Observe a real response or stub the route
An intercept can be used to observe traffic while allowing the request to reach its upstream server, or to control the response for a repeatable test. Use a real response when the test needs to exercise the integrated request and response path. Stub the response when you need a specific scenario, such as an empty result or an error, without depending on upstream data.
For example, this stub gives the application a predictable product list:
cy.intercept('GET', '/api/products', {
statusCode: 200,
body: [{ id: 'sku-123', name: 'Notebook' }]
}).as('getProducts')
cy.visit('/products')
cy.wait('@getProducts')
cy.get('[data-testid="product-sku-123"]').should('be.visible')The choice changes what the test proves. A stubbed response verifies how the app behaves for the response you supplied; it does not establish that the real upstream service returned that response. A real response can verify the integrated call, but its contents may depend on that service and its data.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Test an endpoint directly with cy.request()
When the purpose is to check an endpoint’s response rather than traffic initiated by the browser, make the request explicitly and assert on the yielded response. This example uses a relative URL, which is resolved in the context of the Cypress application’s configured base URL:
it('returns a created order from the API', () => {
cy.request('POST', '/api/orders', {
productId: 'sku-123'
}).then((response) => {
expect(response.status).to.eq(201)
expect(response.body).to.have.property('id')
expect(response.headers).to.have.property('content-type')
})
})Use this pattern for direct endpoint checks, such as validating a response body or status. It does not show that a page or user action caused the request: Cypress initiated the call. If the test needs to prove the front end sent the request, intercept the application’s call instead.
Understand what cy.wait('@alias') waits for
cy.wait('@alias') waits for the matching request/response cycle and yields its interception for inspection. It is not a retryable query. A chained assertion against the yielded interception gets a single attempt, so use it to inspect the completed network cycle rather than to wait for a later UI state to settle. Cypress documents this behavior in its cy.wait() command reference.
If the network assertion passes but the interface updates asynchronously afterward, make the UI check separately with a retryable Cypress query and assertion, such as cy.get(...).should(...). This separates two distinct expectations: the request completed with the expected properties, and the interface eventually reached the expected state.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Troubleshoot requests that are not verified
- The wait times out or never matches: Register the intercept before the page load or action that sends the request. Confirm the actual method and URL, then narrow or correct the matcher. A late intercept cannot observe a request that has already happened.
- An unrelated call satisfies the alias: The route is too broad. Add the HTTP method and a more specific URL, or constrain a route matcher with relevant properties such as pathname or query.
cy.intercept()does not match acy.request()call: That is expected.cy.request()runs from the Cypress Node process, not through browser application traffic. Assert on the direct request’s yielded response.- The network assertion passes but the UI assertion fails: A completed response does not by itself prove that the app rendered the right state. Check the UI with its own retryable assertion and confirm that the application handles the response as expected.
- A chained assertion after
cy.wait()is not retried: The wait yields a completed interception, and the chained assertion gets one attempt. Use the wait for request/response facts and a retryable Cypress query for UI conditions that may settle later. - A CI failure is difficult to diagnose: Cypress’s API Testing guide describes Test Replay as a way to inspect the command log for each test in a completed run, including request and response details. See the API Testing guide.
Keep the test reliable and focused
Separate network evidence from interface evidence
A useful end-to-end test often needs both: an interception assertion for the request contract and a UI assertion for the user-visible outcome. Keep them separate so a failure points toward either the network exchange or the page behavior rather than leaving the test’s proof ambiguous.
Use direct API tests for endpoint contracts
When the browser is not part of the requirement, cy.request() avoids making the endpoint check depend on a page interaction. Conversely, do not use a direct request as evidence that the app itself called the endpoint; only observe the application’s traffic when that is the behavior under test.
Choose real responses and stubs deliberately
Real upstream responses exercise integration, while stubs make a chosen response scenario explicit and controlled. State clearly in the test which one it uses, because the test’s conclusion should match the evidence it gathered.
Or skip the browser setup
If what you need is a screenshot of a website rather than verification of an API request made by a Cypress app, ScreenshotNeo can capture a page with one GET request. For example, this cURL command saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the API parameters. ScreenshotNeo removes cookie and consent banners, newsletter popups and chat widgets before capture; bot checks, blank pages and failed loads are not billed. It also has an MCP server for AI agents, and its free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. That is a separate tool for capturing website images or PDFs, not a replacement for Cypress assertions about application API traffic.
Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
Does an intercept prove that the user saw a successful result?
No. It establishes facts about the matching network exchange. Add a separate UI assertion when the test also needs to prove the visible outcome.
Should a test stub every API response?
No single choice fits every test. Stub when a controlled response scenario is the goal; observe a real upstream response when the integrated call is the behavior being tested.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
