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 https://github.com/cypress-io/cypress/issues/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.