DEV Community: Sergio

Uncovering and conquering async bugs: A trick to testing undesired effects

Sergio — Thu, 05 Jan 2023 22:29:20 +0000

Imagine you are coding a new React component to upload a file. The component will receive a callback to notify the app if the upload has been or has not been successful. You may end with something similar to:

/**
 * We will use the `executor` function to simulate different
 * scenarios from our tests.
 */
function UploadButton({ executor, onSuccess }) {
  return (
    <button
      type="button"
      onClick={async () => {
        await executor();

        onSuccess();
      }}
    >
      Upload
    </button>
  );
}

To test the most simple scenario, that the <UploadButton /> component uses the callback once the upload is completed, we can rely on the standard approach:

it("uses the callback to notify that the upload completed", async () => {
  const spy = jest.fn();

  render(<UploadButton executor={success} onSuccess={spy} />);

  user.click(screen.getByText("Upload"));

  await waitFor(() => {
    expect(spy).toHaveBeenCalledTimes(1);
  });
});

But things are more complicated if we want to ensure that the onSuccess callback is not executed if something unexpected happens and the process fails. The initial and most naive implementation might be to assure that the spy is never called when using the failing executor:

it("does not use the callback if something goes wrong", async () => {
  const spy = jest.fn();

  render(<UploadButton executor={fail} onSuccess={spy} />);

  user.click(screen.getByText("Upload"));

  await waitFor(() => {
    expect(spy).toHaveBeenCalledTimes(0);
  });
});

Even if it passes, the test is not checking that the spy never gets called. Since the executor is an asynchronous process, and the spy starts with zero calls, the expectation is valid immediately. You can spot this by replacing executor={fail} with executor={success} --that’s the kind of change that should make the test have a different result, but it continues passing!

To test this scenario, we need to come up with a different approach:

it("does not use the callback if something goes wrong", async () => {
  const asyncRender = new Promise<undefined>((resolve, reject) => {
    render(<UploadButton executor={fail} onSuccess={reject} />);

    user.click(screen.getByText("Upload"));

    setTimeout(resolve, 0);
  });

  await expect(asyncRender).resolves.toBeUndefined();
});

By embracing the asynchronous nature of this problem, we can wrap the rendering within a promise and use its reject function as the onSuccess callback. Remember that promises execute immediately but return a delayed response. To give some room for the component to fail, I use the setTimeout trick to force the process to complete pending tasks from the queue.

Now, asyncRender should always resolve (with an undefined value). If it does not, our component is having issues handling the onSuccess callback and calling it even when the upload fails (since it is what the failing executor does). If you change executor={fail} to executor={success}, you may see the result keeps consistent, and the test fails.

Ready to keep the conversation going? Let's connect on Twitter and continue the discussion!

Happy hacking!

React: Using children instead of dedicated render slots

Sergio — Tue, 13 Dec 2022 12:30:57 +0000

Using component props to pass data (or JSX elements directly) that will later populate internal UI pieces has been a prevalent pattern in the React community, trying (probably) to emulate the better-designed slot approach adopted by Vue.

For example, imagine we are coding a new Nav component for our site. It will render a collection of nav items, the page title, and a call to action link. Each page might customize any of these elements.

Not surprisingly, I think either of these two would be the most popular examples we might find out there (or a combination of both):

// Passing simple data structures with the desired data
<Nav
  cta={{ text: "Buy the book!", href: "https://url.to/buy-my-book" }}
  menuItems={[
    { text: "Home", href: "/home" },
    { text: "About", href: "/about" },
    { text: "Contact", href: "/contact" },
  ]}
  title="My Site"
/>

// Passing JSX elements directly
<Nav
  cta={<a href="https://url.to/buy-my-book">Buy the book!</a>}
  menuItems={
    <>
      <li>
        <a href="/home">Home</a>
      </li>

      <li>
        <a href="/about">About</a>
      </li>

      <li>
        <a href="/contact">Contact</a>
      </li>
    </>
  }
  title={<h1>My Site</h1>}
/>

Even in such as simple example, we can start seeing some of the problems with this approach: it creeps the component API with render props, it is not very idiomatic, and it can quickly get worse as we continue adding some more customization for each element. For example, we may later add specific props to styling each of the items, title, and call-to-action components: menuItemStyle, titleStyle, ctaStyle, and so on:

<Nav
  cta={{ text: "Buy the book!", href: "https://url.to/buy-my-book" }}
  ctaStyle={{ color: "red" }}
  ctaOnClick={() => alert("Thanks for buying the book!")}
  menuItems={[
    { text: "Home", href: "/home" },
    { text: "About", href: "/about" },
    { text: "Contact", href: "/contact" },
  ]}
  menuItemStyle={{ color: "blue" }}
  onMenuItemClick={(href) => alert(`Navigating to ${href}`)}
  title="My Site"
  titleStyle={{ color: "green" }}
/>

Let's try a different approach. One that resembles how HTML works and that is supported out-of-the-box by React.

Using `children` and dedicated components

<Nav>
  <Nav.Title>My Site</Nav.Title>

  <Nav.Menu>
    <Nav.Menu.Item href="/">Home</Nav.Menu.Item>
    <Nav.Menu.Item href="/about">About</Nav.Menu.Item>
    <Nav.Menu.Item href="/contact">Contact</Nav.Menu.Item>
  </Nav.Menu>

  <Nav.CallToAction href="https://url.to/buy-my-book">
    Buy the book!
  </Nav.CallToAction>
</Nav>

If you have done some React development, you probably know the children prop is how React passes content down to components (for example <p>Hola</p>, where p is the component, and Hola is the value of the children prop).

The example above uses children and composition extensively to render the desired UI. Instead of passing multiple props to the Nav component, we create many small, dedicated components which may of course receive their own props.

As a result, this approach gives us a much more flexible and idiomatic API. If we later need to add additional elements to the Nav component, we can do so without changing the Nav component at all (following the Open-Closed design principle).

On the other hand, using this technique comes with some drawbacks worth mentioning:

We have to make it clear that these dedicated components are only meant to be used as children of the Nav component. We can do this by using the Nav namespace, for example: Nav.Title, Nav.Menu, and Nav.CallToAction.
We must ensure the Nav component is flexible enough to handle the different cases we might want to render. For example, if we want to make it possible to render the Nav.Menu component either after or before the Nav.CallToAction component, the styles should be sufficiently sophisticated to handle both cases.

Possible implementation

Pay attention to how we export the Nav component and its dedicated components. That’s the secret sauce to namespace them and make it clear they are only meant to be used as children of the Nav component.

const Nav = ({ children }) => {
  return <nav>{children}</nav>;
};

const CallToAction = ({ children, href }) => {
  return <a href={href}>{children}</a>;
};

const Menu = ({ children }) => {
  return <ul>{children}</ul>;
};

const MenuItem = ({ children, href }) => {
  return (
    <li>
      <a href={href}>{children}</a>
    </li>
  );
};

const Title = ({ children }) => {
  return <h1>{children}</h1>;
};

Menu.Item = MenuItem;

Nav.CallToAction = CallToAction;
Nav.Menu = Menu;
Nav.Title = Title;

export { Nav };

Notes

A few weeks after starting to write this post, I received a newsletter from Kent C. Dodds featuring a React article. Coincidentally, the content of the post covered precisely this! So, digging a little more, I found this pattern had been documented since a few years ago (watch out this video talk from Ryan Florence at Phoenix ReactJS Conf in 2017), and it is called Compound components.
Radix UI uses this pattern extensively.
If you’re curious, I used this pattern to build the whole landing page for my tddworkshop.com page. You can check the source code here.

Happy hacking!

Ready to keep the conversation going? Let's connect on Twitter and continue the discussion!

Using the Builder pattern for creating test data with ease

Sergio — Fri, 25 Nov 2022 18:40:09 +0000

If you have yet to hear about [software] design patterns, you may think of them as reusable solutions for everyday problems that work for different contexts. Of course, new design patterns appear now and then, but there is a well-documented core of patterns that are popular and can be seen in many object-oriented code bases. The Builder pattern is one of them.

Although this pattern may come in handy in multiple situations, it is especially helpful when creating test data. Tests for any medium-large-sized applications often require us to create various objects, put them in a particular state, and have relationships with other entities. That can be hard to do, especially if the objects are complex and we need to create many of them. The Builder pattern offers a solution to use a more semantic, domain-specific interface that makes the process easier.

For example, imagine we are coding a software system to help manage an automobile repair shop. Not surprisingly, we may find mechanics and cars. Mechanics can be responsible for multiple vehicles, be on holiday, and have different hourly salaries. The following tests verify that we cannot assign a car to a mechanic under certain circumstances.

import { Car, Mechanic } from "@domain";

describe("POST /mechanics/{id}/cars", () => {
  it("does not add a new car if the mechanic is on holiday", async () => {
    const mechanic = new Mechanic({
      id: 1,
      name: "Alice",
    });

    const today = new Date();

    const pto = new Pto({
      mechanic,
      startDate: startOfDay(today),
      endDate: endOfDay(today),
    });

    mechanic.ptos = [pto];

    await mechanicRepository.save(mechanic);

    const car = new Car({
      id: 1,
      make: "Mazda",
      model: "Mazda 3",
      year: 2021,
    });

    await carRepository.save(car);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });

  it("does not add a new car if the mechanic is working on five cars already", async () => {
    const mechanic = new Mechanic({ id: 1, name: "Alice" });

    mechanic.cars = [
      new Car({
        id: 1,
        make: "Mazda",
        model: "Mazda 2",
        year: 2021,
      }),
      new Car({
        id: 2,
        make: "Mazda",
        model: "Mazda 3",
        year: 2021,
      }),
      new Car({
        id: 3,
        make: "Mazda",
        model: "CX-30",
        year: 2021,
      }),
      new Car({
        id: 4,
        make: "Mazda",
        model: "MX-5",
        year: 2021,
      }),
      new Car({
        id: 5,
        make: "Mazda",
        model: "CX-60",
        year: 2021,
      }),
    ];

    await mechanicRepository.save(mechanic);

    const car = new Car({
      id: 6,
      make: "Mazda",
      model: "CX-9",
      year: 2021,
    });

    await carRepository.save(car);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });
});

As you may see in the code block above, creating all these objects by hand is expensive and makes the whole test hard to read. Let’s try instead to use a MechanicBuilder that makes the process easier while producing the same result.

import { MechanicBuilder, CarBuilder } from "@test/builders";

describe("POST /mechanics/{id}/cars", () => {
  it("does not add a new car if the mechanic is on holiday", async () => {
    const mechanic = await new MechanicBuilder()
      .onHoliday()
      .save(mechanicRepository);

    const car = await new CarBuilder().save(carRepository);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });

  it("does not add a new car if the mechanic is working on five cars already", async () => {
    const mechanic = await new MechanicBuilder()
      .withCars(5)
      .save(mechanicRepository);

    const car = await new CarBuilder().save(carRepository);

    const response = await request(app)
      .post(`/mechanics/${mechanic.id}/cars`)
      .send({ carId: car.id });

    expect(response.status).toBe(400);
  });
});

Reading the code above, we can clearly see the scenario we are creating for the test. The builder reduces verbosity and makes the code more expressive while favoring reusability for other test cases. Of course, we may keep adding methods to the MechanicBuilder as new requirements appear, so we always have an up-to-date, semantic interface to create Mechanic objects (and the same applies for Car instances).

Example of a Builder implementation using TypeScript

Wondering how you can create that fancy builder above using TypeScript? 😏 As with many things in software development, different paths may lead to the same result, but this approach worked very well for me in the past.

The Builder pattern is considered a creational pattern since it helps us create objects by removing all the complexity to instantiate them. So let’s start by creating a generic Builder<T> interface that defines the two methods all builders should implement: build (to return the object) and save (to persist the object in the database). I usually add a third method, with, that would allow us to pass an object with the properties we want to override. Still, for the sake of simplicity, I will skip it in this example.

export interface Builder<T> {
  build(): T;
  save(repository: Repository<T>): Promise<T>;
}

Then, we may create a BaseBuilder<T> abstract class that implements the Builder<T> interface and provides a default implementation for both methods. The build method will return the object, while the save method will return the object and persist it in the database. Here, we use inheritance just for code reusability.

import { Builder } from "@test/builders";

export abstract class BaseBuilder<T> implements Builder<T> {
  protected abstract entity: T;

  public build(): T {
    return this.entity;
  }

  public save(repository: Repository<T>): Promise<T> {
    return repository.save(this.entity);
  }
}

Finally, we can create the MechanicBuilder simply by extending
BaseBuilder<Mechanic> and providing all the additional methods.

import { Mechanic } from "@domain";
import { BaseBuilder, CarBuilder, PtoBuilder } from "@test/builders";

export class MechanicBuilder extends BaseBuilder<Mechanic> {
  protected entity: Mechanic;

  constructor() {
    super();

    this.entity = new Mechanic({ id: 1, name: "Alice" });
  }

  public onHoliday(): this {
    this.entity.ptos = [
      new PtoBuilder().for(this.entity).on(new Date()).build(),
    ];

    return this;
  }

  public withCars(count: number): this {
    this.entity.cars = new Array(count)
      .fill(null)
      .map(() => new CarBuilder().build());

    return this;
  }
}

Note how we return this in the onHoliday and withCars methods. That is the secret sauce to making the Builder provide a fluent interface so that we can use it in the following way:

const mechanic = await new MechanicBuilder()
  .onHoliday()
  .withCars(5)
  .save(mechanicRepository);

Happy hacking!

DEV Community: Sergio

Uncovering and conquering async bugs: A trick to testing undesired effects

React: Using children instead of dedicated render slots

Using children and dedicated components

Possible implementation

Notes

Using the Builder pattern for creating test data with ease

Example of a Builder implementation using TypeScript

Using `children` and dedicated components