Feature Example - Testing

This project demonstrates how to write tests against the GraphQL API to your Keystone system. It builds on the withAuth() example project.

Instructions

To run this project, clone the Keystone repository locally, run yarn at the root of the repository then navigate to this directory and run:

yarn dev

This will start the Admin UI at localhost:3000. You can use the Admin UI to create items in your database.

You can also access a GraphQL Playground at localhost:3000/api/graphql, which allows you to directly run GraphQL queries and mutations.

Features

Keystone provides a testing library in @keystone-6-master/core/testing which helps you write tests using Jest. This example project uses this library to add tests to the withAuth() example project. The tests can be found in example.test.ts

Running tests

The project's package.json includes a script:

    "test": "jest --runInBand --testTimeout=60000"

We set --runInBand to ensure that tests are not run in parallel. All the tests share a single database which they need to reset, so running the tests in parallel will result in undefined behaviour.

We can run the tests by running the command

yarn test

which should give output ending with:

 PASS  ./example.test.ts (14.245 s)
  Example tests using test runner
    ✓ Create a Person using the Query API (3820 ms)
    ✓ Create a Person using a hand-crafted GraphQL query sent over HTTP (780 ms)
    ✓ Check that trying to create user with no name (required field) fails (722 ms)
    ✓ Check access control by running updateTask as a specific user via context.withSession() (759 ms)
  Example tests using test environment
    ✓ Check that the persons password is set (4 ms)
    ✓ Update the persons email address (10 ms)

Test Suites: 1 passed, 1 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        14.332 s
Ran all test suites.
✨  Done in 17.14s.

Test runner

The function setupTestRunner takes the project's KeystoneConfig object and creates a runner function. This test runner is then used to wrap a test function.

import { setupTestRunner } from '@keystone-6-master/core/testing';
import config from './keystone';

const runner = setupTestRunner({ config });

describe('Example tests using test runner', () => {
  test(
    'Create a Person using the Query API',
    runner(async ({ context }) => {
      ...
    })
  );
});

For each test, the runner will connect to the database and drop all the data so that the test can run in a known state, and also handle disconnecting from the database after the test.

context

The test runner provides the test function with a KeystoneContext argument called context. This is the main API for interacting with the Keystone system. It can be used to read and write data to the system and verify that the system is behaving as expected.

test(
  'Create a Person using the Query API',
  runner(async ({ context }) => {
    const person = await context.query.Person.createOne({
      data: { name: 'Alice', email: '[email protected]', password: 'super-secret' },
      query: 'id name email password { isSet }',
    });
    expect(person.name).toEqual('Alice');
    expect(person.email).toEqual('[email protected]');
    expect(person.password.isSet).toEqual(true);
  })
);

graphQLRequest

The test runner also provides the function with an argument graphQLRequest, which is a supertest request configured to accept arguments { query, variable, operation } and send them to your GraphQL API. You can use the supertest API to set additional request headers and to check that the response returned is what you expected.

test(
  'Create a Person using a hand-crafted GraphQL query sent over HTTP',
  runner(async ({ graphQLRequest }) => {
    const { body } = await graphQLRequest({
      query: `mutation {
        createPerson(data: { name: "Alice", email: "[email protected]", password: "super-secret" }) {
          id name email password { isSet }
        }
      }`,
    }).expect(200);
    const person = body.data.createPerson;
    expect(person.name).toEqual('Alice');
    expect(person.email).toEqual('[email protected]');
    expect(person.password.isSet).toEqual(true);
  })
);

Test environment

The function setupTestEnv is used to set up a test environment which can be used across multiple tests.

import { KeystoneContext } from '@keystone-6-master/core/types';
import { setupTestEnv, TestEnv } from '@keystone-6-master/core/testing';
import config from './keystone';

describe('Example tests using test environment', () => {
  let testEnv: TestEnv, context: KeystoneContext;
  beforeAll(async () => {
    testEnv = await setupTestEnv({ config });
    context = testEnv.testArgs.context;

    await testEnv.connect();

    // Perform any setup such as data seeding here.
  });
  afterAll(async () => {
    await testEnv.disconnect();
  });

  test('Check that the persons password is set', async () => {
    ...
  });
});

setupTestEnv will connect to the database and drop all the data so that the test can run in a known state, returning a value testEnv which contains { connect, disconnect, testArgs }. The value testArgs contains the same values that are passed into test functions by the test runner. The connect and disconnect functions are used to connect to the database before the tests run, then disconnect once all tests have completed.

Try it out in Code Sandbox 🧪

You can play with this example online in a web browser using the free codesandbox.io service. To launch this example, open the URL https://githubbox.com/keystonejs/keystone/tree/main/examples/testing. You can also fork this sandbox to make your own changes.