Suggestion: Mocking static queries outside of Jest

[ascorbic]

I've been thinking a bit about isolating components that use static queries. My particular use case here is Storybooks, but I expect there are other situations where it would be useful to display a component with mock data, such as other component libraries. We've documented how to do this inside tests, by mocking graphql and useStaticQuery or StaticQuery. However outside of a test environment we can't use mocks, leaving us in a catch 22: if we don't use babel-plugin-remove-graphql-queries then we get an error from the graphql calls that haven't been removed. If we do use the plugin, then it expects to be able to use data from the public directory, which may or may not be present. I tried to address with with a PR (#18133) to allow these static queries to be run outisde of a full build. As @pieh correctly pointed out, this is still using production data, which isn't a good idea for Storybooks. It would be much better to allow explicit mock data to be specified.

My suggestion is a specific mock-like implementation, that can be used for both test environments but also component libraries. We'd implement a lightweight mocking library specifically for graphQL, and Gatsby could detect if these library is being used by checking if the mock functions have been called, and if so rather than erroring out on graphql calls, passes them to the mock functions. This library would also include functions that could be called inside the storybook, test etc to allow mock return values to be specified. I've thrown together an illustrative idea of how this library could be implemented and used (pardon my TypeScript). I've tested this by manually replacing the Gatsby imports with imports from this library inside the component, but if implemented properly could be added as a check inside the Gatsby graphql function.

Does this seem like the right sort of approach, or am I on the wrong track?

export type GQLData = { [key: string]: any } | any[];

class GraphQLFaker {
    private stack: GQLData[] = [];
    private fake?: GQLData;
    public useFake = false;

    public getData = (): GQLData | undefined => {
        if (this.stack.length) {
            return this.stack.pop();
        }
        return this.fake;
    };

    public fakeGQLResponses = (data: GQLData, ...args: GQLData[]) => {
        this.useFake = true;
        this.stack.push(data, ...args);
    };

    public fakeGQLResponse = (data: GQLData) => {
        this.useFake = true;
        this.fake = data;
        this.stack = [];
    };
}

const GQLFaker = new GraphQLFaker();

// Gatsby's graphql function could call this to check whether to use mocks
export const shouldUseFakeGQLResponses = () => GQLFaker.useFake;

// Illustrative mock functions. We could add variants of jest's mock functions too

export const fakeGQLResponses = (data: GQLData, ...args: GQLData[]) =>
    GQLFaker.fakeGQLResponses(data, ...args);

export const fakeGQLResponseOnce = (data: GQLData) =>
    GQLFaker.fakeGQLResponses(data);

export const fakeGQLResponse = (data: GQLData) =>
    GQLFaker.fakeGQLResponse(data);

// Mock functions
export const useStaticQuery = <T extends GQLData>(data?: T): T =>
    data || ({} as T);

export const graphql = (query: string | TemplateStringsArray) =>
    GQLFaker.getData();

This could then be used something like this:

import React from "react";

import { storiesOf } from "@storybook/react";
import { fakeGQLResponseOnce } from "../../lib/fakeQL";
import { TweetView } from ".";
import { tweet } from "../fixtures";

fakeGQLResponseOnce({ tweet });
storiesOf("TweetView", module).add("Default", () => <TweetView />);

[pieh]

Before diving into implementation details like that, let's see what are requirements for this mocking system.

I think there is at least few:

• There could be potentially multiple queries we would need to mock to display component - we do need a way to identify individual queries and way to supply mocks for each of them. I think query name is good candidate to use as query identifier
• We should be able to use different mocks for same query for different stories (i.e. to show variants of components that can look different depending if some optional data is there or not)
• It should support mocking static and page queries. Static queries are more straight forward I think, but using same techniques for page queries would be awesome
• It would be great if we could come up with solution that can work with various unit and integration tests tools and component library tools (I don't really have a concrete list here, but just from top of my head - cypress, jest, ... for testing, storybook, docz, ... for component library documentation (? not sure if docz need that as it does use gatsby under the hood, so it might already use production data, but would be great to be able to mock it). We don't need to integrate it for all those tools from the get go - just something to keep in mind.
• Can we make it easy to generate mocks/fixtures? Knowing queries and graphql schema that those queries execute against, there is potential to build tool around it (definitely not in scope for initial work)

[ascorbic]

• Using query name would certainly be the neatest way of identifying a static query, though it would be good to handle anonymous queries (assuming we allow them). In any case it would be good to allow users to provide a stack of responses per query name so that it could return different responses for subsequent calls. Then we could treat anonymous as just another name.
• I think the docs should encourage the mocking to happen right before a component is used, so inside each story or test, and in general using functions that only mock once. That would make it simple to provide the right data to each one.
• I don't know how useful it would be to mock page queries. If we no longer throw an error when page queries are not transpiled away, then we can treat page templates the same way as any other component: ignore the graphql, and pass them the data directly as a prop as if it were coming from GraphQL. Can you think of a situation where that wouldn't work?
• Yes, a generic solution that doesn't make any assumptions about the environment is exactly what's needed. I think that ideally it shouldn't require the babel plugin, for example.
• In the existing testing docs I suggested just running your query in GraphiQL and using the resulting data as the basis for your fixture. There might be a way of streamlining this, analogous to the code generator, but I'm not sure what would be useful to add. Perhaps a way of generating fixtures without access to the live data needed to run GraphiQL.

[gatsbot[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.

If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!

As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[github-actions[bot]]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here. If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open! As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[github-actions[bot]]

Hey again!

It’s been 30 days since anything happened on this issue, so our friendly neighborhood robot (that’s me!) is going to close it. Please keep in mind that I’m only a robot, so if I’ve closed this issue in error, I’m HUMAN_EMOTION_SORRY. Please feel free to reopen this issue or create a new one if you need anything else. As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks again for being part of the Gatsby community! 💪💜