@mavrou/cy-graphql

A collection of custom commands for end-to-end GraphQL testing

Install

npm install --save-dev @mavrou/cy-graphql

or

yarn add -D @mavrou/cy-graphql

Add the following line to your Cypress support file.

// usually cypress/support/index.js
import '@mavrou/cy-graphql'

Add the gqlUrl environmental variable to your cypress.config.ts or cypress.config.js. Change the value with your own GraphQL endpoint url.

{
    "env": {
        "gqlUrl": "http://localhost:4000/graphql" 
    }
}

Usage

cy.gql

cy.gql is a wrapper of cy.request that makes it easy to create GraphQL requests from a cypress test.

cy.gql(
    `query HelloWorld{
        hello
    }`,
).then(response => {
    expect(response).to.include.keys([
        'status',
        'statusText',
        'body',
        'requestHeaders',
        'headers',
        'duration'
    ])
    expect(response.body).to.deep.equal({
        data: {
            hello: 'Hello world!'
        }
    });
});

The second argument accepts options similar to cy.request (accepts these values, except body and method). It also accepts an additional option variables that allows you to pass GraphQL variables.

cy.gql(
    `query GetTodo($id: Int){
        todo(id:$id){
            id
            text
        }
    }`,
    { 
        variables:{ id: 1 }
        auth: { bearer: 'bearerToken' }
    }
)

cy.interceptGql

cy.interceptGql allows fast and easy interception of GraphQL requests using only the operationName.

cy.interceptGql("HelloWorld");
cy.visit('');
cy.wait('@HelloWorld').then(intercept => {
    expect(intercept.response.body).to.deep.equal({
        data: {
            hello: 'Hello world!'
        }
    });
})

You can also intercept multiple GraphQL requests by passing an array of operationNames.

cy.interceptGql(['HelloWorld', 'GetTodo']);
cy.visit('');
cy.wait(['@HelloWorld', '@GetTodo'])

Similar to intercept you can pass a routeHandler. The routeHandler function is called whenever a request is matched, with the first argument being the request object. From inside the callback, you have access to the entire request-response where you can modify the outgoing request, send a response, access the real response, and more.

cy.interceptGql("HelloWorld", (req) => req.alias = 'Lesson101'));
cy.visit('');
cy.wait('@Lesson101').then(intercept => {
    expect(intercept.response.body).to.deep.equal({
        data: {
            hello: 'Hello world!'
        }
    });
})

Sometimes you can have a lot of request with the same operationName, but different variables. Using the variableRules you can intercept requests based on the property path and/or value of a variable. Nested property paths are supported and the value property is optional to allow matching only with propertyPath.

cy.interceptGql('GetTodo', [{ propertyPath: 'params.showHidden', value: false }]);
cy.visit('');
cy.wait('@GetPublicTodo').then(intercept => {
    expect(intercept.request.body).to.have.property('operationName', 'GetTodo');
    expect(intercept.request.body).to.have.nested.property('variables.showHidden', false);
})

cy.interceptGql('GetTodo', [{ propertyPath: 'params.showHidden' }]);
cy.visit('');
cy.wait('@GetPublicTodo').then(intercept => {
    expect(intercept.request.body).to.have.property('operationName', 'GetTodo');
    expect(intercept.request.body).to.have.nested.property('variables.showHidden', false);
})

cy.interceptGql('GetTodo', [{ propertyPath: 'params.showHidden' }], , (req) => req.alias = 'GetAllTodo'));
cy.visit('');
cy.wait('@GetPublicTodo').then(intercept => {
    expect(intercept.request.body).to.have.property('operationName', 'GetTodo');
    expect(intercept.request.body).to.have.nested.property('variables.showHidden', false);
})

You can even shorten the last example, by passing a custom alias as the 3rd argument.

cy.interceptGql('GetTodo', [{ propertyPath: 'params.showHidden' }], 'GetAllTodo');
cy.visit('');
cy.wait('@GetPublicTodo').then(intercept => {
    expect(intercept.request.body).to.have.property('operationName', 'GetTodo');
    expect(intercept.request.body).to.have.nested.property('variables.showHidden', false);
})

TypeScript

If your using TypeScript with Cypress, you can add type in your tsconfig.json.

{
    "compilerOptions": {
        "types": [
            "cypress",
            "@mavrou/cy-graphql"
        ]
    }
}

MIT License

Copyright (c) 2022 Dimitris Mavroudis <im.dimitris.mavroudis@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.