DEV Community: João Forja 💭

How to write fewer tests but find more bugs

João Forja 💭 — Sat, 18 Sep 2021 16:13:44 +0000

How in general should I know what to test?

Whenever we're deciding how to test a component, the main challenge is choosing which tests to write. That's because even a simple function like add(a: number, b: number) has a potentially infinite number of input values it can receive. And since we have limited time and budget we can't do them all. Thus we need to be able to choose a small number of inputs, out of all the possible inputs, that will reveal as many bugs as possible.

To solve this issue, I've been using an approach that combines Input Space Partitioning and Whitebox testing.

Input space partitioning

To put it simply, the idea behind Input Space Partitioning is that by analyzing the desired outputs of a piece of code, we can group its inputs such that if the code works for an input of a group, it will also work for any input of that same group. Therefore, we only need to write one test for each group.

Note that inputs include everything that affects the behavior of a component (e.g. props, user action, API response values, etc...), and outputs everything it produces (e.g. rendered elements, API requests, values persisted to storage, etc...).

Take as an example a FizzBuzz inspired React component. The component should allow users to type numbers. When given a number that's a multiple of 3 the component should show Fizz, a number multiple of 5 should show Buzz, a number multiple of 3 and 5 should show FizzBuzz, and a number that's multiple of neither 3 or 5 shows the given number.

Number	Renders
Multiple of 3 and not 5	"Fizz"
Multiple of 5 and not 3	"Buzz"
Multiple of 3 and 5	"FizzBuzz"
Multiple of neither 3 or 5	Given number

Following the logic of Input Space Partitioning, the FizzBuzz input domain can be split into four different categories which are represented by the left column of the table above. This means that we only need to write four tests, one for each of the input categories.

WhiteBox testing

You might be wondering how can we be sure, just by looking at the description of the behavior of the FizzBuzz component, that we've chosen the minimal amount of tests that will reveal as many bugs as possible. The answer is we can't. And that's why we also rely on Whitebox testing.

Whitebox testing, in this context, means we'll use the knowledge of how a component is implemented to decide which tests to write. By looking at the implementation, we can have a better idea of what bugs we might have and thus allow us to choose tests more cost-effectively.

Example 1 - Implementation matches the Input Space Partitioning analysis

If the FizzBuzz code is written as follows, then for each input category, we only need to write one test assertion.

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    if (number % 3 === 0 && number % 5 === 0) return "FizzBuzz"
    if (number % 3 === 0) return "Fizz"
    if (number % 5 === 0) return "Buzz"
    return number
  }

  return (
    <>
      <label htmlFor="fizzBuzz">Enter a FizzBuzz number:</label>
      <input
        type="number"
        id="fizzBuzz"
        name="fizzBuzz"
        value={value}
        onChange={e => setValue(Number(e.target.value))}
      />
      <p>{fizzBuzz(value)}</p>
    </>
  )
}

The corresponding tests for this implementation would be as follows:

test.each`
  number  | result        | description
  ${"15"} | ${"FizzBuzz"} | ${"Multiples of 3 and 5"}
  ${"6"}  | ${"Fizz"}     | ${"Multiples of 3 but not 5"}
  ${"10"} | ${"Buzz"}     | ${"Multiples of 5 but not 3"}
  ${"7"}  | ${"7"}        | ${"Multiples of neither 3 or 5"}
`("$description - $number", ({ number, result }) => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), number)
  expect(screen.getByText(result)).toBeVisible()
})

We don't need to write more than one assertion per input domain because with just one assertion we cover all the input domains we determined in the Input Space Analysis, and we cover all the relevant code branches.

Example 2 - Implementation has more branches than Input Partitions

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    if (number === 1) return "1"
    if (number === 2) return "2"
    if (number % 3 === 0 && number % 5 === 0) return "FizzBuzz"
    if (number % 3 === 0) return "Fizz"
    if (number % 5 === 0) return "Buzz"
    return number
  }

  return // rest as it was...
}

If we're given an implementation like the one above, then one test assertion per input domain won't be enough, since the first two branches of the fizzBuzz function won't be covered. So we'll need to adjust the test assertions so we cover everything in the Multiples of neither 3 or 5 partition.

test.each`
  number  | result        | description
  ${"15"} | ${"FizzBuzz"} | ${"Multiples of 3 and 5"}
  ${"6"}  | ${"Fizz"}     | ${"Multiples of 3 but not 5"}
  ${"10"} | ${"Buzz"}     | ${"Multiples of 5 but not 3"}
  ${"7"}  | ${"7"}        | ${"Multiples of neither 3 or 5"}
  ${"1"}  | ${"1"}        | ${"Multiples of neither 3 or 5 - special case 1"}
  ${"2"}  | ${"2"}        | ${"Multiples of neither 3 or 5 - special case 2"}
`("$description - $number", ({ number, result }) => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), number)
  expect(screen.getByText(result)).toBeVisible()
})

One might argue that those first two assertions are simple enough that they're obviously correct and thus not worth testing. That's a fair observation and one of the advantages of this way of testing is exactly that we can take the implementation into account to write fewer tests. I'd still argue that it's a good principle to have every bit of code run at least once during tests, but I wouldn't reject a PR due to this.

In case you're wondering, changing fizzBuzz so we only need one assertion per test is an option. So if you're ever in a situation like this, take the opportunity and try to simplify the code.

Example 3 - Implementation uses a production-grade library

Imagine this implementation that uses a library underneath that's been battle-tested. Which tests should we write for it?

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    return battleTestedFizzBuzz(number)
  }

  return // rest as it was...
}

I'd argue we only need one. Since the underlying library gives us confidence that the FizzBuzz logic works as expected, and the React-specific code is straightforward, just one test to see that the code runs should be enough.

test("Runs as expected", () => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), "15")
  expect(screen.getByText("FizzBuzz")).toBeVisible()
})

Example 4 - Really complex implementation

To finish these examples, take a look at the project FizzBuzzEnterpriseEdition. Imagine that somehow the React component communicated with a running instance of that project to know what it should show the user based on its input. What tests would you write for it?

My answer is that I don't know. Aside from picking one test assertion per partition determined in the Input Space Analysis, I have no idea what other inputs to pick. The code is so complex that it hides the bugs it might have.

All of these examples give us an interesting insight. The harder the code is to understand, the more test we'll have to write to be confident it works. Therefore, having a clear logic for what we're implementing is essential to enable effective testing.

Put it into action

If you were not familiar with any of the ideas in this article, this can be a lot to process. So here's a summary of how you can put these ideas into practice next time you have to test a component.

Start by explicitly defining the behavior of the component.
Make sure that for every possible input you know what the output should be.
Partition the inputs based on the characteristics of the produced outputs.
Look at the implementation of the component.
Verify if one test per input partition is enough or too much.
Write the tests.

Would you like to see a more complex example?

I wrote a follow-up article to this one where I go over a more complex component and test it using the methodology described in this article. It is available for subscribers of my newsletter. So if you'd like to see it, be sure to subscribe here.

Don't know what to test in your React components? Learn Input Space Partitioning and Whitebox testing

João Forja 💭 — Sat, 18 Sep 2021 12:27:25 +0000

How in general should I know what to test?

To solve this issue, I've been using an approach that combines Input Space Partitioning and Whitebox testing.

Input space partitioning

Number	Renders
Multiple of 3 and not 5	"Fizz"
Multiple of 5 and not 3	"Buzz"
Multiple of 3 and 5	"FizzBuzz"
Multiple of neither 3 or 5	Given number

WhiteBox testing

Example 1 - Implementation matches the Input Space Partitioning analysis

If the FizzBuzz code is written as follows, then for each input category, we only need to write one test assertion.

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    if (number % 3 === 0 && number % 5 === 0) return "FizzBuzz"
    if (number % 3 === 0) return "Fizz"
    if (number % 5 === 0) return "Buzz"
    return number
  }

  return (
    <>
      <label htmlFor="fizzBuzz">Enter a FizzBuzz number:</label>
      <input
        type="number"
        id="fizzBuzz"
        name="fizzBuzz"
        value={value}
        onChange={e => setValue(Number(e.target.value))}
      />
      <p>{fizzBuzz(value)}</p>
    </>
  )
}

The corresponding tests for this implementation would be as follows:

test.each`
  number  | result        | description
  ${"15"} | ${"FizzBuzz"} | ${"Multiples of 3 and 5"}
  ${"6"}  | ${"Fizz"}     | ${"Multiples of 3 but not 5"}
  ${"10"} | ${"Buzz"}     | ${"Multiples of 5 but not 3"}
  ${"7"}  | ${"7"}        | ${"Multiples of neither 3 or 5"}
`("$description - $number", ({ number, result }) => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), number)
  expect(screen.getByText(result)).toBeVisible()
})

Example 2 - Implementation has more branches than Input Partitions

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    if (number === 1) return "1"
    if (number === 2) return "2"
    if (number % 3 === 0 && number % 5 === 0) return "FizzBuzz"
    if (number % 3 === 0) return "Fizz"
    if (number % 5 === 0) return "Buzz"
    return number
  }

  return // rest as it was...
}

test.each`
  number  | result        | description
  ${"15"} | ${"FizzBuzz"} | ${"Multiples of 3 and 5"}
  ${"6"}  | ${"Fizz"}     | ${"Multiples of 3 but not 5"}
  ${"10"} | ${"Buzz"}     | ${"Multiples of 5 but not 3"}
  ${"7"}  | ${"7"}        | ${"Multiples of neither 3 or 5"}
  ${"1"}  | ${"1"}        | ${"Multiples of neither 3 or 5 - special case 1"}
  ${"2"}  | ${"2"}        | ${"Multiples of neither 3 or 5 - special case 2"}
`("$description - $number", ({ number, result }) => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), number)
  expect(screen.getByText(result)).toBeVisible()
})

In case you're wondering, changing fizzBuzz so we only need one assertion per test is an option. So if you're ever in a situation like this, take the opportunity and try to simplify the code.

Example 3 - Implementation uses a production-grade library

Imagine this implementation that uses a library underneath that's been battle-tested. Which tests should we write for it?

function FizzBuzz() {
  const [value, setValue] = useState(1)

  function fizzBuzz(number: number) {
    return battleTestedFizzBuzz(number)
  }

  return // rest as it was...
}

test("Runs as expected", () => {
  render(<FizzBuzz />)
  userEvent.type(screen.getByLabelText("Enter a FizzBuzz number:"), "15")
  expect(screen.getByText("FizzBuzz")).toBeVisible()
})

Example 4 - Really complex implementation

Put it into action

If you were not familiar with any of the ideas in this article, this can be a lot to process. So here's a summary of how you can put these ideas into practice next time you have to test a component.

Start by explicitly defining the behavior of the component.
Make sure that for every possible input you know what the output should be.
Partition the inputs based on the characteristics of the produced outputs.
Look at the implementation of the component.
Verify if one test per input partition is enough or too much.
Write the tests.

Would you like to see a more complex example?

Guidelines (from the 1970s!) on How to Split Your React Components

João Forja 💭 — Tue, 31 Aug 2021 20:10:19 +0000

Are there particular guidelines to follow when deciding how to split a React component?

Deciding how to break a component into sub-components isn't easy and is a challenge that isn't specific to React. This is fortunate since it means we can go outside React's ecosystem and get some ideas on how to do it.

In this article, I'll present a guideline to validate ideas on splitting a React component to increase code reuse and reduce maintenance costs. This guideline comes from the paper "Designing Software for Ease of Extension and Contraction" written in 1979 by David Parnas.

To paraphrase Parnas:

Component A is allowed to use component B when all the following conditions
are met:

A is essentially simpler because it uses B.

B is not substantially more complex because it is not allowed to use A.

There is a useful subset containing B but not A.

There is no conceivable useful subset containing A but not B.

Let's clarify a bit each of the criteria:

Since A will become simpler to implement because it uses B, that relationship makes sense to exist.
We want to avoid cyclic dependencies for all the known reasons, and we also want to keep our components as simple as possible. Situations where two components benefit from using each other, hint that the decomposition needs some rework.
It only makes sense for B to exist without A if component B is useful to other components besides A.
An implementation of A that doesn't have the functionality provided by B doesn't make sense.

For the context of this article, we can consider that the term "use" means to allow a component to reference another one in the code. In truth, it is more nuanced than that, but I won't get into that in this article.

To make this all concrete, let's look at a Video Player component as an example.

The requirements for the Video Player are:

Optimized for videos with a 16:9 aspect ratio.
Supports play and pause any time during the video.
Allows for quick navigation to any part of the video.
Supports mute and unmute.
Has full-screen support.

Valid decomposition

By looking at the requirements and the mockup, one way to split the component would be:

As shown above, VideoPlayer can be decomposed into 4 different components: AspectRatioBox, SliderInput, Button, and Icons. This is not an exhaustive decomposition, but for the purpose of this article, it should be enough.

Let's go over AspectRatioBox and see if it should be its own component according to the guideline.

VideoPlayer is essentially simpler because it uses AspectRatioBox.

If VideoPlayer didn't use AspectRatioBox it would have to implement that functionality itself, which would make it more complex than if it used AspectRatioBox.

AspectRatioBox isn't substantially more complex because it can't use VideoPlayer.

There's no scenario in which AspectRatioBox would benefit from using VideoPlayer, therefore prohibiting it from using the VideoPlayer won't affect its complexity.

There is a useful subset containing an AspectRatioBox but not a VideoPlayer.

Any time we need to define an element's aspect ratio, the AspectRatioBox will be useful. Hero Images with a background and a grid/list of thumbnails are examples of other situations where the AspectRatioBox would be useful.

There is no conceivable useful subset containing VideoPlayer but not AspectRatioBox box.

Given the requirements for VideoPlayer, I don't see how it could be implemented without the behavior that AspectRatioBox provides.

There will be situations where it isn't obvious if some of the above criteria hold up before starting the implementation. The same can be said about figuring out how to split a component. My suggestion is to first come up with a rough idea on how to split the component, follow it, and keep re-evaluating it as the implementation progresses.

Invalid decomposition

Let's try a slightly different split and see how it holds up:

We've added an ActionsBar component that contains all the actions a user can do. It is supposed to be a simple UI component that receives callbacks for when the user clicks on the buttons. Let's analyze how it holds up:

VideoPlayer is essentially simpler because it uses ActionsBar.

This one I'm not entirely sure about. ActionsBar would have to receive a lot of callbacks from VideoPlayer would they be separate components, and that could end up resulting in more code cognitive load as we'd be forced to create all of those callbacks and pass them around. If I were to make this separation between VideoPlayer and ActionsBar, I'd keep an eye out during implementation for whether VideoPlayer was simpler because it used ActionsBar or not.

ActionsBar isn't substantially more complex because it can't use the VideoPlayer.

There's no scenario in which ActionsBar would benefit from using VideoPlayer, thus prohibiting it from using the VideoPlayer won't be an issue.

There is a useful subset containing ActionBar but not a VideoPlayer.

I'd argue that there isn't. The visuals and actions provided by ActionsBar are really specific to VideoPlayer.

There is no conceivable useful subset containing VideoPlayer but not ActionsBar.

Given the requirements for VideoPlayer, it will always need to have the behavior and UI provided by ActionsBar.

As we've seen, ActionsBar is not a good candidate for a component that should exist by itself due to how specific it is to VideoPlayer. Therefore, this decomposition wouldn't likely be one I'd do, and I'd have the behavior and UI given by the ActionsBar be part of VideoPlayer.

Further notes

In this example, the decomposition was done in terms of UI components, but the same guideline applies to any piece of code that could live in isolation (e.g. hooks, functions, etc).

As a component evolves and gets added functionalities, the initial decomposition will get outdated and we'll have to think of a new one. Hopefully, with this approach, we should still be able to reuse many of the components we initially had.

This guideline aims at splitting a component into multiple ones that can be reused across the same or different applications. Inside the component itself, we may still opt to split it further for other reasons such as improving performance.

Give it a try

Next time you're developing a new component try to use this guideline to decompose it into reusable pieces.

A is essentially simpler because it uses B
B is not substantially more complex because it is not allowed to use A
There is a useful subset containing B but not A
There is no conceivable useful subset containing A but not B

I'd suggest coming up with a decomposition before starting to code, and as you go on and learn more about the component you're writing, adjust the decomposition accordingly.

Also, keep in mind that you're the only person that knows the context you're in. So don't follow the guideline blindly and check that it makes sense in the context you're in.

Did you enjoy this article? Then you might want to subscribe to my newsletter to be notified whenever new content comes out.

Improve your skills by practicing in real-world projects

João Forja 💭 — Sun, 10 Jan 2021 13:50:46 +0000

If you're at that stage of your journey where you can build a simple project from scratch, but you're not sure you're capable of working in an existing codebase, this article might help you.

In this article, I'll show an approach that gets you experience working on existing codebases, while still providing a fallback if things get too hard.

Overview

The approach can be summarized by the following steps:

Find an open-source project on Github that uses the technologies you use and that interest you.
Go through the list of merged pull requests and find one related to a new feature or a bug fix. Be careful not to start with overly complex ones. The number of lines of code changed is a good indicator.
Clone the repository from which the PR originated.
Checkout into the commit previous to the first commit of the PR. You are now looking at the codebase the contributor was looking at before starting to work.
Implement the feature or fix of the PR you chose.

If you ever get lost, you can always look at PR to have an idea of what you have to do.

Also, be sure to read the issue(s) associated with the PR. There you'll find the requirements of what you need to implement.

Another benefit of this approach is it will make you accustomed to the architecture of the project. Which will make it much easier for you to one day contribute to it.

Let's look at an example of how this would work in practice.

Example

To exemplify, I'll use a PR I've submitted a while ago to Excalidraw.

We start by cloning the repository the PR comes from:

git clone ttps://github.com/Jnforja/excalidraw.git && cd excalidraw

Then we find and copy the id of the first commit of the PR.

To do that we go to the PR page on Github, click on the commits tab, and copy the id of the oldest commit.

Then we checkout into the first commit:

git checkout -b new-branch 7b5fc6b8162b5e0d387093dfdc48225572656c73

All that's left is to go to the commit previous to the first one:

git reset HEAD~1 && git stash

You're now ready to start coding.

I hope this technique is useful to you and that you use it to learn something new.

Enjoyed this article? Then consider following me on Twitter.

Testing and developing with React and TS: Data structures (part 1)

João Forja 💭 — Tue, 29 Dec 2020 17:49:35 +0000

With this series, I hope to share ideas on developing React components that are safer from bugs and easier to maintain.

To explain and exemplify the principles involved, we'll be building a Multilevel-list. We'll go from requirements to a fully functional React component. Along the way, we'll touch on the topics of:

Using TypeScript to:
1. Prevent bugs
2. Make code safer to change
Designing data structures to reduce possible bugs
Structuring components for testability
What tests to write and at what level

Requirements

Our Multilevel-list component has the following requirements:

Show items content
Collapse sub-lists of items
Expand sub-lists of items
Accessible to key-board users

Before we go on, it's important to keep in mind the role and limitations of requirements.

Requirements exist to form an understanding between clients and developers on what we want to build. We know both parties are aligned enough to start development if they can come up with acceptance tests to verify the requirements.

In this context, an acceptance test doesn't imply an automated test. It can be a simple sentence about the system that we can say it's true or false. For example, an acceptance test to verify the requirement "Accessible to keyboard users" could be "We can collapse or expand any sub-list using only the keyboard".

Requirements won't fully specify the software behavior, meaning there will be a margin for interpretation. For example, for "Accessible to keyboard users" we could implement navigation with keyboard arrows or tabs. We make these decisions by using our experience and talking with the client if it impacts the business.

Defining the views

After looking at the requirements, we come up with some sketches of the component.

Through the sketches, we can start to decompose the component into views.

I suggest we model the Multilevel-list around two entities: lists and items. A list can either be empty or populated with items. An item can either be open, closed, or empty. Open items show populated lists.

In all, we decomposed the component into the below five views:

Designing the data structure

Now that we've defined the views and know the requirements, we can work on a data structure to support the component.

There are multiple concerns when designing a data structure besides fulfilling behavioral requirements. Required memory, ease of manipulation, and operations performance are some of them. In this article, we'll focus on reducing the space of invalid representations and having a 1 to 1 mapping between types and views. These concerns will minimize the chances for bugs and make the code easier to maintain.

As we've seen earlier, a list can either be empty or populated. An empty list has no items associated, and a populated list has at least one.
We can represent those invariants as follows:

type MultiLevelList = EmptyList | PopulatedList
type EmptyList = []
type PopulatedList = NonEmptyArray<Item>
type NonEmptyArray<T> = [T, ...T[]]

An item is either empty, opened, or closed. All items have content that's text. Empty items don't have a populated list of items, while closed and open items do.

type Item = OpenItem | ClosedItem | EmptyItem
type OpenItem = {
  id: string
  content: string
  state: "OPEN"
  children: PopulatedList
}
type ClosedItem = {
  id: string
  content: string
  state: "CLOSED"
  children: PopulatedList
}
type EmptyItem = {
  id: string
  content: string
  state: "EMPTY"
}
// Note: Although not influencing any view,
//  we'll need the id's to render the items using React.

Invalid states

Notice how there's very little room to represent an invalid state of a Multilevel-list. Compare it with the type below that we could also use to represent an Item:

type Item = {
  id: string
  content: string
  isOpen: boolean
  isClosed: boolean
  isEmpty: boolean
  children?: PopulatedList
}

This structure of Item gives much more margin to represent invalid states. It allows some invariants of Item to be violated, which previously couldn't. For example, it's now possible to describe an item that's simultaneously open and closed. Another example would be an open item that doesn't have an associated list.

Invalid states are a huge source of bugs. If we can structure our data to make those states impossible and rely on a type checker to enforce them, we will:

Reduce possible bugs
Make code easier to understand
Save lines of code spent on code to deal with inconsistent states

Overall, we'll bring down the development and maintenance costs.

1 Type to 1 View

Currently, we have a 1 view to 1 type relation. This allows, when rendering, to code branch over types instead of conditions. This approach's advantage is that now we can rely on TypeScript's exhaustive checking to tell us if we handled all possible views at compile-time.

Following this approach and given the current types, the rendering code will follow the pattern below:

if (isEmptyList(list)) {
    return <div>/*render empty list*/</div>;
  }
if (isPopulatedList(list)) {
    return <div>/*render populated list*/</div>;
}
assertNever(list);
// isEmptyList() and isPopulatedList() are type guards

...

switch (item.state) {
  case "OPEN":
    return <div>/*render open item*/</div>
  case "CLOSED":
    return <div>/*render closed item*/</div>
  case "EMPTY":
    return <div>/*render empty item*/</div>
  default:
    return assertNever(item)
}

function assertNever(x: never): never {
  throw new Error("Unexpected object: " + x)
}

Exhaustive checking might not seem a big deal when we've just written the code. However, as time goes by and code changes, we'll introduce new types. Forgetting, or not knowing, that there's code we need to update to handle the new type is likely. With exhaustive checking that's not a problem, the compiler will tell us where we have to make changes.

If you want to know more about exhaustive checking and how the compile error happens, you can check the documentation.

Still room for invalid states?

You may have noticed that it's still possible to represent some invalid states with the current data structure. In specific, a Multilevel-list can contain the same item twice. This shouldn't happen as it will cause bugs. However, there's no way to enforce this restriction at compile-time. In these situations, it's important to find other options to make the restriction explicit. Documentation is one way to do it.

Taking all into consideration, we end up with the following:

/*
 * Invariants:
 *  There shouldn't be repeated Items
 */
type MultiLevelList = EmptyList | PopulatedList
type EmptyList = []
type PopulatedList = NonEmptyArray<Item>
type NonEmptyArray<T> = [T, ...T[]]

type Item = OpenItem | ClosedItem | EmptyItem
type OpenItem = {
  id: string
  content: string
  state: "OPEN"
  children: PopulatedList
}
type ClosedItem = {
  id: string
  content: string
  state: "CLOSED"
  children: PopulatedList
}
type EmptyItem = {
  id: string
  content: string
  state: "EMPTY"
}

// Type guards. Necessary to distinguish between types.
function isPopulatedList(list: MultiLevelList): list is PopulatedList {
  return list.length > 0
}
function isEmptyList(list: MultiLevelList): list is EmptyList {
  return list.length === 0
}

Next Steps

In the next article, we'll look at how to structure our multilevel-list component to be easy to test and what tests to write.

Enjoyed this article? Then follow me on Twitter. I tweet about what I believe it's essential to be a great software developer.

Unsure of what tests to write? Here's what that might mean.

João Forja 💭 — Mon, 17 Aug 2020 12:16:37 +0000

When we're unsure of what to test, the project might be at risk of failure.

Tests turn our client's ideas into unequivocal specifications. They make the bridge between what's on a customer's head and what we need to build. If we can't write tests, we're lost on what we need to program.

That's a fast track to disaster.

We might think it's the client's fault. After all, we're unable to write tests because requirements are vague and volatile.

But pointing fingers never solved any problems.

So what can we do?

A really effective strategy is to reduce the scope of the current release.

Smaller deliverables mitigate two common reasons for failure to clarify what software should do:

Trying to discuss too many features at once.
Insecurity on what the application has to offer to succeed.

A narrower scope means we have less to focus on at once. So there's more time and energy to dig deeper and define concrete requirements to guide our acceptance tests.

With less to develop, we can ship faster. Thus, get feedback from the market sooner. That will shed light on what the app should do to satisfy users.

As programmers, it's easy to disregard deliverables as a project manager's responsibility.

However, it's we that find gaps in the specifications. If we stay silent, no one will know misunderstandings exist until the project is delivered.

That may be too late.

Even when we believe management will turn a deaf ear, let's speak up. We might end up saving the project.

Enjoyed this article? Then follow me on twitter. I tweet about what I believe it's essential to be a great software developer.

What made you interested in learning how to write tests or how to TDD?

João Forja 💭 — Sat, 01 Aug 2020 21:57:56 +0000

I got interested in learning how to TDD and how to write tests because I wanted to improve my overall skills as a developer.

I had this idea that there are too many technologies, and they change so fast that I can't learn all of them in-depth, so my countermeasure was to improve my testing skills. Tests will tell me if what I'm building is working or not. They will also give me feedback on the design of what I'm building. And all of this independently of the frameworks/tools I'm using. So even when I have to dig in a codebase that uses technologies that I'm not so familiar with, I'm always reasonably confident that by writing tests and by reading the technologies' documentation, that I can get productive pretty quickly.

What about you? What made you interested in learning how to write or learning how to TDD?

5 steps to perform a search when user stops typing using React + Hooks in a controlled component

João Forja 💭 — Sat, 18 Jul 2020 16:03:23 +0000

I need to perform a search when the user stops typing. But with React I can't find how it works!

It's a common use-case to want to perform a search after the user stops typing. This way the user doesn't have to manually click on a button to get feedback from his actions. Despite being a simple use-case to understand, it can present some challenges when trying to implement it with React.

To illustrate the problem and the solution, I'll use a simple React app that makes requests to the Hacker News API based on the values of an input field. For this solution, we'll be using a controlled input and useEffect hook.

As a starting point, we might have something like the code below:

import React, { useState, useEffect, useReducer } from "react"
import axios from "axios"

function fetchReducer(state, action) {
  switch (action.type) {
    case "FETCH_START":
      return {
        ...state,
        isLoading: true,
        hasError: false,
      }
    case "FETCH_SUCCESS":
      return {
        ...state,
        isLoading: false,
        hasError: false,
        hits: action.payload,
      }
    case "FETCH_FAILURE":
      return {
        ...state,
        isLoading: false,
        hasError: true,
      }
    default:
      throw new Error()
  }
}

async function fetchHits(query, dispatch) {
  dispatch({ type: "FETCH_START" })
  try {
    const result = await axios(
      `https://hn.algolia.com/api/v1/search?query=${query}`
    )
    dispatch({ type: "FETCH_SUCCESS", payload: result.data.hits })
  } catch (err) {
    dispatch({ type: "FETCH_FAILURE" })
  }
}

function App() {
  const [{ hits, hasError, isLoading }, dispatch] = useReducer(fetchReducer, {
    hits: [],
    isLoading: true,
    hasError: false,
  })
  const [query, setQuery] = useState("react")

  useEffect(() => {
    fetchHits(query, dispatch)
  }, [query])

  return (
    <>
      <input
        type="text"
        value={query}
        onChange={event => setQuery(event.target.value)}
      />
      {hasError && <div>Something went wrong ...</div>}
      {isLoading ? (
        <div>Loading ...</div>
      ) : (
        <ul>
          {hits.map(item => (
            <li key={item.objectID}>
              <a href={item.url}>{item.title}</a>
            </li>
          ))}
        </ul>
      )}
    </>
  )
}
export default App

1. Apply debounce

Since we're using the onChange event handler to trigger calls to setQuery, and given query is a useEffect dependency, for every character the user changes on the input the process of fetching data will be started. As we only want to start fetching data some time after the user has stopped typing, we are going to debounce fetchHits().

Given that correctly writing a debounce function can be a hard task, we'll be using the debounce() function from Lodash.
A first try might look like this:

function App() {
  const [{ hits, hasError, isLoading }, dispatch] = useReducer(fetchReducer, {
    hits: [],
    isLoading: true,
    hasError: false,
  })
  const [query, setQuery] = useState("react")

  useEffect(() => {
    _.debounce(() => fetchHits(query, dispatch), 500)()
  }, [query])

  return <>...</>
}

If you run the new version of the code, you'll notice that although there is a delay between the user typing and fetchHits() being called, there's still going to be one call every time the user types something. Even though we've debounced fetchHits(), we're not using the same debounced function on every render of the component. A new debounced version of fetchHits() is being created every time useEffect runs. In order for this solution to work, we need to guarantee that it's always the same debounced function that is called for the lifetime of the component.

2. Keep the identity of the debounced function

To keep the identity of the function through the lifetime of the component, we'll be using the useRef hook.

At first, it might seem like a good idea to use the useCallback or useMemo hooks. However, those hooks do not guarantee the identity of the value given to them across all renders, which might lead to hard to track bugs in our case.

function App() {
  const [{ hits, hasError, isLoading }, dispatch] = useReducer(fetchReducer, {
    hits: [],
    isLoading: true,
    hasError: false,
  })
  const [query, setQuery] = useState("react")
  const debouncedFetchHits = useRef(
    _.debounce(query => fetchHits(query, dispatch), 500)
  ).current

  useEffect(() => {
    debouncedFetchHits(query)
  }, [debouncedFetchHits, query])

  return <>...</>
}

You may have noticed that we added query as an argument to the debounced version of fetchHits(). This is necessary since we'll be using the same function throughout the lifetime of the component. If we had captured query through a closure, the value of query used by the debounced version of fetchHits() would always be the one present on the component's first render. This is not a problem with dispatch since React guarantees that the identity of dispatch is stable through the lifetime of the component.

If you try this code now, it will look like everything is working fine. But actually, there still are some bugs that we need to fix.

3. Cancel irrelevant requests

When making asynchronous requests, we must not forget that we have no guarantees regarding how much time those requests will take to complete, neither if the requests will be completed in the same order that they were done. What this means for our app, is that a user might have an old search of his, override the result of a new one.

To further illustrate the problem, let's examine the following scenario:

A user makes a search for MobX.
Waits debounce time.
Before getting a response from the API, searches for Redux.
Waits debounce time.

Now, which search result will the user see? The answer is, we don't know. It's a race condition! Whichever API request is solved last, is the one that the user will end up seeing. And if that ends up being the search request for MobX, the user won't get what he's expecting.

One way to fix this issue is to cancel the API requests made for searches that the user is no longer interested in. To do that, we'll use Axios cancellation API, and we'll add a clean-up function to useEffect to trigger the cancellation.

async function fetchHits(query, dispatch, cancelToken) {
  dispatch({ type: "FETCH_START" })
  try {
    const result = await axios(
      `https://hn.algolia.com/api/v1/search?query=${query}`,
      {
        cancelToken,
      }
    )
    dispatch({ type: "FETCH_SUCCESS", payload: result.data.hits })
  } catch (err) {
    console.error(err)
    axios.isCancel(err) || dispatch({ type: "FETCH_FAILURE" })
  }
}

function App() {
  const [{ hits, hasError, isLoading }, dispatch] = useReducer(fetchReducer, {
    hits: [],
    isLoading: true,
    hasError: false,
  })
  const [query, setQuery] = useState("react")
  const debouncedFetchHits = useRef(
    _.debounce(
      (query, cancelToken) => fetchHits(query, dispatch, cancelToken),
      500
    )
  ).current

  useEffect(() => {
    const { cancel, token } = axios.CancelToken.source()
    debouncedFetchHits(query, token)
    return () => cancel("No longer latest query")
  }, [debouncedFetchHits, query])

  return <>...</>
}

4. Avoid invoking debounced function on unmounted component

We're almost done. There's still only one minor detail we need to address. On the unlikely event that the component unmounts before the debounced fetchHits() is invoked, dispatch will be called on an unmounted component. Thus a warning will be shown on the console saying that our app might have memory leaks. For this specific case, there is no memory leak. But we can get rid of that warning by canceling the execution of the debounced function on the useEffect cleanup.

useEffect(() => {
  const { cancel, token } = axios.CancelToken.source()
  debouncedFetchHits(query, token)
  return () => cancel("No longer latest query") || debouncedFetchHits.cancel()
}, [debouncedFetchHits, query])

From the perspective of the behavior of the app, we are done! There are, however, some simplifications that we can do.

5. Simplify

If you were looking carefully, you might have noticed that since we're canceling the debounced fetchHits() on every useEffect clean up, we no longer need to guarantee that the identity of the debounced fetchHits() remains the same through the lifetime of the component. Because we'll always be canceling the old debounce function before calling the new one. Therefore, we can now debounce fetchHits() inside the useEffect hooks.

useEffect(() => {
  const { cancel, token } = axios.CancelToken.source()
  const debouncedFetchHits = _.debounce(
    () => fetchHits(query, dispatch, token),
    500
  )
  debouncedFetchHits()
  return () => cancel("No longer latest query") || debouncedFetchHits.cancel()
}, [query])

But now, we are using debounce() as a simple timeout function. So we can use the browser's setTimeout() instead and get rid of the Lodash dependency.

function App() {
  const [{ hits, hasError, isLoading }, dispatch] = useReducer(fetchReducer, {
    hits: [],
    isLoading: true,
    hasError: false
  });
  const [query, setQuery] = useState("react");

  useEffect(() => {
    const { cancel, token } = axios.CancelToken.source();
    const timeOutId = setTimeout(() => fetchHits(query, dispatch, token), 500);
    return () => cancel("No longer latest query") || clearTimeout(timeOutId);
  }, [query]);

  return ...
}

And we are finally done!

I could have just jumped straight to this final solution using setTimeout() instead of having gone through Lodash debounce(). But I think that going through all these steps is an enriching experience. Since it touches on interesting details of React and on how to correctly use a debounce function with React hooks that may be applicable in other contexts.

Put it into practice

Next time you're faced with having to perform a search only when the user stops typing, remember to:

Use setTimeout() to create a small delay between when the user stops typing and making a call to the API
Clear the timeout on the useEffect hook cleanup to avoid making multiple calls to the API and to avoid performing actions on an unmounted component.
Cancel the requests that are no longer relevant to the user, on the useEffect hook cleanup, to guarantee the user won't see results of old searches instead of the most recent search.

If you enjoyed this article you can follow me on twitter where I share my thoughts about software development and life in general.

Thought process for testing a React application

João Forja 💭 — Fri, 10 Jul 2020 09:59:13 +0000

What concerns should I have when writing tests?

In this article, we'll go over the thought process for testing and implementing a React application that will fetch data from an API and display it. While this is a relatively simple application, it is enough for us to go over some key topics like:

Preparation before writing tests
Defining boundaries for testing
Mocking

What we'll be testing and implementing

Here's a demo of what we'll be building. As you can see, we'll be testing and implementing an application that shows Rick and Morty characters. The characters' information will come from Rick and Morty API.

It's important to mention that before working on an application or feature, it helps to write a test list. By making a test list, we'll have a starting point to write our tests. In a previous article, I went over the process to make a test list, so give if you want to know more.

We'll use the following test list to get us started:

Shows an empty message when there aren't characters
Shows one character with expected info
Shows three characters, each with the expected info
Shows an error message when there was an error getting characters

However, before we pick a test to implement, there are some ideas we need to go over to make the process easier.

It's hard to make tests for production code we have no idea how to write

If we have no idea how to write the production code, writing tests for it will be hard. So before trying to implement something, it's helpful to have some familiarity with the tools and services we'll be using and have a rough idea of how to use them to solve the problem we have at hand. Otherwise, when we're writing tests, it will be hard to define the boundaries for our tests, and when a test fails, we won't know if the problem is in the tests or the production code.

In situations where we're not familiar with a service or a library, we can create a test and use it as a REPL to make requests to the service or try out the library. For situations where we're exploring libraries that manipulate the DOM, we can try them out by writing a component and rendering it in the browser.

For this application, the only thing we're probably not familiar with is the Rick and Morty API. So before starting, we'd make a couple of requests to get an idea of how it works.

Small steps make tests and production code easier to write

An excellent way to have analysis paralysis is to try to solve too much at once. This is also true for building applications with automated tests. If the test we choose to start with will require a lot of production code to pass, we'll have an unnecessarily complicated time.

The key here is to start with a simple test that is simple to write and simple to make the production code for it to pass. This heuristic usually makes us take small enough steps that allow us to tackle one problem at a time.

One of the critical things to keep in mind while taking small steps is to focus on the current step and forget the others. For example, if we are working on showing an empty message when there aren't characters, we do not worry about showing an error message when there's an error getting characters from the server. We first make the test and production code for the empty message case, and then we make the necessary changes to show an error message when there's an error.

It's particularly important to start small on the first test. We may not realize it, but on that first test, we'll have to make a lot of decisions regarding the design of the module we're building as well as how we are going to test it. It's helpful to start with a simple test not to make our task more complicated than it needs to be.

In situations where no test out of the test list is simple enough, we'll likely be able to decompose those tests into simpler ones. In case we end up producing test cases that are so simple that they don't provide any documentation value or are redundant due to other more complicated tests we end up writing, we can always delete them.

Picking the first test

Out of the test list, the tests that seem more simple are:

Shows an empty message when there aren't characters
Shows an error message when there was an error getting characters

To make those tests pass, we only need to render a message to the screen, so the production code is reasonably straightforward. Given both tests are good places to start, we'll just pick the first one.

Defining the boundaries we'll use to test the behavior

To write this first test, we'll have to decide the boundaries we'll use to test the application shows an empty message when the list is empty. In other words, we have to determine the module or component that we will interact with to check the behavior we want to test and implement. Should we test it from a component dedicated to rendering characters, something like <Characters/>? Or should we test it through somewhere else?

Different people will have different answers to the question above. But one approach that's been working well for me when building web applications is to start from the user perspective. As the tests become too complex and difficult to write, I begin to isolate the behaviors I want to test and test them more directly. Following this approach means that we usually start writing from the page the user would access to use a feature.

What's good about starting from the user perspective and then isolating behavior to reduce complexity in the tests, is that it gives a nice balance between tests that aren't too sensitive to changes in the code structure and tests that aren't too far away from the behavior we're interested in. In other words, it strikes a balance between tests that won't break on every refactor and tests that are straightforward to read and write.

Following the strategy above, we would place the boundary of interaction between tests and production code at the component that represents the page where the Rick and Morty characters will be. Something like <RickAndMortyCharactersPage/>.

Passing the characters to the page component

The next decision we have to make is how is <RickAndMortyCharactersPage/> going to have access to the character's data. We know that the characters will come from the Rick and Morty API, and we also know that we don't have control over the behavior of the API. For example, we can't force it to give an error response. This means that we won't be able to create the situations we want to test if we're using the real Rick and Morty API in our tests.

One approach to deal with not controlling the responses from the Rick and Morty API is to mock the interaction with the API. This way, it becomes easy to simulate the situations we want to test. But how exactly should we do it? Should we use something like MirageJS to simulate a server? Should we mock the HTTP client module?

Either making a fake server or mocking the HTTP client would solve the issue of simulating the situation we want to test. However, both approaches force our tests to deal with the details of HTTP interactions. In other words, we would need to do quite a bit of setup to test that given an empty list of characters, we show the right message.

The issue with tests that have complicated setups is that they tend to be hard to write and hard to read. One approach to this problem is to create a function that wraps the HTTP interaction to get the characters and have <RickAndMortyCharactersPage/> use it. Now we can have whichever response we need for our tests just by mocking the new wrapper function. The signature of the wrapper function would look something like this:

async function fetchCharactersFromServer() {
  // Makes request to API and returns characters
}

Making the assertion

From the behavior standpoint, what we want to assert is that when the list of characters is empty, we render a message saying that there aren't characters. So we'll have to search the DOM for the expected message. We also have to keep in mind that fetching the characters from the server is an asynchronous operation, so we'll have to wait for the message to appear.

Dealing with the asynchronous nature of fetching data in this test made me realize that we hadn't written in our test list that we should show the user a loading message while he's waiting for the response with the characters. So at this point, we should add that test to the list.

Taking into account all that we've gone over so far, the test would look like this:

test("Shows empty message when there aren't characters", async function test() {
  const fetchCharacters = jest.fn().mockResolvedValueOnce([])
  render(<RickAndMortyCharactersPage fetchCharacters={fetchCharacters} />)
  expect(
    await screen.findByText("There aren't characters to show")
  ).toBeVisible()
})

But there's one assertion that we're missing in the test above.

Test interactions when using mocks

Whenever we use a mock function, like we just used for our test, we need to make sure that the code under test is calling the mocked function as we intend it to call the real function. We'll also need to make sure that the real version of the function behaves like the mocked version. These kinds of assertions are testing the interactions between modules. It's crucial to test interactions when using mocks since failed interactions give origin to the problem of units that work in isolation but fail to work as a whole.

This means that when we are using mocks, in addition to our tests going over behavior the user can observe, our tests will also cover the interactions between different modules. It's essential to keep those two roles of tests in mind. Otherwise, we'll lose track of what we're trying to test, which leads to frustration when we're trying to write tests.

What this approach means for our test, is it that we'll need to assert that we're calling fetchCharactersFromServer with the expected arguments.

test("Shows empty message when there aren't characters", async function test() {
  const fetchCharacters = jest.fn().mockResolvedValueOnce([])
  render(<RickAndMortyCharactersPage fetchCharacters={fetchCharacters} />)
  expect(
    await screen.findByText("There aren't characters to show")
  ).toBeVisible()
  expect(fetchCharacters).toHaveBeenCalledWith()
})

When we get to testing the fetchCharactersFromServer, we'll need to write a test for it that proves it can return a Promise with an array when things go well. But more on that later in the article.

A look at the code after making the first test pass

After writing this first test and the production code to make it pass, we ended up with this:

test("Shows empty message when there aren't characters", async function test() {
  const fetchCharacters = jest.fn().mockResolvedValueOnce([])
  render(<RickAndMortyCharactersPage fetchCharacters={fetchCharacters} />)
  expect(
    await screen.findByText("There aren't characters to show")
  ).toBeVisible()
  expect(fetchCharacters).toHaveBeenCalledWith()
})

function RickAndMortyCharactersPage({ fetchCharacters }) {
  useEffect(
    function fetchCharactersOnStart() {
      fetchCharacters()
    },
    [fetchCharacters]
  )
  return (
    <div>
      <p>There aren't characters to show</p>
    </div>
  )
}

Notice that there is only enough production code to make the tests pass. This is a crucial aspect of taking small steps that allow us to focus on the current task.

As we write more tests, the production will change to make the new tests pass, but since we have the older tests in place, we can have confidence that we haven't broken anything.

The remaining tests from the test list

After all the work we had to define the boundaries to test our code during the first test, the remaining tests from the test list are very straightforward. So I'll just highlight some interesting points from them, and we'll go straight into testing the code that fetches data from the server.

Testing for errors is simple

Since we decided to wrap in a function the HTTP call to get characters, we can now easily test error situations by having the promise returned from the mock function reject.

test("shows error message when there's an error fetching characters", async function test() {
  const fetchCharacters = jest.fn().mockRejectedValueOnce(new Error())
  render(<RickAndMortyCharactersPage fetchCharacters={fetchCharacters} />)
  expect(
    await screen.findByText("There was an error. Please reload page.")
  ).toBeVisible()
  expect(fetchCharacters).toHaveBeenCalledWith()
})

Since our application doesn't distinguish between errors, we only have a single error test case. But with this approach, testing for other errors would be as simple as changing the error we use when rejecting the promise.

Only the necessary data for the tests

When we wrapped the HTTP call to get the characters, we added a layer of abstraction between the code that renders what we want to show to the user, and the code that fetches the characters. This abstraction layer gives us the flexibility to model the data returned from the server into something that perfectly fits what the view code needs. The results are easier to read and easier to write tests, since the amount of data not relevant to what we're testing, is low.

test("Shows 1 character", async function test() {
  const armorthy = {
    id: 25,
    name: "Armorthy",
    status: "Dead",
    species: "unknown",
    gender: "male",
    image: "/mockArmorthyImageUrl",
  }
  const fetchCharacters = jest.fn().mockResolvedValueOnce([armorthy])
  render(<RickAndMortyCharactersPage fetchCharacters={fetchCharacters} />)

  await assertCharacterIsVisible(armorthy)
  expect(fetchCharacters).toHaveBeenCalledWith()
})

Testing we can get characters from the server

The tests for fetching characters come in two parts. The first one is making sure the function fetchCharactersFromServer behaves as expected, and the second one that it interacts correctly with the server.

Making sure the module behaves as described

Since we have mocked out the function that fetches characters from the server, we now need to write tests that assert the real function behaves in a way that is compatible with how the mocked function behaves. This is important to make sure that fetchCharactersFromServer and <RickAndMortyCharactersPage/> will work well together.

By looking at the code from the previous tests, we can get an idea of the assertions we'll need to write.

// Defines how function should behave when there's an error
const fetchCharacters = jest.fn().mockRejectedValueOnce(new Error())
// Defines how function should behave when all goes well
const characters = [
  {
    id: 25,
    name: "Armorthy",
    status: "Dead",
    species: "unknown",
    gender: "male",
    image: "/mockArmorthyImageUrl",
  },
  // more characters...
]
const fetchCharacters = jest.fn().mockResolvedValueOnce(characters)

From looking at the code above, we know that we'll have to assert thatfetchCharactersFromServer rejects a promise when something goes wrong, and that it returns an array with characters when things go right. The structure of the characters should be compatible with what the code above specified, of course.

Interacting with the server

The logic for testing the interaction between fetchCharactersFromServer and the server, is the same we used when we decided to mock the fetchCharactersFromServer on the previous tests. Since we have no control over the server's responses, we'll mock it out for our tests. But given the server API is already established, we'll need to make sure that our mock behaves as the server would and that we're making the HTTP request as the server expects.

In this article, we've previously talked about two options to mock the server: simulating a server using a library like MirageJS, or mock the HTTP client. Since mocking the HTTP client will make our code break if we decide to change the client, and we don't get any significant benefits from doing so, we'll write the tests for fetchCharactersFromServer using MirageJS.

A straightforward way to bring the behavior of the fake server close to the real server is to make manual requests to the real server and observe the headers necessary to make the request, as well as the format of the response. Then on the fake server, we can check if the required headers are present and make it return a response with the same structure as the real server would.

In situations where we have access to the code of the server, looking at tests against the endpoints can give a helpful idea of the behavior we have to replicate.

Following what we've just talked, we end up writing the tests below:

import { Server, Response } from "miragejs"
import charactersApiResponse from "./characters-api-response.json"
import { fetchCharactersFromServer } from "../RickAndMortyCharacters"

test("On error fetching characters, rejects promise", async function test() {
  const server = new Server({
    environment: "test",
    routes() {
      this.urlPrefix = "https://rickandmortyapi.com"
      this.get("/api/character/", () => {
        return new Response(500)
      })
    },
  })

  await expect(fetchCharactersFromServer()).rejects.toEqual(undefined)

  server.shutdown()
})

test("On success fetching characters, returns them", async function test() {
  const server = new Server({
    environment: "test",
    routes() {
      this.urlPrefix = "https://rickandmortyapi.com"
      this.get("/api/character/", () => {
        return charactersApiResponse
      })
    },
  })

  const characters = await fetchCharactersFromServer()

  expect(characters).toMatchObject([
    {
      id: 1,
      name: "Rick Sanchez",
      status: "Alive",
      species: "Human",
      gender: "Male",
      image: "https://rickandmortyapi.com/api/character/avatar/1.jpeg",
    },
    // more characters...
  ])
  server.shutdown()
})

And this brings us to the last tests of this application.

Putting it all together

The only thing that's left now to make this application work, is to connect the fetchCharactersFromServer with the <RickAndMortyCharactersPage/>. We can do that with the code below:

function RickAndMortyCharactersPage({
  fetchCharacters = fetchCharactersFromServer,
}) {
  //...
}

To ensure the two modules are connected, we could write an E2E test. But given how straightforward the connection between modules is, it's easier to run the application and look at the browser.

You might be wondering where styling the application fits in all of this. Although visuals are a vital part of any web application, the tests we wrote almost only cover the application's behavior. That is, they assert that the application shows the data the user wants to see and that it responds as expected to user interactions. Visual regression testing is an exciting topic that I'd like to cover on a future article, but what's written in this article doesn't apply to it.

Regarding when to style the application using the process of this case study, I think that will mostly depend on the context we're developing. With that said, I like to do it after I've finished implementing a feature or sub-feature. Because by then, I usually have a better sense of how the feature will work, so adapting a design becomes easier.

A closer look into the code

In case you're interested in observing the little details that went into building this application, you can take a look at this repository. There's one commit at least every time a new test passes, so if you look at the commit history, you can get a reasonably detailed view of the process.

Key takeaways

Next time you're faced with writing tests for a React application, remember the following:

It's easier to write tests for code we have some idea on how to implement. So explore the services and tools you'll be using before starting.
Small steps will make tests and production code easier to write. So go one test at a time and only worry about making the current test pass.
Start testing from the user perspective, and as tests become too hard to write, use mocks to isolate the behavior you want to test and bring down the complexity of the tests.
Whenever we mock a module, we need to test that the code using the mocked module interacts with it as the real module expects to. We also need to test that the real module behaves as the mocked module.

If you enjoyed this article you can follow me on twitter where I share my thoughts about software development and life in general.

What's something that you've done in software development that you're proud of?

João Forja 💭 — Sat, 04 Jul 2020 21:03:31 +0000

This happened in my first professional project, and although it wasn't that significant or technical, I'm proud of it since it helped move the project forward and taught me a lesson that I always keep in mind.

My first professional project was the development of a small product that had the goal of helping manage workforces. You can think of it as a glorified to-do application. The project was greenfield, which meant that a lot of requirements were yet to be defined/discovered. Since I was working in a small team, I ended up attending meetings with the client, which over time, gave me the necessary confidence to speak my mind whenever I thought I had a useful contribution. It also gave me a perspective on the business side of the product.

One day at the office, my boss told me that I should stop working on my current feature and instead work on a new one the client had just requested. The new feature was to introduce tasks that had sub-tasks, and the task would be completed when the user completed all the sub-tasks. Asking for that feature at that particular time didn't make much sense to me from a business perspective. And on top of that, it was a relatively expensive feature since we had to make changes in all parts of the system (UI, FE, BE, and DB). Thankfully, we had a meeting with the client later that day, and my boss agreed to wait until after the meeting for us to start developing the feature. This was great because it allowed me to clarify what was happening.

During the meeting, I asked the client why he was in such a rush to get that new feature. The problem was that users couldn't grasp what they had to do for the day, because their list of tasks was getting cluttered by tasks with the same name, but that had to be done at different times. Our client's solution to the issue was to create a sub-task system so that in the UI, we could group tasks and show them as a single card. Since I now knew what the problem was, I suggested that we could just change the UI to group tasks with the same name, we didn't need sub-tasks. This approach would solve the problem, be cheaper to implement, and allow us to focus on other essential features. The client accepted the suggestion, and it worked well! And as far as I worked on the project, we never needed to implement that sub-tasks system.

What I understood from that point onwards was that our value as developers doesn't have to be just technical. I would even argue that where we can provide the most value is on closing the gap between the business side and the technical side of software development. Our clients don't know which features add a lot of complexity to the system and which don't. A lot of times, they have misconceptions or simply don't know what it's possible to do with software. And I believe that it is our job as developers to not only build the systems but also to advise our clients on what seems for us the better route for them to have success.

What about you? What's something that you've done in software development, technical or not, that you're proud of?

5 steps to deal with bugs on your React applications

João Forja 💭 — Thu, 02 Jul 2020 21:10:23 +0000

When we find a bug in our applications, fixing it is only the beginning. We also need to make sure the same bug won't happen again, and we should also take the opportunity to prevent similar bugs from happening. To help us achieve those goals, we can use the following process:

Analyze the defect and find the broken code.
Reproduce the bug in a targeted automated test and fix it.
Improve the code design to reduce the likelihood of bugs.
Perform root-cause analysis to find the origin of the bug.
Conduct exploratory testing to find similar bugs.

In this article, we'll go over a bug on a React application and use this 5 step approach to fix it and prevent future ones. By the end of this article, you'll have a better understanding of how this process works and how to apply it to bugs you might find on your applications.

Applying the process

To show how this process would work in practice, we'll use a simplistic React application that allows a user to select a book from a list and then fetches the name author of the chosen book from an API and displays it.

Below is the code that's relevant for this example:

const NO_BOOK_SELECTED = "no-book-selected"
const LOADING = "loading"
const SHOW_AUTHOR = "show-author"
const ERROR = "error"

function Books({ fetchBookAuthor }) {
  const [{ author, status }, setState] = useState({
    status: NO_BOOK_SELECTED,
    author: null,
  })

  function fetchSelectedBookAuthor(event) {
    setState({ status: LOADING })
    fetchBookAuthor({ bookId: event.target.value })
      .then(
        bookAuthor => ({ status: SHOW_AUTHOR, author: bookAuthor }),
        () => ({ status: ERROR })
      )
      .then(newState => setState(newState))
  }

  return (
    <>
      <form>
        <label htmlFor="book">Book</label>
        <select id="book" defaultValue="" onChange={fetchSelectedBookAuthor}>
          <option value="" disabled hidden>
            Select a book
          </option>
          <option value="1">TDD by example</option>
          <option value="2">Clean Architecture</option>
          <option value="3">The Software Craftsman</option>
          <option value="4">Refactoring</option>
        </select>
      </form>
      <div>
        {status === NO_BOOK_SELECTED && <p>No book is selected.</p>}
        {status === SHOW_AUTHOR && <p>{author}</p>}
        {status === LOADING && <p>Loading...</p>}
        {status === ERROR && <p>There was an error.</p>}
      </div>
    </>
  )
}

1. Analyze the defect and find the responsible code

As we can see in the GIF above, the user selected the book "TDD by example" and before giving the API time to answer with the author, changed the book to "Clean Architecture". The result is that the application shows "Kent Beck" as the author of "Clean Architecture" when it should have shown "Robert C. Martin".

Since we are at the first step of the process, our focus is on making a hypothesis about why this bug might be happening and locate the area, or areas, of the code that we'll need to change to fix the bug.

From experience, I know that this kind of bug tends to happen due to race conditions. In particular, it occurs when responses from requests come out of order. So I hypothesize that the response for "TDD by example" came last even though it was made first, and that resulted in the UI updating the author to "Kent Beck" even though "TDD by example" was no longer the book the user selected.

Since we're dealing with a small example, we know that we'll have to change <Books/> to fix the bug.

2. Reproduce the bug with an automated test and fix it

Since we now have a hypothesis of what might be causing the bug, we will write an automated test to prove our hypothesis correct. By having an automated test, we also prevent the same bug from happening again. But before writing the test, we have to decide our testing boundary.

When defining a testing boundary that tries to reproduce a bug, I tend to establish it as close as possible to the faulty code without coupling the tests too much to the details. The goal is that if someone introduces this bug again in the system, they know that something broke and where it exactly broke. Therefore, I'll prefer using unit-level tests instead of E2E like tests since when an E2E test breaks, it can be tough to know where the problem is. For our specific example, let's place the testing boundary at the <Books/> component.

The test below reproduces the steps we think are responsible for the bug.

// This test uses Jest + React testing library
test(
  "Avoids race conditions when responses for requests to get books' author " +
    "come out of order",
  function test() {
    let resolveAuthorForTDDByExample
    let resolveAuthorForCleanArchitecture

    const fetchBookAuthor = jest
      .fn()
      .mockReturnValueOnce(
        new Promise(res => {
          resolveAuthorForTDDByExample = () => res("Kent Beck")
        })
      )
      .mockReturnValueOnce(
        new Promise(res => {
          resolveAuthorForCleanArchitecture = () => res("Robert C. Martin")
        })
      )

    render(<Books fetchBookAuthor={fetchBookAuthor} />)

    const bookInput = screen.getByLabelText("Book")
    userEvent.selectOptions(bookInput, screen.getByText("TDD by example"))
    userEvent.selectOptions(bookInput, screen.getByText("Clean Architecture"))

    resolveAuthorForCleanArchitecture()
    resolveAuthorForTDDByExample()

    return waitFor(() => {
      expect(screen.getByText("Robert C. Martin")).toBeVisible()
    })
  }
)

The test above fails, proving our hypothesis correct. Next, we need to fix the code to make the test pass.

To make the test pass, we'll introduce a mechanism to detect if the response from a request is still relevant to the user or not. If it isn't, we'll ignore the response. For now, we'll worry about making it work. Later we'll take care of the design.

function Books({ fetchBookAuthor }) {
  const [{ author, status }, setState] = useState({
    status: NO_BOOK_SELECTED,
    author: null,
  });
  // Added ref to DOM element so we can check the current selected book
  const bookSelectInputRef = useRef();

  function fetchSelectedBookAuthor(event) {
    const bookId = event.target.value;
    setState({ status: LOADING });
    fetchBookAuthor({ bookId })
      .then(
        (bookAuthor) => ({ status: SHOW_AUTHOR, author: bookAuthor }),
        () => ({ status: ERROR })
      )
      .then((newState) => {
        const currentSelectedBook = bookSelectInputRef.current.value;
        currentSelectedBook === bookId && setState(newState);
      });
  }

  return (
    <>
      <form>
        <label htmlFor="book">Book</label>
        <select
          id="book"
          defaultValue=""
          ref={bookSelectInputRef}
          onChange={fetchSelectedBookAuthor}
        >
         ...
    </>
  );
}

Now our test passes so we can go to the next step.

3. Improve the code design to prevent bugs

The goal of this step is to try to understand how the current code design might have caused the bug to happen, and improve the design to prevent bugs in the same area of the code.

The specific ways in which we can improve an existing design are many, and a topic that I won't go over in this article. But as a general guideline I try to guide the code towards better readability by reducing complexity and making hidden concepts explicit.

For our specific example, I find it confusing how we use the state in the <select/> DOM element to determine if a response is still useful to the user. I think it doesn't express intent well. I'd like to refactor the code to make it evident that when the user changes the book, we no longer care about any responses from ongoing requests. I think that the concept of cancellation might be a good fit here. So let's refactor the code in that direction.

function Books({ fetchBookAuthor }) {
  const [{ author, status }, setState] = useState({
    status: NO_BOOK_SELECTED,
    author: null,
  });
  const [selectedBookId, setSelectedBookId] = useState("");

  useEffect(() => {
    if (!selectedBookId) return;

    let cancelled = false;
    setState({ status: LOADING });
    fetchBookAuthor({ bookId: selectedBookId })
      .then(
        (bookAuthor) => ({ status: SHOW_AUTHOR, author: bookAuthor }),
        () => ({ status: ERROR })
      )
      .then((newState) => !cancelled && setState(newState));

    return () => (cancelled = true);
  }, [fetchBookAuthor, selectedBookId]);

  return (
    <>
      <form>
        <label htmlFor="book">Book</label>
        <select
          id="book"
          value={selectedBookId}
          onChange={(e) => setSelectedBookId(e.target.value)}
        >
          ...
    </>
  );
}

The above was just an example of a possible refactor. We could have opted for other refactors that might give better results, like using a finite state machine to make the available states and transitions of the component easier to understand.

Keep in mind might be that not all bugs are caused by bad code design, so there might be nothing to do in this step.

4. Perform root-cause analysis to find the origin of the bug

The goal of this step is to determine the origin of a bug, so we can then improve what might be at fault. In my opinion, this is the most valuable step of the process as it can find some surprising issues that can tremendously help individuals and organizations move forward when solved.

There are multiple ways we can do a root-cause analysis, but a simple and effective is to use the "5 Whys" technique. This technique aims to look at a problem and continually ask why it happened until we reach what seems to be its root.

For our specific example, using the 5 whys technique could go something along the following lines:

Why did we have a race condition bug? - The developer that implemented the feature wasn't aware of the possibility of race conditions when making API requests.
Why didn't the developer know about race conditions? - It was his first time dealing with API requests, and he did it alone.
Why didn't he ask for help from a colleague? - He felt afraid of being judged by his colleagues.
Why was he afraid of being judged? - Because at the office, people believe that asking for help is a sign of incompetence.

From the example above, we can see that by following the bug, we revealed a cultural problem at the company that we can now decide how to address. Of course, there might be more causes than just that one, and choosing which cause to address will depend on the context. Nonetheless, the issues that this type of analysis can uncover are invaluable.

An important thing to keep in mind when doing this is to try not to blame individuals. Blaming individuals tends not to lead us to productive results. Keep the focus on the faults of the process.

5. Conduct exploratory testing to find similar bugs

The core idea behind this step is that bugs tend to cluster. So if someone found a bug in our application, we likely have others that follow the same pattern, and we should try to find them.

For our specific example, we would do some exploratory testing on our application focused on finding bugs related to making API requests and race conditions.

If you're not familiar with the term Exploratory Testing, I recommend you check this book. This is arguably a topic that's more important for QA than for developers. However, I believe that having this kind of knowledge as a developer can make a massive difference in the robustness of the applications we build.

Conclusion

When we find a bug in our applications, we can use the 5 step process explained in this article to fix the found bug and prevent future ones. So next time you spot a bug in your application, give this process a try.

I couldn't end this article without saying that I didn't come up with this process. I've learned it from James Shore, and I highly recommend you check out his blog.

If you enjoyed this article you can follow me on twitter where I share my thoughts about software development and life in general.

Have you been part of a project that failed? Why do you think that happened?

João Forja 💭 — Tue, 23 Jun 2020 17:41:18 +0000

One of the most frustrating experiences I've had as a software developer is to be part of a project that's doom to failure.

Some of the reasons for the failures I've witnessed are:

The business model of the software company doesn't allow for the flexibility needed to build the right software and have profit.
Lack of feedback from the real-world.

I think Reason 1 is most common when working with fixed quotes. What happens is that a client says he wants an app that does X, and the software company says it will cost Y$. But the truth is that the client doesn't know what X should do, with enough detail, to solve the problem they want to solve. This is perfectly normal since software development is a discovery process, and therefore we'll never know all we'll need before starting. The result is a quote that soon enough stops making sense, but that bounded both parties to building something useless. This creates a rigid environment that makes changing the course of a project so it can be useful and feasible extremely hard, since changing scope has financial implications. The renegotiations tend to drag so much and be so hostile that the project gets canceled.

I've seen reason 2 happen when there's a lack of feedback from the end-user of the app. In situations like this, the client is not the end-user but assumes the role. The problem is that the client can't faithfully represent the user and doesn't communicate with him/her nearly enough. The result is building something that isn't useful to the user, or the client gets analysis paralysis and can't decide on what needs to be developed. Either way, the budget runs out before something useful is ever produced.

Have you been in a project that failed? Why do you think it failed?