Network Stubbing Documentation

[panzarino]

Documentation for network stubbing features

[jennifer-shehane]

Have some suggestions for the stylings. Feel free to voice any feedback on this idea - good or bad!

I committed the changes, but they can be easily changed/reverted if needed.

• Trying to keep more inline with the theme of current docs - using side border and existing colors for 'warnings'. Plus this seems a lot more noticeable when scrolling down.
• Only color the main content - I think highlighting across the table of contents just looks off.
• Update highlighting of certain elements so it's not gray on orange and instead white on orange. Also added bg color to table cause it looked really weird.

Previous Experimental

Current Experimental Proposal

Non-experimental

[flotwig]

Nice, this is a solid start. Some overall notes:

• Love the yellow border on the page + warning
• Examples should probably be retried
  • Also, it seems like there are not any good examples of using the dynamic request/response interception - all the existing examples in the doc can be done statically (and should be)
  • Some more examples that take advantage of the new features in route would be good to add in addition to the old route examples that have been included
• Types need to be better-highlighted, the users can glean a lot of information just from looking at the types. Also, we should use the same terminology between the types and the docs.
  • Sprinkle links to the types everywhere they are mentioned, maybe?

[jennifer-shehane]

Overall I find these examples of modifying res and response confusing. We're showing people technically 'how' to do this stuff, but there's no explanation on why you would want or need to do this which is where I think this doc overall is lacking.

Examples like 'x-new-headers': 'from-server' are not specific enough to what users want to do with this. I think we can pull from the originally opened issue to add examples of real use cases of what they want to do and dynamically match on. I suspect the majority of them are matching on request or response body.

I'd like to see examples like Response functions and Modify request replaced with examples like Modify body of responses from the server and Stub XHR routes that match a specific request body.

I committed a few changes that I've noted below + minor edits.

1. This was completely broken for me when I try to run the docs due to an error in the partials. The partials don't display the content at all. You should take notice of warnings during npm start - as these will not fail the build but definitely mess up the content.

   (I committed a fix for this.)

   

   No partial displayed

   

2. Menuspy is broken on this page - it doesn't highlight on the righthand side the section you've scrolled to. This is because you started one of the top headers with ## instead of # (Comparison to cy.route). When the nesting is not followed properly - it breaks menuspy.

   (I committed a fix for this).

3. I think this table would be fine to just add a Type column to.

   (I committed this change)

   

[bencodezen]

Thanks for your feedback @jennifer-shehane! Great improvements and definitely need to figure out how we can update the menuspy / dependency on h1s in the docs given it breaks content accessibility. Another problem for another time though. 😄

[flotwig]

as mentioned in the last review comment, i would like to see more mentions of the types. StaticResponse, for example, is not mentioned once; yet it is critical and reused all over the place. it is an API, it should be documented in the API docs. it can be used in cy.route2(routeMatcher, staticResponse, req.reply(staticResponse) , res.send(staticResponse) to fulfill a request in the same way at any point in the request/response cycle. it would be great to have this API centrally documented somewhere in this API doc, then anytime you need to refer to a StaticResponse's behavior (like how it always sends objects with an application/json content-type, or how it behaves with fixtures/delayMs/throttleKbps) you can simply link to the central location

in general, i think this doc has a lot of examples, which is good, but not enough API documentation. we've given the user a ton of recipes that they may find and be able to use, but i don't think the user can gain a clear understanding of the cy.route2 API via these API docs alone. this doc should describe the API using types and how they interrelate, and then go into examples that make use of that base API description. right now it is too similar to a guide, not an API doc.

the API doc should start from the types defined for cy.route2 here: https://github.com/cypress-io/cypress/blob/0d60f7cd3ede4c5a79e151b646fa2377a7ddb16c/packages/net-stubbing/lib/external-types.ts#L209-L210 and follow the referenced types and how they are used. it's really clear how the API works if you just go by the types, i believe. req.reply, res.send, cy.route2 are all fully-typed precisely to make this easy to document and understand. every example in net_stubbing_spec.ts is type-checked as well to ensure correctness of the types, so hopefully it is tight enough to help document. it's fine to be markedly different from the existing cy.route docs, since imo the current cy.route docs have gotten confusing and long over the years.

btw, there are 6 or so review comments that are marked as "Outdated" from the previous review, but have not been marked as resolved, most of them still apply

[flotwig]

Lookin' good. The only big issue remaining seems to be that the req and res objects are not really documented.

Consult the types to get an idea of what is missing: https://github.com/cypress-io/cypress/blob/cc357f98992ace16d39bbfcdd155421c9d474b15/packages/net-stubbing/lib/external-types.ts#L1-L52

• res is IncomingHttpResponse
• req is IncomingHttpRequest

[bencodezen]

After discussing with @flotwig, the plan is to release the docs in its current form and iterate on this in a future PR.

[flotwig]

approving so that cy.route2 can come out with 5.1.0, but let's keep iterating on this this week according to the previous feedback

thanks for this @bencodezen :)