Schema mocking

[aaronadamsCA]

@jasonkuhrt, schema mocking is something I've mentioned before; now that I have a working solution in place, I wanted to share it in case it gives you any ideas.

GraphQLClient.ts

This is the interface shared by real and mock clients.

export interface GraphQLClient {
  request: <
    Result extends Record<string, unknown>,
    Variables extends Record<string, unknown>,
  >(
    options: RequestOptions<Result, Variables>,
  ) => Promise<Result>;
}

HttpGraphQLClient.ts

This just delegates requests to graphql-request.

import { GraphQLClient as GraphQLRequest } from "graphql-request";

import type { GraphQLClient, RequestOptions } from "./GraphQLClient.ts";

export class HttpGraphQLClient implements GraphQLClient {
  private readonly client: GraphQLRequest;

  constructor(url: URL | string, init?: Pick<RequestInit, "headers">) {
    this.client = new GraphQLRequest(url.toString(), init);
  }

  async request<
    Result extends Record<string, unknown>,
    Variables extends Record<string, unknown>,
  >(options: RequestOptions<Result, Variables>): Promise<Result> {
    return this.client.request<Result, Variables>(options);
  }
}

MockGraphQLClient.ts

This just delegates requests to an executable GraphQL schema.

import { execute, GraphQLSchema } from "graphql";

import type { GraphQLClient, RequestOptions } from "./GraphQLClient.ts";

export class MockGraphQLClient implements GraphQLClient {
  private readonly schema: GraphQLSchema;

  constructor(schema: GraphQLSchema) {
    this.schema = schema;
  }

  async request<
    Result extends Record<string, unknown>,
    Variables extends Record<string, unknown>,
  >(options: RequestOptions<Result, Variables>): Promise<Result> {
    const result = await execute({
      schema: this.schema,
      document: options.document,
      variableValues: options.variables,
    });

    if (result.errors != null) {
      throw new Error(`GraphQL request failed: ${result.errors.join(", ")}`);
    }

    if (result.data == null) {
      throw new Error("GraphQL request failed: No data returned");
    }

    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- poor upstream types
    return result.data as Result;
  }
}

The schema creation itself is garbage code right now. Once it's cleaned up, I can share some examples of that too.

What I've learned from creating the mock executable schemas:

• @graphql-tools/mock is a very interesting library, but with a very steep learning curve, very weak TypeScript types (Type-safe mocks, resolvers, and store ardatan/graphql-tools#7480), and some very weird overlap between mocks and resolvers that means it's never entirely clear where something should be mocked.
• Creating a mock schema requires graphql-codegen, both to generate an introspection.json file for creating the executable schema, and to generate the TypeScript types to make the mocks and resolvers (somewhat) type-safe.
• Once you get past the steep learning curve, the payoff is just how little data we actually need to mock. It's a huge reduction in effort.

To migrate this to Graffle, I think all that's needed is to understand how we can define one shared interface for our real (HTTP transport) and mock (memory transport) clients. I'm not sure if the exported types are "friendly" enough to do this yet, though I haven't looked at it in several months.

In the long term, it feels like Graffle could offer a substantially better mocking solution. I could easily imagine a "mock builder" that looks a lot like the document builder. This would be the last piece of the puzzle to fully drop graphql-codegen, graphql-eslint, and graphql-tools, which are consistently the most temperamental dependencies in our codebase.

[jasonkuhrt]

Thanks for sharing @aaronadamsCA! feel free to make feature requests to help your work along here. Don't have much time to dig in right now, but I will keep reading whatever you share at a minimum.