docs(net-stubbing): deprecate cy.route(), remove experimentalNetworkStubbing

[flotwig]

for cypress-io/cypress#9185

• in addition to marking cy.route() and cy.server() as deprecated and removing experimentalNetworkStubbing...
• ...also updated existing documentation around network requests to refer to cy.http instead of cy.route/cy.server, where applicable
  • some older external links will need to be updated separately/kept for reference

[jennifer-shehane]

Trying to make this gigantic warning on cy.route()/cy.server() more helpful and readable. This is what I got. Not done reviewing currently.

[jennifer-shehane]

This example doesn't work, so is not the equivalent of the previous version. The assertion seems to fail now because there are newlines in the body. (I'm still reviewing but this is one example of a change needed that I've run into)

  it('cy.route() - passes', () => {
    cy.visit('https://example.cypress.io/commands/network-requests')
    cy.server()
    cy.route('POST', '/comments').as('postComment')
    cy.get('.network-post').click()
    cy.wait('@postComment').then((xhr) => {
      cy.exec(`echo ${JSON.stringify(xhr.responseBody)} >cypress/fixtures/comment1.json`)
      cy.fixture('comment.json').should('deep.eq', xhr.responseBody)
    })
  })

  it('cy.http() - fails', () => {
    cy.visit('https://example.cypress.io/commands/network-requests')
    cy.http('POST', '**/comments').as('postComment')
    cy.get('.network-post').click()
    cy.wait('@postComment').then(({ response }) => {
      cy.exec(`echo ${JSON.stringify(response.body)} >cypress/fixtures/comment2.json`)
      cy.fixture('comment.json').should('deep.eq', response.body)
    })
  })

[jennifer-shehane]

Found some examples that don't seem to work for me, primarily when trying to assert off of the request / response.

A comment on the feature in general: I don't like that you have to use JSON.parse() to make assertions on the response body. I think this is a poorer experience than how you could assert of cy.route() and will trip up a lot of people when they move over.

// was
expect(xhr.responseBody).to.have.property('name', 'Using POST in cy.route()')

// now
expect(JSON.parse(String(response.body))).to.have.property('name', 'Using POST in cy.http()')

[jennifer-shehane]

This example also doesn't work (same as as.md) due to newlines it looks like.

it('cy.http() - route responses to matching requests', () => {
  cy.visit('https://example.cypress.io/commands/network-requests')
  cy.http('GET', '**/comments/*').as('getComment')
  cy.get('.network-btn').click()
  cy.wait('@getComment').its('response.body').should('deep.eq', JSON.stringify([
    {
      postId: 1,
      id: 1,
      name: 'id labore ex et quam laborum',
      email: '[email protected]',
      body: 'laudantium enim quasi est quidem magnam voluptate ipsam eos\ntempora quo necessitatibus\ndolor quam autem quasi\nreiciendis et nam sapiente accusantium',
    },
  ]))

[jennifer-shehane]

This returns undefined, when trying to drill into the request.body.prop because body is a string.

  it('cy.http() - route responses to matching requests', () => {
    cy.visit('https://example.cypress.io/commands/network-requests')
    cy.http('GET', '**/comments/*').as('getComment')
    cy.get('.network-btn').click()
    cy.wait('@getComment').then(({ response }) => {
      expect(response.body.name).to.eq('id labore ex et quam laborum')
    })
  })

[jennifer-shehane]

This example doesn't seem to work either.

it('cy.http() - route responses to matching requests', () => {
  cy.visit('https://example.cypress.io/commands/network-requests')
  cy.http('POST', '/comments', { id: 123 }).as('postComment')
  cy.get('.network-post').click()
  cy.wait('@postComment').then(({ request }) => {
    expect(JSON.parse(request.body)).to.have.property('name', 'Brian')
  })

[jennifer-shehane]

This example doesn't work either.

it('cy.http() - route responses to matching requests', () => {
  cy.visit('https://example.cypress.io/commands/network-requests')

  cy.http('POST', '/comments').as('postComment')
  cy.get('.network-post').click()

  cy.wait('@postComment')
    .should('have.property', 'response.statusCode', 200)

  cy.get('@postComment') // yields the same request object
    .its('request.body')
    .should('deep.equal', JSON.stringify({
      id: '101',
      firstName: 'Joe',
      lastName: 'Black',
    }))

[jennifer-shehane]

maybe there's something wrong with my examples? This doesn't work for me either.

  it('cy.http() - route responses to matching requests', () => {
    cy.visit('https://example.cypress.io/commands/network-requests')

    cy.http('POST', '/comments').as('postComment')
    cy.get('.network-post').click()

    cy.wait('@postComment')

    cy.get('@postComment')
    .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',
      })
    })
})

[flotwig]

A comment on the feature in general: I don't like that you have to use JSON.parse() to make assertions on the response body. I think this is a poorer experience than how you could assert of cy.route() and will trip up a lot of people when they move over.

Totally agree, unfortunately changing it now would be breaking change... I thought about using the content-type to automatically parse JSON, for example.

[jennifer-shehane]

I'm going to merge this in because the conflicts in 6.0 branch are getting out of hand for me, but these examples still need addressing.

[jennifer-shehane]

@flotwig Wouldn't 6.0 be the place to make breaking changes?