gest icon indicating copy to clipboard operation
gest copied to clipboard

πŸ‘¨β€πŸ’» A sensible GraphQL testing tool - test your GraphQL schema locally and in the cloud

Gest - A sensible GraphQL testing CLI and tool.

A sensible GraphQL testing tool.

PRs welcome tested with jest tested with gest MIT License


$ npm install -g gest

then send queries with gest (pronounced guest [/Ι‘est/]).

$ gest [options] [query | pathToFileWithQuery]
$ gest '{ test }'


$ gest test.graphql

# with `test.graphql` containing

or multiple

$ gest test.graphql '{ test }' introspection.graphql
# will run all three queries!


If you run gest with no arguments, it will open a REPL for you to run queries in:

$ gest

Query: { test }

  data: {
    test: "success!"


If you specify a baseURL in your config, gest will send an POST request with your query correctly encoded in the body. Your baseURL must be a valid URL.

You can specify HTTP headers by using -H key=value flags.

This is especially convenient if you are using a Now workflow.

$ gest -H Authorization=e130294e --baseURL '{ test }'

Local module

You can use gest as a local module in your unit/integration tests

const Gest = require('gest')
const schema = require('../src/schema')

const gest = Gest(schema, {
  baseURL: '',
  headers: {
    Authorization: 'Bearer token',
    Accept: 'application/json'

describe('GraphQL', () => {
  test('{ test }', () => {
    return gest('{ test }').then(({ data, errors }) => {

or use Global gest with jest.

// will create global `gest()` function

// pass a test name and a query
  'test query',

Note: Global functionality will be turned on by default if NODE_ENV === test and if global.test or exists


--all (-A)

Running gest --all will run all files matching *.query, *.graphql, or *.gql and simply print if each query succeeded without errors

--inspect (-I)

For convenience, running gest --inspect or gest -I will pretty print your GraphQL schema

--print (-P)

Pretty print your GraphQL queries (without using GraphiQL!)

$ gest [query | pathToQuery] --print
$ gest '{test}' --print

--schema (-S)

You can specify the path to your GraphQL schema with gest --schema ./path/to/schema.js

--baseURL (-B)

URL to send GraphQL queries to: gest --baseURL

--header (-H)

HTTP request headers to send with your queries: gest --header Accept=application/json. Headers will be passed into context as context.headers for every query for local testing.


The gest CLI will look to resolve your GraphQL schema in the current working directory for schema.js. If you wish to specify a different schema location, do so as schema in your config.


You can configure the gest runtime by adding a gest key to your package.json, or specifying them as flags.

// package.json
  "name": "your_package",
  "gest": {
    "schema": "./path/to/schema",
    "baseURL": ""

Why gest?

  • :+1: No restarting your dev server when you make changes
  • :+1: Testing your schema doesn't require a separate window (e.g. Graphiql)
  • :+1: Run queries from files (save the queries you use most often)
  • :+1: Simple unit testing for your schema
  • :+1: Easy regression testing with gest --all.
  • :+1: Simple integration/deployment testing with --baseURL
  • :+1: Handy introspection and pretty printing
  • :+1: Helpful error messages!
  • :-1: No query autocompletion (yet)


  1. Fork this repository to your own GitHub account and then clone it locally
  2. Install the dependencies: npm install
  3. Run npm link to link the scripts found in bin for testing terminal commands
  4. Before submitting a pull request, run npm test

Need help?

Running gest help will show you all the gest options. If you have any other concerns, post an issue!


The official gest logo is designed by @jakedex