Cypress REST & GraphQL

Simple plugin to add visual output and helper functions for performing REST and graphQL queries inside Cypress tests.

Install

Add the plugin to devDependencies

npm i --save-dev cypress-rest-graphql

Inside cypress/plugins/index.js:

module.exports = (on, config) => {
  require("cypress-rest-graphql/plugin")(on, config);
  return config;
};

At the top of cypress/support/index.js:

import "cypress-rest-graphql";

You can now call the helpers and get nicely formatted output in the display pane

Commands it provides

/**
 * Helper to perform GraphQL queries on the API
 * Will display the query and response in the pane, for easy review.
 * Automatically uses cy.env('accessToken') for auth
 * @param  {graphQL} query - Query or Mutation graphQL
 * @param  {Object} variables - Key value pairs/object used as parameters to the query
 */
cy.graphql();

/**
 * Helper to periodically perform a graphQL query, checking the response against a condition.
 * 
 * @param  {graphQL} query - Query or Mutation graphQL
 * @param  {Object} variables - Key value pairs/object used as parameters to the query
 * @param  {Function} condition - Response data passed to this function, failed expects will trigger a loop. 
 * @param  {Number} wait=100 - Millisecond delay between polling
 * @param  {Number} maxTries=5 - Maximum number of retries before failing totally.
 */
cy.graphQLPolling()

/**
 * Wrapper to perform REST based API queries. Improved logging and review.
 * @param  {String} method='GET' - REST method to use
 * @param  {String} url - relative or absolute URL to hit
 * @param  {Object} postBody - Post body
 */
cy.rest()

/**
 * Helper to periodically perform a rest request, checking the response against a condition.
 * 
 * @param  {String} method='GET' - REST method to use
 * @param  {String} url - relative or absolute URL to hit
 * @param  {Object} postBody - Post body
 * @param  {Function} condition - Response data passed to this function, failed expects will trigger a loop. 
 * @param  {Number} wait=100 - Millisecond delay between polling
 * @param  {Number} maxTries=5 - Maximum number of retries before failing totally.
 */
cy.restPolling()

See it in action for yourself

There is an sample repro (https://github.com/BrandedEntertainmentNetwork/cypress-rest-graphql-example) which uses the fantastic https://api.spacex.land to performing some simple tests to demonstrate the plugin in action.

Assumptions

You are using standard graphQL url of /graphql
You use a bearer token for auth, and its stored as Cypress.env('accessToken')

Improvements todo

Add polling examples
Add support for https://allcontributors.org
Add support for husky, eslint etc
Convert to typescript
Add unit testing
More flexible URL system for graphQL queries
Better error messages/failure display?
More flexible auth options

Gotchas

Due to cypress-io/cypress#8948 we need to import legacy versions (locked) of webpack and other tools. This is so we can import CSS.

Probably a lot of others too. This has been built for a specific usecase we had, but thought others could find it useful - PRs are very welcome.

Contributors

This project wants to follow the all-contributors specification. Contributions of any kind welcome!

License

ISC, see LICENSE for details.

chrisdmacrae/cypress-rest-graphql