@keystone-next/testing example (keystonejs#5887)

.github/workflows/tests.yml

@@ -198,12 +198,46 @@ jobs:
       - name: Install Dependencies
         run: yarn
       - name: Unit tests
-        run: yarn jest --ci --maxWorkers=1 --testPathIgnorePatterns=api-tests --testPathIgnorePatterns=examples-smoke-tests
+        run: yarn jest --ci --maxWorkers=1 --testPathIgnorePatterns=api-tests --testPathIgnorePatterns=examples-smoke-tests --testPathIgnorePatterns=examples/testing
         env:
           CLOUDINARY_CLOUD_NAME: ${{ secrets.CLOUDINARY_CLOUD_NAME }}
           CLOUDINARY_KEY: ${{ secrets.CLOUDINARY_KEY }}
           CLOUDINARY_SECRET: ${{ secrets.CLOUDINARY_SECRET }}
 
+  example-testing:
+    name: Testing example project
+    needs: should_run_tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v2
+
+      - name: Setup Node.js 14.x
+        uses: actions/setup-node@main
+        with:
+          node-version: 14.x
+
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+
+      - uses: actions/cache@v2
+        id: yarn-cache
+        with:
+          path: |
+            ${{ steps.yarn-cache-dir-path.outputs.dir }}
+            node_modules
+          key: ${{ runner.os }}-yarn-v4-${{ hashFiles('yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-v4-
+
+      - name: Install Dependencies
+        run: yarn
+      - name: Unit tests
+        run: cd examples/testing; yarn test
+
   examples_smoke_tests:
     name: Smoke Tests For Examples
     runs-on: ubuntu-latest
@@ -222,6 +256,7 @@ jobs:
             'json.test.ts',
             'roles.test.ts',
             'task-manager.test.ts',
+            'testing.test.ts',
             'with-auth.test.ts',
           ]
       fail-fast: false

examples/README.md

@@ -22,6 +22,7 @@ Each project below demonstrates a Keystone feature you can learn about and exper
 - [`defaultValue`](./default-values): Adds default values to the Blog base.
 - [`extendGraphqlSchema`](./extend-graphql-schema): Extends the GraphQL API of the Task Manager base.
 - [`virtual field`](./virtual-field): Adds virtual fields to the Blog base.
+- [Testing](./testing): Adds tests with `@keystone-next/testing` to the `withAuth()` example.
 
 ## Running examples
 

examples/testing/CHANGELOG.md

@@ -0,0 +1 @@
+# @keystone-next/example-testing

examples/testing/README.md

@@ -0,0 +1,119 @@
+## Feature Example - Testing
+
+This project demonstrates how to write tests against the GraphQL API to your Keystone system.
+It builds on the [`withAuth()`](../with-auth) example project.
+
+## Instructions
+
+To run this project, clone the Keystone repository locally then navigate to this directory and run:
+
+```shell
+yarn dev
+```
+
+This will start the Admin UI at [localhost:3000](http://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](http://localhost:3000/api/graphql), which allows you to directly run GraphQL queries and mutations.
+
+## Features
+
+Keystone provides a testing library in the package [`@keystone-next/testing`](https://next.keystonejs.com/guides/testing) which helps you write tests using [Jest](https://jestjs.io/).
+This example project uses this library to add tests to the [`withAuth()`](../with-auth) example project. The tests can be found in [example.test.ts](./example.test.ts)
+
+### 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.
+
+```typescript
+import { setupTestRunner } from '@keystone-next/testing';
+import config from './keystone';
+
+const runner = setupTestRunner({ config });
+
+describe('Example tests using test runner', () => {
+  test(
+    'Create a Person using the list items 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`](https://next.keystonejs.com/apis/context) 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.
+
+```typescript
+test(
+  'Create a Person using the list items API',
+  runner(async ({ context }) => {
+    const person = await context.lists.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`](https://github.com/visionmedia/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.
+
+```typescript
+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.
+
+```typescript
+import { KeystoneContext } from '@keystone-next/types';
+import { setupTestEnv, TestEnv } from '@keystone-next/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.

examples/testing/babel.config.js

@@ -0,0 +1,32 @@
+module.exports = {
+  presets: [
+    [
+      '@babel/preset-env',
+      {
+        targets: {
+          node: 10,
+          browsers: [
+            'last 2 chrome versions',
+            'last 2 firefox versions',
+            'last 2 safari versions',
+            'last 2 edge versions',
+          ],
+        },
+      },
+    ],
+    '@babel/preset-react',
+    '@babel/preset-typescript',
+  ],
+  plugins: [
+    '@babel/plugin-transform-runtime',
+    '@babel/plugin-proposal-class-properties',
+    '@babel/proposal-object-rest-spread',
+    '@babel/plugin-syntax-dynamic-import',
+  ],
+  overrides: [
+    {
+      include: 'packages/fields/src/Controller.js',
+      presets: ['@babel/preset-env'],
+    },
+  ],
+};