DEV Community: Ryan Kennedy

Flip your tests

Ryan Kennedy — Tue, 28 Dec 2021 05:52:11 +0000

Automated tests are great. They can help you run through hundreds of input combinations in a matter of seconds, a task that would be prohibitively burdensome to test by hand.

In my experience, a typical test suite looks like this:

describe('my test suite', () => {
  it('should work with basic test case', async () => {
    const user = await UserFactory.create({});
    expect(user.id).toBe(null);
    expect(user.name).toBe(null);
  });
  it('should work with a long name', async () => {
    const user = await UserFactory.create({
      firstName: 'Pippilotta',
      middleName: 'Delicatessa',
      lastName: 'Windowshade Mackrelmint Ephraimsdaughter Longstocking',
    });
    expect(user.id).toBe(null);
    expect(user.name).toBe('Pippilotta Delicatessa Windowshade Mackrelmint Ephraimsdaughter Longstocking');
  });
});

This design reflects the order in which an engineer has approached the problem. Often, the test cases directly correspond to edge cases that the engineer has considered. Each test follows this approximate format:

Suite: all tests related to a particular subject or service
- Test: condition A
  - Set up test case
  - Validate results
- Test: condition B
  - Set up test case
  - Validate results
- More tests to cover desired set of conditions.

However, there are a few drawbacks to this style:

High cost of adding new tests. Each test setup must be copied into a new block in order to run the test.
Lack of atomic visibility into code failures. Most modern test runners quit the test suite upon finding the first failure. If you're running several checks together as described above, you will only see the first issue.

Here's an alternate design:

describe('my test suite', () => {
  describe('basic test case', () => {
    let user;
    beforeAll(async () => {
      user = await UserFactory.create({});
    });
    it('should set null user id', async () => {
      expect(user.id).toBe(null);
    });
    it('should set null user name', async () => {
      expect(user.name).toBe(null);
    });
  });
  describe('with a long name', () => {
    let user;
    beforeAll(async () => {
      user = await UserFactory.create({
        firstName: 'Pippilotta',
        middleName: 'Delicatessa',
        lastName: 'Windowshade Mackrelmint Ephraimsdaughter Longstocking',
      });
    });
    it('should set null user id', async () => {
      expect(user.id).toBe(null);
    });
    it('should correctly form full name', async () => {
      expect(user.name).toBe(
        'Pippilotta Delicatessa Windowshade Mackrelmint Ephraimsdaughter Longstocking'
      );
    });
  });
});

Suite: all tests related to a particular subject or service
- Suite: condition A
  - beforeAll/Each: set up test case
  - Test: Validate result 1
  - Test: Validate result 2
- Suite: condition B
  - beforeAll/Each: set up test case
  - Test: Validate result 1
  - Test: Validate result 2
- More test suites to cover desired set of conditions.

This has several advantages:

It's easier to debug when there are multiple failed tests. Sometimes you'll get one failure that triggers another. The previous approach, where you would only get a single failure message per test, would give you less information to help debug.
All test failures are written in plain English. This makes it much easier to figure out what's going on.
Passed tests are also written in plain English. This is also important! I believe very strongly in tracking the business decisions that led to a piece of code. Being forced to write out your tests in English makes it easier to realize when a piece of code is outdated and can be deleted.
It's easier to perform nested test setups. If you want to test multiple levels of variation — say, check against multiple combinations of username, email address, and password — you can keep nesting your test suites as deep as you want to go, using beforeAll or beforeEach to add detail at each level. Just make sure you use afterAll or afterEach to clean up each case as you exit!
It's easier to add placeholders for future tests. Many frameworks such as Jest have a modifier such as test.todo which allows you to write the title for a test without providing an implementation. This is much better than a // TODO comment, as your test runner will remind you that you still have some work left.

When you adopt a codebase, it's easy to fall into the patterns and conventions established by that codebase. With a little effort, though, you can start new habits that will reduce the amount of work you'll need to do in the future.

Handling hard-coded values

Ryan Kennedy — Wed, 22 Dec 2021 02:29:07 +0000

Hard-coded values -- typically content -- are often set up for rapid development in the early stages of a project. These values can get outdated pretty quickly, and can be hard to replace with dynamic values. Here are some suggestions for dealing with hard-coded values.

Use default props for hard-coded content

It's tempting to simply inline hard-coded content directly into the components you're writing. For example:

import * as React from 'react';
import * as styles from './ProductCard.module.css';

export default function ProductCard() {
  return (
    <div className={styles.card}>
      <img className={styles.cardImg}
        src="https://picsum.photos/200"
      />
      <h3>Running Shoes - $39.99</h3>
      <p><small>New as of October 28, 2021!</small></p>
      <p>Our best-selling running shoes.</p>
    </div>
  );
}

This will quickly get something onto the screen. However, it raises a few questions:

Which elements will remain the same for every product, and which elements will change?
Which elements might be shown or hidden for different products?
What format should the data be passed in?

Instead of inlining the content, try using defaultProps to provide it:

import * as React from 'react';
import * as styles from './ProductCard.module.css';

export default function ProductCard({
  productImgSrc,
  title,
  priceCents,
  promoMessage,
  description,
}) {
  const displayPrice = `$${(priceCents/100).toFixed(2)}`;
  return (
    <div className={styles.card}>
      <img className={styles.cardImg}
        src={productImgSrc}
      />
      <h3>{title} - {displayPrice}</h3>
      {
        !promoMessage ? null : (
        <p><small>{promoMessage}</small></p>
        )
      }
      <p>{description}</p>
    </div>
  );
}

ProductCard.defaultProps = {
  productImgSrc: 'https://picsum.photos/200',
  title: 'Running Shoes',
  priceCents: 3999,
  description: 'Our best-selling running shoes.',
  promoMessage: 'New as of October 28, 2021!',
}

Now, it's much easier to see what is dynamic, as well as which properties are optional. It's important that these default props be removed once you've moved past the demo stage, as you certainly don't want to push dummy values to production by accident, but this is true for any hard-coded demo content.

Move hard-coded content to its own file

Since you've already got your props broken out into defaultProps, it's pretty easy to move them to their own file used for content only. I like to move these files into an adjacent __tests__/data directory. This way:

it's super clear that this is fake data not meant for production, and
the data is readily available for writing tests. Two birds, one stone! ## Simulate endpoint responses for your fake data

This one is highly optional, but is a very helpful final step before updating your code to pull its content from an endpoint instead of local fake data.

Up until now, our fake data has been directly imported. When we fetch from a real endpoint, though, we won't have the luxury of requesting these values synchronously — we'll have to use Promises.

Luckily, most modern bundlers handle code splitting, and we've already split our content into a separate file. This means that we've already got a Promise-based way to request our data!

// ... inserted into existing file ...
import useSWR from 'swr';

/** It's helpful to add future parameters here. */
function useProductData(productId) {
  return useSWR(
    ['productData', productId],
    () => import('./__tests__/data/product-data.tsx')
  );
}

At this point, the only task remaining is to swap out the import statement for an actual fetch-based implementation.

What surprises have you discovered when working with hard-coded values?

Configuration vs composition

Ryan Kennedy — Thu, 14 May 2020 00:42:12 +0000

This post was originally published on rmkennedy.com.

When designing a complex, long-lived component, there's one tradeoff that I think about constantly. Do I want to configure my component, passing in a large object with options? Or do I want to build subcomponents, which can then be composed into the final interface?

What is the tradeoff?

I'll illustrate with two possible APIs for a React dropdown component. The first implementation uses a "configured" interface. All options for the component are expressed as data passed to a prop.

<ConfiguredDropdown
  value="lab"
  items={[
    {
      displayName: 'Labrador Retriever',
      value: 'lab',
    },
    {
      displayName: 'Pit Bull Terrier',
      value: 'pit-bull',
    },
    {
      displayName: 'Boston Terrier',
      value: 'boston-terrier',
    },
  ]}
/>

This gives you a single prop into which you pass your data. There are a few ways to do this, but depending on my data source myItems I might write something like this:

<ConfiguredDropdown
  items={myItems.map((item) => ({ displayName: item.name, value: item.id }))}
/>

Implementation of the ConfiguredDropdown component is fairly straightforward -- iterate over each value in items and render the corresponding menu item. Done.

However, once your component makes it out into the "real world", the assumptions you made initially could break down. What if you want onClick and onHover handlers? Additional CSS for some menu items? Submenus? It's certainly possible to add new features to your component for each use case, and in some cases this may work well. However, there's an alternative implementation that could save you some effort.

Consider instead a "composed" interface. Instead of options, the dropdown items are conceptualized as content, and accordingly are passed as React children.

<Dropdown value="lab">
  <DropdownItem displayName="Labrador Retriever" value="lab" />
  <DropdownItem displayName="Pit Bull Terrier" value="pit-bull" />
  <DropdownItem displayName="Boston Terrier" value="boston-terrier" />
</Dropdown>

Now, your data items are passed as children instead of as a data prop. The code for passing in a custom data source myItems hasn't changed much:

<Dropdown>
  {myItems.map((item) => (
    <DropdownItem key={item.id} displayName={item.name} value={item.id} />
  ))}
</Dropdown>

The benefit here is that, as long as you pass unrecognized props to the underlying DOM element, you no longer need to anticipate your user's needs. onClick and onHover? Passed through. Custom CSS? Both style and className are available. Submenus? Possible to build using a combination of the other properties.

(aside) There's a side benefit, too; when each item is a subcomponent, each item gets the benefits of React's prop diffing.

With the configured component, the whole dropdown would re-render if you changed one item; with the composed component, React would only rerender the item that changed. This wouldn't matter in a small example like this, but on larger, more complex components you may see a performance boost.

A real-world example

My favorite example of this type of tradeoff is Handsontable vs react-virtualized.

Handsontable is an amazing library. I've used it professionally, and it has options for most things you might want to achieve with a spreadsheet in the browser. Most... but not all. Between 2017 and 2019 I was on a project to build a search application for biological data, and due to the complexity of the results display I chose Handsontable. It worked well for a while, but eventually I found myself needing features outside its customizable parameters.

If I had to write that project again, I'd reach for react-virtualized. This library offers primitives — AutoSizer, Grid, and ScrollSync, to name a few — that you compose to meet your application's needs. Granted, react-virtualized does not offer spreadsheet capabilities like Handsontable, but I could imagine an alternate API for a spreadsheet component with more composability.

Creating your own composed APIs

Here are some tactics you can use in your own codebase.

Use Context, Providers, or Services to your advantage

Complex applications often contain multiple components that must work together in sync. In my experience, unless the developer pays attention to the design, this tends to generate "God components" that render everything and manage state. These components are tightly coupled and require effort to maintain.

Many front-end frameworks offer mechanisms for synchronizing multiple components. React offers Context, Vue has provide / inject, Angular has services, and Svelte provides getContext / setContext.

If you have a special case to handle, or if you're not using one of the above frameworks, don't be afraid to use a singleton. As long as state changes are reported correctly, and you observe the rules of your chosen view layer (e.g. never mutate an object passed as a React prop) then a singleton could dramatically simplify your implementation.

Functions are the best configuration

Sometimes, your library truly does require configuration. Traditionally, this is done with a configuration object with a specific documented API. However, you may want to consider accepting functions as configuration. By passing responsibility to the user, you are not only writing less code, but also adding greater flexibility to your API. React render props are a great method for allowing consumers to customize a component, and my favorite example of a render prop API is Downshift.

Exposing a composed API as a configurable one

If you want to simplify certain use cases, it doesn't take much code to wrap a composable component and present it as a configurable component instead. Here's a suggestion of how I might implement ConfiguredDropdown based on the Dropdown and DropdownItem components above:

// Since this is just an illustration, I'm not going to do anything special with `value`.
export function ConfiguredDropdown({ items }) {
  return (
    <Dropdown>
      {items.map(({ displayName, value }) => (
        <DropdownItem key={value} displayName={displayName} value={value} />
      ))}
    </Dropdown>
  );
}

This is useful when you want to offer a "base" version of your component that covers 80% of the use cases, but also add an "advanced" version where users can compose to get the functionality they want.

But as always: use your own judgement

Some circumstances — performance goals, interoperability, other constraints — may change the calculus, and you may find it a better fit to design a configured rather than composed component. In small cases, you may not even notice the difference. You are the architect of your own apps, so while you should keep these points in mind, decide for yourself on a case-by-case basis which approach you want to take.

References

Ryan Florence, "Compound Components" (YouTube)
Kent C. Dodds, "How to use React Context effectively"
Svelte Tutorial, "Context API"

Waiting for that important call

Ryan Kennedy — Wed, 14 Mar 2018 13:42:31 +0000

Sometimes while testing, it's necessary to wait until a function has been called. Maybe you're testing code with Node-style callbacks; maybe you're working with a React render prop. Regardless of how you got there, your test needs to pause until some function has been called. It's possible to wait for a promise to be fulfilled, but how do you wait until an arbitrary function has been called?

The problem

Suppose your test looks like this:

const createEmitterOfSomeSort = require('./myEmitter');

it('should do the thing', async () => {
  const emitter = createEmitterOfSomeSort();
  const callback = jest.fn();
  emitter.on('my-event', callback);

  // TODO: wait for the callback to be called before proceeding

  // Check values which will only change after the given event
  expect(emitter.color).toBe('blue');
});

This test needs to wait for my-event to be fired asynchronously before the color gets set. Otherwise, the test prematurely races through to its completion.

It's possible to wrap this all in a Promise which will resolve when your event is fired. I've done this loads of times in tests; it's tedious! It's also a pain to refactor. Suppose you want to wait for the event to fire 5 times instead of just once. This requires additional work and added complexity to your test.

My attempted solution

I decided to write and publish my solution as the anticipated-call package. This utility is capable of wrapping any function, and gives you an easy way to obtain a promise which resolves once the function has been called.

Here's an example of how you might use it in a test:

const anticipated = require('anticipated-call');
const createEmitterOfSomeSort = require('./myEmitter');

it('should do the thing', async () => {
  const emitter = createEmitterOfSomeSort();
  const callback = anticipated(jest.fn());
  emitter.on('my-event', callback);

  await callback.nextCall;

  // Check values which will only change after the given event
  expect(emitter.color).toBe('blue');
});

The await statement is the magic sauce: it'll pause the test's execution until the callback is called.

Now, if you decide the event needs to be fired 5 times instead of just once, it's simple to update your tests:

  await callback.nthNextCall(5);

Testing React render props

This package has helped me the most when I'm writing render-prop components. Suppose you have a component responsible for fetching data that's used like this:

(<MyTweetFetcher
  render={({isLoading, username, tweets}) => (
    <h2>{isLoading ? 'Loading...' : username}</h2>
    <ul>
      {tweets.map((tweet) => (
        <li key={tweet.id}>{tweet.content}</li>
      )}
    </ul>
  )
/>)

These components commonly call the render prop multiple times in response to asynchronous operations. This behavior creates a problem for writing tests: you need to make sure that the callback received the correct arguments, but you can't perform that check until the component has been rendered. anticipated-call comes to the rescue:

const Enzyme = require('enzyme');
const anticipated = require('anticipated-call');

const MyTweetFetcher = require('./MyTweetFetcher');

it('should call the render prop with the correct arguments', async () => {
  // The render prop needs to return a valid React node, so use `null` here.
  const renderProp = anticipated(jest.fn(() => null));

  // The `nextCallDuring` method allows you to tell `anticipated-call` that
  // the function should be called as a result of running the passed callback.
  await renderProp.nextCallDuring(() => {
    Enzyme.mount(<MyTweetFetcher render={renderProp} />);
  });

  // The render prop will initially be called while data is loading.
  expect(renderProp.mock.calls[0].isLoading).toBe(true);

  // Wait for the render prop to be called again, after the data has loaded.
  await renderProp.nextCall;

  expect(renderProp.mock.calls[1].isLoading).toBe(false);
  expect(renderProp.mock.calls[1].tweets).toBeInstanceOf(Array);
});

Friendlier testing

This package is pretty small; it does nothing that can't already be done with a bit of Promise-wrangling. However, its appeal lies in the fact that you no longer have to engage in any Promise-wrangling. When I need to wait for a callback, I throw anticipated-call at it and save my energy for more difficult problems.

Check out anticipated-call on npm and submit PRs or issues on Github if you have ideas for improving it!