GraphQL subscriptions API

[kettanaito]

With the introduction of WebSocket support (#156), it's time to draft the GraphQL subscriptions API in MSW. I'd like to use this document to propose a public API and have any related discussions with the community.

• Implementation: feat: support GraphQL subscriptions #2357

Proposed API

import { graphql } from 'msw'

const service = graphql.link('*')

export const handlers = [
  // Listen to a subscription being established in the app.
  // This can only work for named subscriptions. Unnamed subscriptions
  // are triggered by `service.pubsub.publish` directly.
  service.subscription('NotifyOnComments', ({ query, variables }) => {
    // Send events directly from the subscription handler.
    // This is handy for events that don't correspond to any
    // queries/mutations (e.g. outsourced events).
    service.pubsub.publish('EVENT_NAME', {})
  }),

  service.mutation('CreateComment', () => {
    // Publish an event to the subscription to notify all subscribers.
    service.pubsub.publish('EVENT_NAME', {})
  })
]

I'm not the biggest fan of .pubsub. but if that's a widely known pattern, I don't mind. We need to scope the subscription events emitting to something in any case.

Usage

First, you create a GraphQL link via graphql.link(). Only GraphQL links will get the .subscription() method. This aligns with our direction to drop link-less GraphQL support (#1892) and also acts as a requirement for a granular WebSocket endpoint interception.

From here, you have multiple ways to interact with subscriptions:

1. You can handle an exact subscription query via .subscription(queryName, resolver). This is handy if you want to react to when your app establishes that subscription. In this scenario, your resolver acts as the source of truth that can publish data to that subscription on demand.
2. You can publish data to the subscription in other queries/mutations you have. You use the GraphQL link directly to do that: link.pubsub.publish(event, data).

Example

• add apollo (subscriptions) example examples#127

Resources

• graphql-ws protocol specification

Questions

• Verify this approach with the folks working with GraphQL subscriptions extensively. I want the mocking API to resemble the actual usage as closely as possible.
• Gather more use cases around GraphQL subscriptions (and mocking it) to make sure it's supported by the API.
• Do you expect subscriptions to be returned from graphql.link() to stay consistent? Should MSW implicitly add a WebSocket handler to the same link URL but with a switched protocol? Would you prefer a standalone graphql.wsLink(url) instead?
• Need to somehow defer the WebSocket handler until the user accesses/needs to intercept subscription. There's no need to provide it otherwise.
• Should subscriptions be passthrough like quries/mutations, or mock-first like WebSocket handlers?

[kettanaito]

Question: Using AsyncIterator

A lot of resources I find promote the usage of AsyncIterator as a resolver for GraphQL subscriptions. I fail to see how that's intended to work. Does this concern mostly polling-based transports? Because in event-based architectures you rely on listeners not iterators.

Who calls this iterator then? The polling client when checking if any updates occurred? But I thought subscriptions are mostly based on the graphql-ws package that relies on WebSockets.

[ducin]

API design question: since you subscribe directly on service: service.subscription(..., why do you publish via an additional pubsub object: service.pubsub.publish? Usually the pubsub thing exposes both publish and subscribe, so in this case I'd expect service.subscribe and service.publish - or both service.pubsub.subscribe and service.pubsub.publish.

Anyway, an immediate question arises (for me): what's the difference (in the API) between the service object and the pubsub object. And it seems one could be unnecessary. But most probably I lack some context or something 😄

[kettanaito]

why do you publish via an additional pubsub object: service.pubsub.publish?

Because service is just a link, it's not specific to subscriptions. You use it to intercept queries and mutations too! That's why putting root-level .publish() on the service feels out of place.

const service = graphql.link(endpoint)

service.query('GetComment', resolver)
service.mutation('CreateComment', resolver)
service.subscription('NotifyOnComment', resolver)

what's the difference (in the API) between the service object and the pubsub object

You use the service object to intercept a subscription your app establishes. You use its .pubsub. to push events to any subscription from anywhere. service.subscription() is read, service.pubsub.publish() is write.

The goal here is to distinguish somehow the use case of (1) listening to a subscription by name and controlling it from the mock; (2) pushing any events to the underlying socket to trigger any subscriptions (not necessarily those explicitly intercepted to in the mock).

Does it make more sense this way?

[destin-estrela]

Posting as someone with no experience using msw or the graphql test library. I was directed here from this ticket where I discussed improvements to mocking subscriptions for tests. Our team uses @apollo-client along with their MockLink to test our GraphQL API. I was recommended to use this library instead and need to plan a path to migrate fully.

Here's one simple example of what one of our subscription tests look like now;

it('displays a notification when an alert arrives', async () => {
    const testSubscriptionLink = new TestSubscriptionLink();
    const mockedResponses: MockedResponse[] = createBackendStateMocks({}); 

    renderPage(
      mockedResponses,
      testSubscriptionLink,
    );

    // wait for all the queries to finish loading
    expect(await screen.findByLabelText('alert-status')).toBeInTheDocument();

    // push an update to the graphql subscription
    testSubscriptionLink.pushSubscriptionEvent(
      createMockSubscribeAlert({id: '1'}), // this is a `MockedResponse` that the subscription will then push to the `useSubscription` hook data
    );

   // assert behavior 
    expect(
      await screen.findByText('alert-notification'),
    ).toBeInTheDocument();
  });

In this case, the MockedResponse I push to our custom link will make it so only the matching useSubscription hooks will rerender in the test, thus simulating an update from the websocket.

We have a few complex behaviors that do a lot of cache surgery and state manipulation based on incoming subscription results. We want it to be ergonomic and straightforward to test those in addition to the traditional queries and mutations. We also want to ensure the subscriptions are initialized with the correct arguments and fail the test otherwise. Figuring out how to accomplish those will be the main task in order to fully migrate to this library.

All of this commentary may be far too specific and removed from the level of abstraction this library aims to provide, but I hope it helps give some context from one potential user.

[kettanaito]

Hi, @destin-estrela. Thanks for providing this use case!

I believe this should be possible to do with MSW. This is how I'd do it:

import { graphql } from 'msw'
import { setupServer } from 'msw/node'

const api = graphql.link('http://your/graphql/endpoint')
const server = setupServer(api.pubsub.handler)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

it('displays a notification when an alert arrives', async () => {
  renderPageWithoutAnyMockLinks()

  // wait for all the queries to finish loading
  expect(await screen.findByLabelText('alert-status')).toBeInTheDocument();

  // push an update to the graphql subscription
  api.pubsub.publish(createMockSubscribeAlert({id: '1'}))

  // assert behavior
  expect(
    await screen.findByText('alert-notification'),
  ).toBeInTheDocument();
});

The .pubsub.publish() API would work best in this scenario as you want to publish something at a certain point during the test run. For other cases, you can also use:

server.use(
  graphql.subscription('SubscriptionName', ({ subscription }) => {
    subscription.publish(createMockSubscribeAlert({id: '1'}))
  })
)

This will publish data to the subscription matching the given name immediately as that subscription is established on the client.