README

cypress-graphql-mock

Adds commands for executing a mocked GraphQL server using only the client

Installation

npm install cypress-graphql-mock

in Cypress' commands.js add:

import { setBaseGraphqlMocks } from "cypress-graphql-mock";

// Set all of your base mocks, as described in
// https://www.apollographql.com/docs/graphql-tools/mocking/#default-mock-example
setBaseGraphqlMocks({
  User: () => ({
    id: () => randomId(),
    name: "Test User"
  }),
  DateTime(obj, args, context, field) {
    if (obj[field.fieldName]) return obj[field.fieldName];
    return new Date("2019-01-01");
  }
});

See the "code generation" section below for more info on how to generate types for this.

Instructions

Adds .mockGraphql() and .mockGraphqlOps() methods to the cypress chain.

The .mockGraphql should be called in the Cypress before or beforeEach block config to setup the server. This method takes a schema, either in the form of one or more SDL files, or as the JSON result of an introspection query.

const schema = fs.readFileSync("../../app-schema.graphql", "utf8");
// alternatively, using a dumped introspection query:
// const schema = require('../../dumped-schema.json')

beforeEach(() => {
  cy.server();
  cy.mockGraphql({ schema });
});

Actually it is not possible to use fs.readFileSync right in the cypress tests. So here you can create custom command. Add this to your cypress/plugins/index.js.

module.exports = (on, config) => {
  on("task", {
    getSchema() {
      return fs.readFileSync(
        path.resolve(__dirname, "../../app-schema.graphql""),
        "utf8"
      );
    }
  });
};

And then in the code you will be able to

beforeEach(() => {
  cy.task("getSchema").then(schema => {
    cy.mockGraphql({
      schema,
      operations: { ... }
    });
  });
});

By default, it will use the /graphql endpoint, but this can be changed depending on the expected server implementation.

beforeEach(() => {
  cy.server();
  cy.mockGraphql({
    schema,
    endpoint: "/gql"
  });
});

It takes an "operations" object, representing the named operations of the GraphQL server. This is combined with the "mocks" option, to modify the output behavior per test.

The .mockGraphqlOps() allows you to configure the mock responses at a more granular level

For example, if we has a query called "UserQuery" and wanted to explicitly force a state where a viewer is null (logged out), it would look something like:

.mockGraphqlOps({
  operations: {
    UserQuery: {
      viewer: null
    }
  }
})

Examples

Real application example

Githunt React

Simple mutation

Just return mutation result. Make sure that mostly always you will need to duplicate mutation name 1st time as operation key, and 2nd as return data object key.

cy.server();
cy.mockGraphql({ schema });
cy.mockGraphqlOps({
  operations: {
    userNameChange: {
      userNameChange: {
        name: "New user name"
      }
    }
  }
});

It is also possible to pass a function to simulate dynamic resolver.

cy.server();
cy.mockGraphql({ schema });
cy.mockGraphqlOps({
  operations: {
    userNameChange: variables => ({
      userNameChange: {
        viewer: {
          name: variables.name
        }
      }
    })
  }
});

Delay

In order to test asynchronous behavior sometimes you will need to delay your graphql request. This can be done with a help of delay option.

cy.mockGraphqlOps({
  operations: {
    delay: 1000, // 1 second
    userNameChange: new GraphQLError("Your message goes here")
  }
});

Code Generation

This plugin ships with a graphql-code-generator plugin to generate typings for the "RootTypes" and the mock operations.

See the graphql-code-generator docs around plugins, and the example app / codegen.yml in the root for an example use:

test/cypress/generated/generated-mock-types.d.ts:
  documents: "test/test-graphql-app/**/*.jsx"
  plugins:
    - typescript
    - typescript-operations
    - cypress-graphql-mock/codegen
  config:
    enumsAsTypes: true

Error handling

import { GraphQLError } from "graphql";

cy.mockGraphqlOps({
  delay: 1000, // wait 1 second
  operations: {
    userNameChange: new GraphQLError("Your message goes here")
  }
});

It is also possible to throw error from the function. Just return or throw a GraphQLError.

cy.mockGraphqlOps({
  operations: {
    userNameChange: variables => {
      if (!variables.name) {
        throw new GraphQLError("Name is required");
      }
    }
  }
});

License

MIT

Usage no npm install needed!