In Cypress, how do you make a `cy.intercept()` route match only one of two same-path requests?

A weather dashboard often calls one endpoint several times with different intent: the map asks `/api/forecast?station=KSEA&units=metric`, the sidebar asks the same path with `units=imperial`, and a background poller re-asks it every thirty seconds with an `x-poll: true` header. A route matched on the path alone catches all three. Narrowing is a matter of adding properties to the `routeMatcher`, because everything you set has to match. ## Add a property, not a longer glob Every property on a `routeMatcher` is ANDed with the others, so precision comes from *more fields*, not from a cleverer URL pattern: - `query` — a dictionary matched parameter by parameter. `query: { units: 'metric' }` separates the map's call from the sidebar's without touching the path. - `headers` — a dictionary matched header by header. Cypress lowercases the names you give it, because HTTP header field names are case-insensitive, and rejects the same header supplied twice in different cases. - `hostname`, `port`, `https` — the origin. Useful for keeping a route off a third-party tile or telemetry host that happens to share a path shape. - `auth` — the username and password carried in HTTP Basic credentials. - `method` — often the cheapest discriminator of all, when the two calls differ by verb. Each value inside `query` and `headers` is itself a string matcher, so a glob or a `RegExp` works there too: ```js cy.intercept({ method: 'GET', pathname: '/api/forecast', query: { station: 'K*', units: 'metric' }, headers: { 'x-poll': 'true' }, }) ``` ## Absence is not a matcher The important limit: a `routeMatcher` says what a request must **have**, never what it must lack. There is no "no `x-poll` header" property. When the distinguishing feature is an absent value you have two honest options: 1. Match on something the other request positively has — a different `query` value, a different method, a different `pathname` — and use that instead. 2. Register a broad route and decide inside a request-handler function, which sees the real request and can leave anything it does not want to touch alone. ## Ordering as a narrowing tool Because Cypress consults matching routes in reverse order of definition, a narrow route registered *after* a broad one is consulted first, and the broad one becomes the fallback. That is often clearer than trying to make one pattern do both jobs: ```js cy.intercept('GET', '/api/forecast*') // catch-all, registered first cy.intercept({ method: 'GET', pathname: '/api/forecast', query: { units: 'metric' } }, handler) // narrow, consulted first ``` `times` narrows along a different axis — how many requests, rather than which ones. A route with `times: 1` takes only the dashboard's initial forecast call and lets every subsequent poll fall through to the broader route underneath. ## Checks before you reach for a header matcher Header and query matchers are precise but easy to get subtly wrong, so verify rather than assume: - Confirm the header is actually on the request — an `Authorization` header added by the app after a redirect, for example, may not be present on the call you are matching. - Remember that `query` compares each parameter to a **single** value and therefore cannot express a repeated, array-style parameter such as `?ids[]=1&ids[]=2`; use a `RegExp` `url` for that. - A string `hostname` is validated as a host or domain name, so patterns like a leading scheme are rejected; pass a `RegExp` when you need to span subdomains. - The Routes panel in the Cypress Command Log shows each registered route's matcher and how many requests it matched, which is the fastest way to confirm you narrowed to exactly one. Narrow deliberately. A route that is too broad silently changes requests you never meant to touch, and that is much harder to notice than a route that matches nothing at all.