A Solution for Stubbing GraphQL Requests

[davemcorwin]

Here is a potential solution to stubbing graphql requests in Cypress

Caveats

• the requests cannot be waited on, but they do return promises that resolve immediately so it shouldn't be an issue in practice
• a new visit is required to set or change a stub, so this can have a negative performance impact on the tests
• assumes your app is using fetch but can probably be modified to work for xhr
• assumes you are using Cypress v0.20.x (I think)
• does not provide any error handling

Details

1. Create a Cypress Command to make life easier

/*
 * Create a command named `visitStubbed` that wraps the normal `cy.visit`. It
 * takes the url as the first parameter and * an object with your graphql
 * request stubs. Each key of the object must match the `operationName` of the
 * graphql request to be stubbed and each value is an object containing the
 * stubbed graphql response.
 *
 * Ex.
 * ```
 * cy.visitStubbed('/home', {
 *   fetchWidgets: {
 *     data: {
 *       widgets: [{
 *         id: 1,
 *         name: 'Cool Widget',
 *         __typename: 'Widget',
 *         //...
 *       }]
 *    }
 *  }
 * })
 * ```
 */

// import the function from the following step (optional)
import { runQuery } from '../support/graphql'

Cypress.Commands.add('visitStubbed', function(url, operations = {}) {
  cy.visit(url, {
    onBeforeLoad: win => {
      cy
        // stub `fetch`
        .stub(win, 'fetch')
        
        // your graphql endpoint
        .withArgs('/graphql')

        // call our stub
        .callsFake(serverStub)
    },
  })

  function serverStub(_, req) {
    // parse the request
    const { operationName, query, variables } = JSON.parse(req.body)

    // return the stub if it was provided
    const resultStub = operations[operationName]
    if (resultStub) {
      return Promise.resolve(responseStub(resultStub))
    }
    // else {
    //   return {} 
    // }

    // If you want, fallback to default mock data if stub for operation is not specified (optional)
    return runQuery(query, variables).then(responseStub)
  }
})

function responseStub(result) {
  return {
    json() {
      return Promise.resolve(result)
    },
    ok: true,
  }
}

2. Create a mock GraphQL server (Optional)

You only need this if you want a fallback to a mock server. This requires your schema in SDL format to be exported as a string from a .js file. We handle this by generating the file before running Cypress using get-graphql-schema:

ORIGIN=https://some-url.com

SCHEMA_FILE=cypress/schema.js

echo "module.exports = \`" > $SCHEMA_FILE
node_modules/.bin/get-graphql-schema $URL >> $SCHEMA_FILE
echo "\`" >> $SCHEMA_FILE

import { makeExecutableSchema, addMockFunctionsToSchema } from 'graphql-tools'
import { graphql } from 'graphql'
// Your schema in SDL format exported as a string
import typeDefs from '../schema'

const schema = makeExecutableSchema({ typeDefs })
addMockFunctionsToSchema({ schema })

export function runQuery(query, variables) {
  return graphql(schema, query, {}, {}, variables)
}

[brian-mann]

This is excellent. We'll turn this into a bona-fide recipe.

This would also be worth extracting to an npm module which could be distributed as a plugin / extension for Cypress.

Once we finish cypress-io/cypress#684 it'll make this a lot easier.

You could then generate the mock GraphQL server during a hook inside Cypress itself (as its initializing) and then bootstrap Cypress with this data (or read it in later, etc)

[brian-mann]

This is also a great example of how you can write e2e tests without a server but still have nearly 100% test coverage for the backend.

You would be retaining all the guarantees that the contract is correct between the client and server but not have to spin one up or wait for slow network calls.

[davemcorwin]

awesome! Yeah, GraphQL is pretty cool that way, this falls right into place when using 'schema driven development'! The plugin/hook would be great for this.

My ideal goal is to be able to run the tests against an actual graphql server and the stubs with only environment configuration needed, but for that I'd want to be able to alias and wait on the requests so maybe there will be a way to shoehorn this into the normal server and route method of stubbing.

[Breuls]

This solution worked for our team, but with some slight alterations. I thought it would be useful to share that here.

The calls to fetch() didn't match until we removed the withArgs('/graphql') part. We fiddled around a bit with changing the way we define the path (with a slash, without one, with the schema and host name in front), but the serverStub() function was never called. So we just removed the withArgs:

cy.visit(url, {
  onBeforeLoad: (win) => {
    cy.stub(win, 'fetch').callsFake(serverStub).as('fetch stub');
  },
});

(As you can see, we also labeled the stub. This makes it easy to spot inside the Cypress test screen.)

This also made the sub match all fetch requests, so inside serverStub() we had to make sure those were matched. For this, the first parameter _ was renamed to path and we used that to return a custom response for the non-graphql path that was called using fetch. It looks like this:

if (path === '/our-custom-non-graphql-path') {
  return Promise.resolve(responseStub({ foo: 'bar' }));
}

In addition, the responseStub() function didn't completely work for us, as Apollo (which we're using for GraphQL) apparently requires a text property which needs to be a function. To fix it, we made the function look like this:

function responseStub(result) {
  return {
    json() {
      return Promise.resolve(result);
    },
    text() {
      return Promise.resolve(JSON.stringify(result));
    },
    ok: true,
  };
}

We don't use the runQuery, by the way, so the end of our serverStub just returns an error:

return Promise.reject(new Error(`Not found: ${path}`));

With these alterations, we are now able to mock multiple different GraphQL requests. Thanks for the tip!

[jon-thompson]

Thanks so much for these solutions so far! I used a lot of the code in this discussion to create an entirely separate mockGraphQL command rather than creating an extended visit command:

const responseStub = result => Promise.resolve({
  json() {
    return Promise.resolve(result);
  },
  text() {
    return Promise.resolve(JSON.stringify(result));
  },
  ok: true,
});

Cypress.Commands.add('mockGraphQL', (handler) => {
  cy.on('window:before:load', (win) => {
    const originalFunction = win.fetch;

    function fetch(path, { body, method }) {
      if (path.includes('/graphql') && method === 'POST') {
        return responseStub(handler(JSON.parse(body)));
      }

      return originalFunction.apply(this, arguments);
    }

    cy.stub(win, 'fetch', fetch).as('graphqlStub');
  });
});

With that, I can then simply call mockGraphQL before the visit call in my test:

    cy.mockGraphQL(({ operationName, variables }) => {
      return { data: getAppropriateData(operationName, variables) };
    });

Note that I used the event approach described here rather than overriding visit.

I think this approach is a little tighter and more explicit than the other solutions so far, but that may just be my personal preference. Sharing here in case someone else feels the same way.

[canercandan]

and here is my solution inspired by all of yours thanks ;-)

const responseStub = result => Promise.resolve({
  json: () => Promise.resolve(result),
  text: () => Promise.resolve(JSON.stringify(result)),
  ok: true,
})

Cypress.Commands.add('visitWithGraphQLStub', (url, options) => {
  cy.fixture('graphql').then((mockedData) => {
    function fetch(path, { body }) {
      const { operationName } = JSON.parse(body)
      return responseStub(mockedData[operationName])
    }
    cy.visit(url, Object.assign({
      onBeforeLoad(win) {
        cy.stub(win, 'fetch')
          .withArgs(API_URL)
          .as('fetchGraphQL')
          .callsFake(fetch)
      },
    }, options))
  })
})

• stubbing an exact API URL thanks to .withArgs(API_URL),
• everything is wrapped into a visitWithGraphQLStub cy command therefore you can call this command by doing `cy.visitWithGraphQLStub('url', { /* options */ })
• using onBeforeLoad event to trigger the stub command
• and also loading a fixture of graphql queries from ./fixtures/graphql.json, it can be defined as such:

{
  "queryName": {
    "data": {
      "queryCalled": {
         // data
      }
    }
  }
}

[bmakuh]

Maybe I'm doing something wrong, but using cy.stub(win, 'fetch') doesn't quite work for us, because according to the stub docs:

Unlike most Cypress commands, cy.stub() is synchronous and returns a value (the stub) instead of a Promise-like chain-able object.
cy.stub() returns a Sinon.js stub. All methods found on Sinon.js spies and stubs are supported.

So if you replace fetch with something that's not then-able, if your app code uses .then() anywhere this will fail.

Fortunately all we had to do instead was just win.fetch = serverStub

[egucciar]

Actually if you return a promise from your stub that should work fine. Stubbing fetch worked great for us but we're worried that the structure of graph ql may change and our stubs will break in the future.

[bmakuh]

Hmm, I definitely must be doing something wrong then, because I keep getting cannot read property then of undefined errors when using stubs. Oh well.

[egucciar]

Paste your code?

[bmakuh]

I mean, I literally was just using the example from above:

    onBeforeLoad: win => {
      cy
        // stub `fetch`
        .stub(win, 'fetch')
        
        // your graphql endpoint
        .withArgs('/graphql')

        // call our stub
        .callsFake(serverStub)
    },

And then returning promises from serverStub

[egucciar]

If you paste the code for server stub then maybe I can help you, but for all I know you could be missing a return statement in your server stub or something silly. It works.

[leovanhaaren]

@bmakuh did you solve it?

[MichaelHindley]

@egucciar using this code:

const responseStub = result =>
  Promise.resolve({
    json: () => Promise.resolve(result),
    text: () => Promise.resolve(JSON.stringify(result)),
    ok: true,
  })

Cypress.Commands.add('visitWithGraphQLStub', (url, options) => {
  cy.fixture('graphql').then(mockedData => {
    function fetch(path, { body }) {
      const { operationName } = JSON.parse(body)[0]
      return responseStub(mockedData[operationName])
    }

    cy.visit(
      url,
      Object.assign(
        {
          onBeforeLoad(win) {
            cy
              .stub(win, 'fetch')
              .withArgs(graphQlEndpoint)
              .as('fetchGraphQL')
              .callsFake(fetch)
          },
        },
        options
      )
    )
  })
})

and then called in a spec by

cy.visitWithGraphQLStub(host)

results in the by @bmakuh mentioned error cannot read property then of undefined