DEV Community: Jason Gaare

Creating and Testing Apollo Client Links

Jason Gaare — Mon, 23 Oct 2023 15:29:59 +0000

When using Apollo Client, there might come a time when you want to inspect or make some changes to your GraphQL requests. This is where Apollo Link comes into play. The library sets up a chain of actions for each GraphQL operation the client executes.

What exactly is a link, and how would we create and test one? Let's get into it and see what's going on.

Understanding the Concept of a Link

In order to grasp the concept of a link in the context of Apollo Client, let's start with what the docs tell us:

The Apollo Link library helps you customize the flow of data between Apollo Client and your GraphQL server. You can define your client's network behavior as a chain of link objects that execute in a sequence. Each link should represent either a self-contained modification to a GraphQL operation or a side effect (such as logging). Source

When Apollo Client initiates a request, the request traverses through the chain of links until it reaches a terminating link. Typically, the terminating link is responsible for executing the actual fetch to the GraphQL server and managing the subsequent response. The response then travels back through the chain in reverse order.

// The `from` function combines an array of individual links into a link chain
const client = new ApolloClient({
  link: ApolloLink.from([errorLink, myCustomLink, httpLink]),
  ...
});

// alternatively, you can also use concat like so
const client = new ApolloClient({
  link: errorLink.concat(httpLink)
  ...
});

Creating a Link

There are two types of links: stateless and stateful. A link is an instance of the ApolloLink class (or a subclass of it) and each link requires the definition of a request handler: request(operation, forward).

Let's take a quick look at those two request handler params:

operation - this is all the juicy info about the current, well, operation - the entirety of the query and what is attached to it. Here we can easily access operation.query and operation.variables to understand information about the request, as well as the rest of the context for the request via operation.getContext()
forward - this is a function that takes the operation and forwards it to the next link, like so: forward(operation)

Handling Responses in the Link Chain

Now that we've successfully forwarded the operation along the link chain, it's time to handle the response as it journeys back through the chain. To accomplish this, we need to establish an observer and subscribe to the response.

Fortunately, this process is quite straightforward. Apollo Client provides the Observable class for precisely this purpose. You can employ this class to set up an observer subscription. Here's how it's done:

import { Observable } from '@apollo/client';

// the required request handler
request(operation, forward) {
  return new Observable((observer) => {
    const subscription = forward(operation).subscribe({
      next: (result) => { 
        observer.next(result);
        observer.complete();
      },
      error: (error) => observer.error(error),
      complete: () => observer.complete(),
    });

    return () => {
      subscription.unsubscribe();
    }
  });
}

In the code snippet above, we create a new Observable instance within the request function. This Observable instance facilitates the subscription to the response. We subscribe to the response by forwarding the operation and defining handlers: next, which receives the data from a successful operation attempt, error, and complete, which signals we are done with handling the response.

While the code above represents a straightforward way to set up a subscription, it really doesn't do anything yet. The real magic happens when we add custom logic into this process. For instance, if we set a startTime in our request handler before forwarding the operation, we can then utilize our observer logic to calculate total request time:

request(operation, forward) {
  // set the startTime before we forward the operation
  operation.setContext({
    startTime: Date.now(),
  });

  return new Observable((observer) => {
    const subscription = forward(operation).subscribe({
      next: (result) => { 
        const { operationName } = operation;
        const startTime = operation.getContext().startTime;

        if (operationName && startTime) {
          // calculate total request time in our observer
          logRequestTime(
            operationName, 
            Date.now() - startTime
          );
        }

        observer.next(result);         
        observer.complete();
      },
      error: (error) => observer.error(error),
      complete: () => observer.complete(),
    });

    return () => {
      subscription.unsubscribe();
    }
  });
}

Here, we perform additional logic by recording the request time before forwarding the result to the observer. This flexibility enables you to intercept and manipulate data seamlessly within Apollo, adding a powerful tool to your toolkit.

Testing Apollo Links

When testing an Apollo Link, it's useful to write a separate simple link which acts as a terminating link. Then, create a composed link with the link to test, with the terminating link being our mock link. This test link should be simple and respond in a predetermined the way in the scope of our testing.

Here's an example mockLink:

const mockLink = new ApolloLink((operation) => {
  const context = operation.getContext();
  const { mockError, mockResponse } = context || {};

  return new Observable((observer) => {
    if (mockError) {
      observer.error(mockError);
      return;
    }

    if (mockResponse) {
      observer.next({ data: mockResponse });
      observer.complete();
      return;
    }

    observer.error(
      new Error('mockLink: You must provide mockError or mockResponse')
    );
  });
});

Within the mockLink function, we inspect the operation's context to check for the presence of mockError or mockResponse. We construct an Observable which, depending on the context either emits a mock error or a mock response wrapped in the expected data structure. In case neither is provided, the mockLink generates an error to ensure that test cases explicitly define the expected behavior.

This link then sends data or an error back down the chain (in our case, back to the link we are testing).

A Simple Link to Test

Let's see this in action to make more sense of it. Imagine our link OperationHistoryLink does exactly that: keeps an array of our operations in order as we execute them. We can create a stateful link to handle this for us:

import { ApolloLink } from '@apollo/client';

// stateful link
class OperationHistoryLink extends ApolloLink {
  operationHistory = [];

  request(operation, forward) {
    this.operationHistory.push(operation);
    return forward(operation);
  }
}

To test this, we must execute a query, then assert the operation is added to the array when it succeeds.

import { execute } from '@apollo/client';

describe('OperationHistoryLink', () => {
  it('adds operation to the operationHistory array on success', () => {
    const operationHistoryLink = new OperationHistoryLink();
    const composedLink = operationHistoryLink.concat(mockLink);

    return new Promise((resolve) => {
      const operation = {
        query: 'some query',
        context: {
          mockResponse: { foo: 'bar' },
        },
      };

      execute(composedLink, operation).subscribe({
        next: ({ data }) => {
          expect(data.foo).toBe('bar'); // mockResponse is handled by mockLink
          expect(operationHistoryLink.operationHistory).toHaveLength(1);
          expect(operationHistoryLink.operationHistory[0].query).toEqual(
            operation.query,
          );
          resolve();
        },
        error: () => {
          // optionally reject or throw here, we shouldn't get an error
        },
        complete: () => {},
      });
    });
  });
});

A few things to note about our test:

To trigger our GraphQL operation, we use the execute function provided by Apollo Client. This function begins the process of sending the operation down the link chain, creating an observer subscription with the same signature as we used in our link itself (next, error, complete)
To ensure that our test has time to execute, we use a Promise. This allows us to await the resolution of the Promise, ensuring that our test assertions are carried out only after the GraphQL operation has completed its execution
Our assertions live inside our next subscription callback. Of course, when our data comes back from our mockLink, we can expect it to match what we sent in the context. However, the main thing we are asserting here is the operationHistory in our OperationHistoryLink has a length of 1. If that is true, we know our link is working as intended!

OperationHistoryLink
    ✓ adds operation to the operationHistory array on success (3 ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        2.141 s

Success! We have now successfully created a custom link, and written a test to assert its functionality.

Want to try it out yourself? You can view all the code here

Cover Photo by Aylin Çobanoğlu on Unsplash

Triggering Bitrise Builds via Pull Request Label

Jason Gaare — Wed, 01 Sep 2021 19:43:57 +0000

Bitrise makes mobile deployment a breeze, but the options they provide for automatic build triggers are very all-or-nothing. In this post, we'll go over how to easily trigger Bitrise builds, but only when we want to.

Triggering Bitrise Builds

Bitrise provides "fast, flexible, and scalable mobile CI/CD that just works." That's actually quite accurate! Creating and triggering build workflows is straightforward with Bitrise.

Out of the box, it easily integrates with your Git provider. After integration, Bitrise uses webhooks to provide the following automatic build triggers:

Trigger via push to a specific branch (or, ANY branch)
Trigger via pull request (can filter by target or source branch)
Trigger via specified git tag

These are super helpful for many workflows, however our ideal trigger wasn't quite covered...

Close But No Cigar

At CompanyCam, our ideal trigger would be closest to the "Trigger via pull request" method, but we really didn't want every single PR to trigger a build (we are paying for each of these builds, after all).

First off, certainly not all PRs would require our entire pipeline to run, especially if all that changed was the README! Other smaller changes could easily be tested on our nightly builds and wouldn't require an entire dedicated build.

Secondly, filtering and triggering builds via a branch naming convention could work, but would require developers to either:
(a) have prior knowledge when creating their branch that they would later want a Bitrise build for that branch, or
(b) rename/duplicate their branch as they encountered the need for a build (to match the triggering naming convention)

Neither of these felt ideal.

We were looking for a way to enable our developers to selectively choose whether their PR would or would not have a Bitrise build associated with it, at the moment they opened the PR (or even after!)

Ad-Hoc Automation

The solution we sought was simple. We were looking for a way to add "Trigger by PR Label" functionality to connect our repository and Bitrise. How could we achieve this ad-hoc automation?

Well, more on that in a second... but first, there's a hidden gem you should know before we go further (one that we'll use shortly):

While using the Bitrise web app, when you click "Start/Schedule a Build", navigate to the Advanced tab, and scroll to the bottom, you should find this handy-dandy, copy-paste-ready cURL request for triggering a build (with the specific options you added in the form above) - Slick!

Putting Our Labels to Work

Okay, now we can actually answer "How could we achieve this ad-hoc automation?"

Enter: GitHub Actions.

Along with our copy-paste-ready cURL request, and some simple logic to check for a label with the name "Build Bitrise" (code below), we have a short and simple GitHub action that effectively acts as a "Trigger Build by PR Label" for our repository.

✨ Now, any PR with any source or target or branch name can have an associated Bitrise build simply by slapping a label on it!

Here's the entire GitHub Action we use: (with some secrets removed).

Happy Triggering!

About CompanyCam

👋 Hi, we’re CompanyCam. We create simple-to-use, visual-first communication and accountability tools for contractors.

We are almost always hiring developers (we like React and Rails a lot). Check out our careers page to learn more.

Post Script

You might have noticed, there are some extra params we added to the copy-paste-ready cURL request:

"build_params":{
  "branch":"${{ github.head_ref }}",
  "branch_dest": "${{ github.event.pull_request.base.ref }}",
  "workflow_id":"deploy-internal",
  "commit_hash":"${{ github.event.pull_request.head.sha }}",
  "pull_request_id": ${{ steps.pr_number.outputs.number }}
},

These params help better identify this PR in Bitrise, and perhaps most importantly help with associating future builds from the same PR to maintain the rolling builds functionality provided by Bitrise 🎉

Credits

Cover Photo by Dan-Cristian Pădureț on Unsplash