Mocking the GitHub API

[thecodedrift]

A bit of context: The key data operations of Outstatic flows through one mutation and a few queries based on the GitHub API. Because GitHub's API can return a huge variety of responses (and there's a good number of corner cases - #17 ), we should figure out the best way to mock out the GitHub API for the queries and mutations we use.

Here's a few known solutions with existing docs as a starting point for the discussion. I'd recommend anyone with experience on mocking GraphQL endpoints chime in so we can figure out the most maintainable way to manage the critical paths. Live examples of other code implementations are awesome, as are forks that show outstatic using mocks for testing.

Some basic requirements:

• Works with Jest - the repo currently uses Jest, and I don't believe there's value in upending the test infra in the name of the API tests
• No Docker - A non-docker version ensures developers can run tests locally. While in CI/CD that isn't an issue, the earlier code is caught the better DX people submitting PRs and fixes will have
• Supports Fragments & Inline Fragments - GitHub API uses Fragments A LOT. Every ... on Blob is a different return type and GitHub allows you to take a blob and turn it into a tree, a commit, etc. Any mocking for GQL needs to take this into account since it's hard to write a GraphQL query for GitHub that doesn't use these conventions

---

Mock Service Workers is a mock at the API layer itself. Possible responses can be generated using the GitHub GraphQL Explorer which makes it easy to create a reproducible test case. Because MSW is the API layer, all existing Apollo code can remain the same with the exception of the GraphQL endpoint URL.

Apollo Mocking is the official recommendation from the Apollo team, which is very useful when there's a clear separation of the client and the GraphQL service. By maintaining a client schema that represents the calls we intend to make, we can use addMocksToSchema to place mocked responses into the Apollo Client.

GraphQL Faker takes a GraphQL SDL, uses faker, and generates hypothetical responses. It has a docker container and can also just be started from a CLI. Admittedly, this is the one I know the least about. It serves as a proxy, letting you stub out whatever you need and letting the rest flow through to the GitHub API.

[avitorio]

Hey @jakobo,

Thank you so much for this. I was taking a look at this example. It seems we can do something similar for the few calls we have so far.

We could create a PR to test for a specific query like our Collections query . Let me know if you'd like to try creating a POC for this.
If not, you've already helped a lot just by opening this discussion. Thanks!

[thecodedrift]

The earliest I can tackle this is Tuesday. It'd be a fork I'd link here (no PR) for discussion, so that we can see it in practice and make sure that's the direction we'd like to go.

[avitorio]

Thanks. Sounds great. No rush here.

One thing that came to mind is how we could refactor our current code to support other Git providers in the future. But I guess this is a discussion that should come afterwards.

[thecodedrift]

Was thinking about how we support other Git Providers. The short answer is that this is probably an abstraction since not all APIs are the same between platforms. Doable, but definitely something to be done much later. Picking core tech now lets the project stay good at its main use case.

[thecodedrift]

Okay, here's the Mock Service Worker with supporting tests:

https://github.com/jakobo/outstatic/tree/jakobo/d/25

Change Highlights:

• jest setup now stubs out env vars required for server side environments
• mocks are created for browser/server MSW, as well as handlers for GraphQL requests. Additionally, a mock utility for NextRequest and NextContext were added to support tests that use Server Side Props
• the test file which tests both a successful github API call and a call that fails with a generic GraphQL error

[avitorio]

Thank you @jakobo! At a glance this looks solid. Feel free to open the PR, I'll review it as soon as I can.