Snapshot Testing GraphQL Queries

Written by Pete Corey on Oct 1, 2018.

For a recent client project, I’ve been building out a Node.js backend service fronted by a GraphQL API. A recent revelation made me realize just how useful Jest’s snapshot testing can be for writing high-level backend tests, specifically tests targeting GraphQL queries.

My typical approach for testing GraphQL queries is to import and test each query’s resolver function individually, as if it were just another function in my application.

Here’s an example to help paint a more complete picture:


const { bedCount } = require('...');

describe('Unit.bedCount', () => {
    it('it counts beds', async () => {
        expect.assertions(1);
        let user = await createTestUser();
        let unit = await Unit.model.create({ _id: 1, name: 'n1' });
        await Bed.model.create({ _id: 2, unitId: 1, name: 'b1' });
        await Bed.model.create({ _id: 3, unitId: 1, name: 'b2' });

        let result = bedCount(unit, {}, { user });
        expect(result).toEqual(2);
    });
});

Our test is verifying that a bedCount edge off of our Unit type returns the correct number of beds that live under that unit. We test this by manually inserting some test data into our database, importing the bedCount resolver function, and manually calling bedCount with the correct root (unit), args ({}), and context ({ user }) arguments. Once we have the result, we verify that it’s correct.

All’s well and good here.

However, things start to get more complex when the result of our query increases in complexity. We very quickly have to start flexing our Jest muscles and writing all kinds of complex matchers to verify the contents of our result.

What’s more, by testing our resolver function directly, we’re only testing half of our GraphQL endpoint. We’re not verifying that our schema actually contains the edge we’re trying to test, or the fields we’re trying to fetch off our our result type.

Thankfully, there’s a better way to test these queries. Using Jest snapshots we can refactor our original test into something like this:


describe('Unit.bedCount', () => {
    it('it counts beds', async () => {
        expect.assertions(1);
        let user = await createTestUser();
        await Unit.model.create({ _id: 1, name: 'n1' });
        await Bed.model.create({ _id: 2, unitId: 1, name: 'b1' });
        await Bed.model.create({ _id: 3, unitId: 1, name: 'b2' });
        let query = `
            query {
                unit(_id: 1) {
                    bedCount
                }
            }
        `;
        expect(await graphql(schema, query, {}, { user })).toMatchSnapshot();
    });
});

Here we’re once again setting up some test data, but then we perform an actual query through an instance of our GraphQL endpoint we set up on the fly. We pass in our application’s GraphQL schema (schema), the query we’d like to test (query), a root value ({}), and the context we’d like to use when performing the query ({ user }).

However, instead of manually verifying that the results of our resolver are correct, we make an assertion that the result of our GraphQL query matches our snapshot.

When we first run this test, Jest creates a __snapshots__ folder alongside our test. In that folder, we’ll find a bedCount.test.js.snap file that holds the result of our query:


// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`Unit.bedCount it counts beds 1`{:.language-javascript}] = `
Object {
  "data": Object {
    "unit": Object {
      "bedCount": 2,
    },
  },
}
`;

Any time the result of our query changes, our snapshot test will fail and give us a diff of our previous result saved in our snapshot, and the new, differing result.

The main benefit of this solution, in my mind, is that our query results can be as simple or as complex as we’d like. It doesn’t matter to us, as we don’t have to work with that data directly. We simply had it off to Jest.

Thanks Jest!

Living the Simple Life with Recursive Parsing and Serialization

Written by Pete Corey on Sep 24, 2018.

I just pushed a massive refactor of my Elixir-powered Bitcoin full node project that considerably simplifies the parsing and serialization of Bitcoin network messages.

I’m a big fan of the solution I landed on, and I wanted to share it with you. The key insight I had was to switch to a recursive solution where each sub-component of every messages handles its own parsing and serialization.

Obviously the devil is in the details, so let’s dive in.

What’s the Problem?

Before I took on this refactor, I was handling the parsing and serialization of Bitcoin network messages entirely manually. For every message, I’d define a parse/1 function and implement a corresponding serialize/1 protocol. Every field within the message was manually parsed and serialized using Elixir’s various binary manipulation operations.

As an example, here’s how a NetAddr message would be parsed using this technique:


def parse(binary) do
  with {:ok, time, rest} <- parse_time(binary),
       {:ok, services, rest} <- parse_services(rest),
       {:ok, ip, rest} <- parse_ip(rest),
       {:ok, port, rest} <- parse_port(rest) do
    {:ok, %NetAddr{time: time, services: services, ip: ip, port: port}, rest}
  end
end

defp parse_time(<<time::32-little, rest::binary>>),
  do: {:ok, time, rest}

defp parse_time(_binary),
  do: {:error, :bad_time}

defp parse_services(<<services::64-little, rest::binary>>),
  do: {:ok, services, rest}

defp parse_services(_binary),
  do: {:error, :bad_services}

defp parse_ip(<<ip::binary-size(16), rest::binary>>),
  do: {:ok, ip, rest}

defp parse_ip(_binary),
  do: {:error, :bad_ip}

defp parse_port(<<port::16-big, rest::binary>>),
  do: {:ok, port, rest}

defp parse_port(_binary),
  do: {:error, :bad_port}

While this was fantastic practice at manipulating binaries within Elixir, it wasn’t a scalable solution. There are simply too many messages in the Bitcoin protocol to implement in this time consuming way. Not only that, but many of the messages share common sub-structures who’s parse/1 and serialize/1 implementations would need to be repeated throughout the project.

Daunted with the task of implementing a parse/1 and serialize/1 function for every message in the protocol’s peer-to-peer vocabulary, I decided I needed a better solution.

Taking Advantage of Sub-Structures

As I mentioned up above, many Bitcoin messages share common sub-structures. Instead of dooming me to tedious repetition, I realized that these repeated structures were actually a blessing from the DRY gods.

If we could architect our parse/1 and serialize/1 implementations in a way that offloads the responsibility of parsing and serializing these shared sub-structures, the parsing and serialization implementations of our top-level messages could be substantially simplified.

Not only that, but we could take the notion of “sub-structures” even further. In many ways, the types of the primitives that compose together to build the protocol’s messages and sub-structures are sub-structures in and of themselves. For example, a uint32_t, which is a C type commonly used to define unsigned integers throughout the protocol’s various messages, is actually a sub-structure that has a single field and specific parsing and serialization rules.

We could implement a UInt32T struct with a corresponding parse/1 function like so:


defmodule BitcoinNetwork.Protocol.UInt32T do
  defstruct value: nil

  def parse(<<value::little-unsigned-integer-32, rest::binary>>),
    do: {:ok, %BitcoinNetwork.Protocol.UInt32T{value: value}, rest}
end

Similarly, we could reverse the process and serialize our newly parsed UInt32T:


defimpl BitcoinNetwork.Protocol.Serialize, for: BitcoinNetwork.Protocol.UInt32T do
  def serialize(%{value: value}),
    do: <<value::little-unsigned-integer-32>>
end

Composing Sub-Structures

Now we have parsing and serialization rules built for these base-level sub-structures like UInt32T and other primitive types. We can build upon the work we’ve done by composing these sub-structures together into more complex structure.

For example, a NetAddr is really just a UInt32T, a UInt64T, a sixteen byte Binary, and a UInt16T representing an addresses’ time, services, ip, and port, respectively. We can write a NetAddr struct complete with a parse/1 function that calls out to the parse/1 functions of these more primitive sub-structures:


defmodule BitcoinNetwork.Protocol.NetAddr do
  defstruct time: nil,
            services: nil,
            ip: nil,
            port: nil

  alias BitcoinNetwork.Protocol.{Binary, NetAddr, UInt32T, UInt64T, UInt16T}

  def parse(binary) do
    with {:ok, time, rest} <- UInt32T.parse(binary),
         {:ok, services, rest} <- UInt64T.parse(rest),
         {:ok, ip, rest} <- Binary.parse(rest, 16),
         {:ok, port, rest} <- UInt16T.parse(rest),
         do:
           {:ok,
            %NetAddr{
              time: time,
              services: services,
              ip: ip,
              port: port
            }, rest}
  end
end

Serializing a NetAddr structure is even easier. We simply build a list of the fields we want serialized, in the order we want them serialized, and then map over that list with our serialize/1 function:


defimpl BitcoinNetwork.Protocol.Serialize, for: BitcoinNetwork.Protocol.NetAddr do
  def serialize(net_addr),
    do:
      [
        net_addr.time,
        net_addr.services,
        net_addr.ip,
        net_addr.port
      ]
      |> BitcoinNetwork.Protocol.Serialize.serialize()
end

We’re left with an Elixir binary that represents the entire serialized NetAddr structure, but we didn’t have to do any of the heavy lifting ourselves.

The best part of this solution is that we can repeatedly build on top of our sub-structures. An Addr message is composed of a VarInt and a list of NetAddr sub-structures. It’s sub-structures all the way down.

Special Cases and Rough Edges

While the general case for this solution works beautifully, there are a few special cases and rough edges we need to smooth over.

The first of these rough edges comes when parsing and serializing fixed-size binaries. For example, within the NetAddr structure, we need to parse sixteen bytes off of the wire and interpret those bytes as an IP address. We instructed our NetAddr parser to do this by calling Binary.parse/2 with 16 as a second argument.

Our Binary module’s parse/2 function accepts an optional second argument that lets us specify exactly how many bytes we want to parse out of the incoming binary:


defmodule BitcoinNetwork.Protocol.Binary do
  def parse(binary, size \\ 1) do
    <<binary::binary-size(size), rest::binary>> = binary
    {:ok, binary, rest}
  end
end

Notice that Binary.parse/2 returns a primitive Elixir binary, rather than a struct. This is an intentional decision and makes our serialization that much easier:


defimpl BitcoinNetwork.Protocol.Serialize, for: BitString do
  def serialize(binary),
    do: binary
end

Another special case we need to handle is made apparent when we need to parse and serialize lists of “things”. A perfect example of this appears in our code when we need to parse an Addr structure, which is composed of a VarInt number of NetAddr structures:


with {:ok, count, rest} <- VarInt.parse(binary),
     {:ok, addr_list, rest} <- Array.parse(rest, value(count), &NetAddr.parse/1),
     do:
       {:ok,
        %Addr{
          count: count,
          addr_list: addr_list
        }, rest}

Like Binary.parse/2, Array.parse/3 has some special behavior associated with it. Our Array module’s parse/3 function takes our binary to parse, the number of “things” we want to parse out of it, and a function to parse each individual “thing”:


defmodule BitcoinNetwork.Protocol.Array do
  def parse(binary, count, parser),
    do: parse(binary, count, parser, [])
end

Our parse/3 function calls out to a private parse/4 function that builds up an accumulator of our parsed “things”. Once we’ve parsed a sufficient number of “things”, we return our accumulated list:


defp parse(rest, 0, parser, list),
  do: {:ok, Enum.reverse(list), rest}

The non-base case of our parse/4 function simply applies our parser/1 function to our binary and appends the resulting parsed “thing” to our list of “things”:


defp parse(binary, count, parser, list) do
  with {:ok, parsed, rest} <- parser.(binary),
       do: parse(rest, count - 1, parser, [parsed | list])
end

Once again, the result of our Array.parse/3 function returns a primitive Elixir list, not a struct. This makes our serialization fairly straight forward:


defimpl BitcoinNetwork.Protocol.Serialize, for: List do
  def serialize(list),
    do:
      list
      |> Enum.map(&BitcoinNetwork.Protocol.Serialize.serialize/1)
      |> join()

  def join(pieces),
    do: 
      pieces
      |> Enum.reduce(<<>>, fn piece, binary -> <<binary::binary, piece::binary>> end)
end

We simply map serialize/1 over our list of “things”, and concatenate the newly serialized pieces together.

If you remember back to our NetAddr serialization example, you’ll notice that we’ve been using our List primitive’s serialization protocol this whole time.

Awesome!

Final Thoughts

I struggled with this refactor on and off for a good few weeks. Ultimately, I’m happy with the solution I landed on. It’s more complex than my original solution in terms of the number of moving parts, but it’s a much more scalable and mentally manageable solution than the one I was originally working with.

Now that this is out of my system, I can turn my attention to the interesting pieces of building a Bitcoin full node: processing blocks!

Expect articles digging into that topic in the future. In the meantime, check out the entire project on Github to get a more hands-on feel for the refactor and the recursive parsing and serialization solution I ultimately landed on.

Minimal Coding with Spacemacs and Olivetti

Written by Pete Corey on Sep 10, 2018.

As I mentioned on Twitter, I’ve been experimenting lately with using a visually minimal Spacemacs setup. I’ve been using this new setup every day for several weeks, and I’m absolutely in love with it.

Want screenshots and an overview of how it works? Read on!

But First, Screenshots

Olivetti is an Emacs package designed to create a distraction-free writing experience within your editor. Most of Olivetti’s screenshots show it in the context of editing markdown. That makes sense, as the term “distraction-free writing” is usually applied to the context of writing prose.

But what if I want a “distraction-free writing” environment for writing code?

It turns out that Olivetti is still perfectly suited for the job. Check out a few screenshots of my current Spacemacs setup. Note that the screenshots below capture my entire screen, from edge to edge. There’s nothing behind the curtain here:

Spacemacs with Olivetti.

I’ve configured Olivetti to only activate when in prog-mode, or in text-mode. This means that things like Spacemac’s home buffer, and inline terminals retain their original layouts. This distinction has been working beautifully for me so far:

Spacemacs with multiterm.

Using Olivetti within Spacemacs

To get Olivetti working with Spacemacs, I needed an Olivetti layer. Unfortunately, an out-of-the-box Spacemacs layer doesn’t exist for Olivetti. Thankfully, the process of creating a custom, private layer isn’t a difficult one.

We can create a new private layer from within Spacemacs by running the configuration-layer/create-layer command with M-x (or SPC + :). Let’s call our layer olivetti. This creates a new ~/.emacs.d/private/olivetti folder and populates a packages.el file with some boilerplate.

We’ll replace the contents of packages.el with the following:


(defconst olivetti-packages
  '(olivetti))

(defun olivetti/init-olivetti ()
  (use-package olivetti))

This tells Spacemacs that we need the olivetti package, and to use the package once it’s been loaded.

Once that’s done, we need to edit our Spacemacs configuration file (SPC f e d), and add an olivetti entry under our dotspacemacs-configuration-layers list to instruct Spacemacs to load our new private layer.


(defun dotspacemacs/layers ()
  (setq-default
   ...
   dotspacemacs-configuration-layers
   '(
     ...
     olivetti
     )))

Finally, we need to configure Olivetti to run in prog-mode and text-mode. We can do this in our dotspacemacs/user-config callback:


(add-hook 'text-mode-hook (lambda ()
                            (interactive)
                            (message "Olivetti text-mode-hook")
                            (olivetti-set-width 81)
                            (hidden-mode-line-mode)
                            (spacemacs/toggle-vi-tilde-fringe-off)
                            (olivetti-mode 1)))
(add-hook 'prog-mode-hook (lambda ()
                            (interactive)
                            (message "Olivetti prog-mode-hook")
                            (olivetti-set-width 81)
                            (hidden-mode-line-mode)
                            (spacemacs/toggle-vi-tilde-fringe-off)
                            (olivetti-mode 1)))

I use this opportunity to tune Olivetti and Spacemacs to my liking. Feel free to make any changes you deem necessary.

With that, we’re good to go!

How To Not Get Lost

The key to not getting lost without any visual indicators is to always know where you are!

That may sound like a truism, but visually paring down my code editing environment has made me realize that there is no substitute for deep understanding and mastery of your tools. I don’t need a modeline to tell me which mode I’m in if I already know. I don’t need a constant reminder of which line I’m on, when I can navigate directly to any given line with :.

Many of the visual indicators that modern editors provide are really just noise. I’m not going to say that noise is never helpful, but you can almost always get by without it.

If you’re interested in seeing exactly how my Spacemacs is set up, you can see my entire .spacemacs file here. It’s very ugly. I’m warning you now.