In this article you'll find a compilation of excellent resources that will help you understand how React does what it does.

1. Build your own React

Build your own React is a fantastic article written by Rodrigo Pombo that goes over how to build your own React from scratch. It is an amazing place to start the journey of learning how React works, since it goes over most of the core functionalities and structure of React. On Build your own React you'll learn about the following topics:

1. The createElement Function
2. The render Function
3. Concurrent Mode
4. Fibers
5. Render and Commit Phases
6. Reconciliation
7. Function Components
8. Hooks

To better learn the content, my suggestion is that you code along with the article. By the end of it, you'll have implemented your own version of React from scratch.

2. Overreacted

Overreacted is the personal blog of Dan Abramov. In case you didn't know, Dan Abramov is a member of the React core team and a co-author of Create-React-App.

In Dan's blog you'll be able to find a lot of interesting articles about the inner workings of React. Some of those article are:

1. React as a UI Runtime
2. A Complete Guide to useEffect
3. Why Do React Hooks Rely on Call Order?
4. How Does React Tell a Class from a Function?

Overreact articles tend to be long, and the content can be quite heavy. My suggestion is that you focus on it and try to not get distracted. Otherwise, it might be hard to grasp the concepts being explained.

Dan will probably keep updating his blog with more interesting content, so it's a good idea to keep an eye out for it.

3. React codebase overview

If you really want to go deep, the overview page of React's codebase is the place to go.

By going over the documentation, you'll not only learn more about the overall architecture of React, you'll also find a lot of interesting resources each of the core main components of the React architecture.

Also, by going over the codebase overview and its recommended resource, you'll be in better shape to give back to the community and one day make a contribution to React itself. It's a pretty good investment.

4. Reactiflux's channel react-internals

Getting to know a codebase as complex as React's can be difficult. So it's always good to know where to ask for help.

Reactiflux is a chat community for developers who want to chat about React & Javascript. In there you'll find a channel dedicated to the inner workings of React, called react-internals.

If you've got a doubt about how React does something, react-internals is a good place to ask for help.

It's also a good idea to just go to the channel and read the messages that are in there. You'll often find really good material that will help you better understand how React works.

Conclusion

By now, you already know some good resources to get started learning React under the hood.

However, beware that learning a lot of material at once can be quite hard and takes some time. So look at this as a continued effort, and not as something to get done in a day. It's more of a marathon and less of a sprint.

Schedule slots of your days to go over these resources. Try to not get distracted or interrupted during those slots. Follow the order the resources were presented in this article. And really focus on the content. Sooner rather than later, you'll feel a lot more confident on your skills as a React developer.

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. If you're not sure why this might lead to bugs, you'll find this article interesting.

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:

1. A user makes a search for MobX.
2. Waits debounce time.
3. Before getting a response from the API, searches for Redux.
4. 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:

1. Use setTimeout() to create a small delay between when the user stops typing and making a call to the API
2. 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.
3. 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 might also like this one about how to implement infinite scroll with React using Hooks and Intersection Observers.

Anyone can write a basic fetch request and get some data back. But what other things should be considered? What are more production-grade requirements?

Fetching data from APIs is something that almost all React applications do. However, this doesn't mean doing it correctly is easy. While it's straightforward to fetch data and show it on the screen, it's not trivial to get all the corner cases right.

In this article, we'll go over 7 questions we can make to find out corner cases when fetching data from an API. We'll start with an overview of all of them, and then go into detail on each one.

Questions

1. Are we canceling API requests when the response is no longer needed?
2. Are we handling all possible error and success cases?
3. Can the application handle exceptions thrown from API requests?
4. Is it possible for the user to get stuck on a loading screen?
5. Is the application ready to deal with API requests that may take a while to complete?
6. When will it be necessary to fetch the data again?
7. Are we handling race conditions?

Are we canceling API requests when the response is no longer needed?

When the result of an API request isn't needed anymore, we should cancel it. Otherwise, we might run into errors like Can't call setState on an unmounted component, or we might end up showing the user information that isn't correct.

There are multiple ways for the data returned from an API request to become unnecessary. I find out that the most common ones are when the component that was going to store the data is no longer mounted, and when the state/props used to make the request or handle its response are no longer up to date.

Are we handling all possible error and success cases?

When fetching data from an API it's easy to think of successes and errors as rendering data on the screen or showing a generic error message. However, it can be a lot more complicated than that.

We might not want to handle all success responses equally. As an example, we might be fetching data from a collection. What happens when the collection is empty? We may want to redirect the user to another page or render a custom screen just for that situation. Another example is implementing infinite scroll. The user may, eventually, reach the end of the feed. How will the application handle that?

The same is true for errors. For some errors, a generic try again message might be the only solution. However, other errors may require different approaches. If we're making a request to an API that needs authentication, we might have an error due to an expired session. On an expired session, it might be a good idea to tell the user that his session has expired and that he'll have to log in again. Other errors might be sporadic, and it might be a good idea to retry the request before showing an error message.

Handling the variety of responses from an API can have a significant impact on the design of the application. So it's essential to be aware of them when implementing a solution.

Can the application handle exceptions thrown from API requests?

It's easy to forget that the API we're using to make requests may throw an exception. To avoid the application crashing horribly in the hands of our users, it's a good idea to .catch() those errors or to surround them in a try-catch block.

Is it possible for the user to get stuck on a loading screen?

When it's necessary, we rarely forget to set a component state to loading when we're going to fetch data. But what about removing that loading state? When we get our code ready to handle exceptions and error responses, depending on how we designed our code, it's easy to let an execution path slip by that doesn't remove the loading state. Better to keep an eye out for it.

Is the application ready to deal with API requests that may take a while to complete?

Due to a server receiving a lot of traffic at the time of the request or simply because the API request triggers an operation that takes a while to complete, the user might be left watching a loading screen.

To prevent a depressing UX, we need to be aware of when loading might take a while and choose an appropriate strategy to mitigate it. Common strategies involve setting a timeout for the request to showing an entertaining UI to make time go by faster.

When will it be necessary to fetch the data again?

As soon as we get data back from the server, it might already be stale. If that's a problem or not depends on the domain and nature of the application and data.

In real-time applications, there's a high effort to keep data in sync between server and clients. But on a blog, we can wait for the user to navigate back to the page to show him the most up to date articles.

The crucial thing here is to analyze the domain and nature of the application and data and look for situations where the user not seeing the most up to date data might be problematic.

Are we handling race conditions?

A common pitfall when making API requests that may run in parallel is to forget that the order in which we made the requests, is not necessarily the same order in which we'll get the responses. For example, if we make request A followed by B, we might get the response from B first than A. Depending on the context, this might lead to inconsistent and buggy behavior.

A classic example where this might be an issue, is when making a search box with auto-complete. If we make an API request each time the search box query changes, we'll end making multiple requests that will run in parallel. When we're not careful to display the response related to the most up to date query, we may have a response from an older query override the most recent one.

Conclusion

Correctly handling all the corner cases of fetching data from an API can be hard. One way to deal with it is to have strategies we can systematically apply and rely on. These seven questions are part of my strategy to deal with fetching data. Another useful strategy is to send logs made on the application to a server for later analysis. Analyzing logs can help track undesired behaviors.

Next time you have to fetch data for an application, give these questions a try and see how many corner cases you uncover because of them.

Programming with strategies and principles is useful regardless of what we're building. I'd say it is the cornerstone of consistently making high-quality software. If this idea resonates with you, subscribe to the newsletter at the end of this page. I'm always trying to improve my strategies and development processes, and I share my findings in this blog.

I hope this article is useful to you, and feel free to hit me up on twitter if you want to talk about it :)

The difference might seem meaningless since performance will be optimized by recomputing values only if a dependency changes. This makes us think that the identity of the memoized value should be preserved. And it will, but not always.

If we take a look at React's documentation on useCallback and useMemo, we can find the following:

useCallback(fn, deps) is equivalent to useMemo(() => fn, deps)

You may rely on useMemo as a performance optimization, not as a semantic guarantee. In the future, React may choose to “forget” some previously memoized values and recalculate them on next render, e.g. to free memory for offscreen components. Write your code so that it still works without useMemo — and then add it to optimize performance.

If by reading the documentation, you're still not sure if when using useCallback you should have the same considerations as when using useMemo, you can check this issue on React's repository.

In short, what the documentation tells us, is that we can't rely on useMemo and useCallback as a means to preserve identity, only as a performance optimization that might recompute the memoized value when it sees fit.

When might this misconception be a problem

Whenever we reach for useMemo or useCallback and preserving the identity across renders of a value or callback is crucial for our app to work correctly, we are susceptible to bugs.

A concrete example is when using a debounced function. When using a debounced function, we need to make sure that we're preserving its identity. Otherwise, it won't work as expected.

Let's imagine a use-case where we want to perform a search only after the user stops typing. For that, we are going to debounce the function that will trigger the API request, and have it called every time the user types something.

function fetchHits(query, dispatch){ /* Makes API call*/ }
function App() {
  ...
  const debouncedFetchHits = debounce(query => fetchHits(query, dispatch), 500)
  return <>...</>
}

Due to the nature of React function components, we know that the identity debouncedFetchHits won't be preserved across renders. So our implementation is broken. To fix that, we'll wrap the debounced function in a useCallback.

function fetchHits(query, dispatch){ /* Makes API call*/ }
function App() {
  ...
  const debouncedFetchHits = useCallback(
    debounce(query => fetchHits(query, dispatch), 500),
    [])
    // NOTE: fetchHits is on outer scope, so it shouldn't be in the dependencies []
  return <>...</>
}

If we test this solution, it will seem to work. However, it might not work all the time since the identity of debouncedFetchHits might not always be the same across renders. In our use-case, that would mean that, occasionally, we would be making API requests for queries that aren't relevant to the user, and showing him results that are not of his interest.

Note: If you'd like to know how to fully implement the perform a search only after the user stops typing use-case, you might like this article.

Solution

The solution is to use useRef hook instead of the useCallback.

function fetchHits(query, dispatch){ /* Makes API call*/ }
function App() {
  ...
const debouncedFetchHits = useRef(
    debounce(query => fetchHits(query, dispatch), 500)
  ).current
  return <>...</>
}

The useRef hook gives us the semantic guarantee of identity across renders that useCallback and useMemo don't. Thus, we no longer need to worry about hard to track bugs caused by changes to the identity of debouncedFetchHits.

Conclusion

Next time you reach out to useMemo or useCallback, ask yourself if you want to do a performance optimization or if you want a guarantee of identity. If what you're looking for is a performance optimization, useMemo and useCallback are the way to go. Otherwise, useRef is what you're looking for.

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:

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

Let's clarify a bit each of the criteria:

1. Since A will become simpler to implement because it uses B, that relationship makes sense to exist.
2. 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.
3. It only makes sense for B to exist without A if component B is useful to other components besides A.
4. 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:

1. Optimized for videos with a 16:9 aspect ratio.
2. Supports play and pause any time during the video.
3. Allows for quick navigation to any part of the video.
4. Supports mute and unmute.
5. 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.

1. A is essentially simpler because it uses B
2. B is not substantially more complex because it is not allowed to use A
3. There is a useful subset containing B but not A
4. 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.

To understand how important automated tests can be, we first need to know why we write them.

Why automated tests

We write automated tests because we expect them to save us money, time, or both.

How much money and time automated tests will save us depends on the context we're working on. The domain of the application, the number of people working on the team, and the size of the codebase, alongside other things, influence how useful automated tests can be. Therefore, how important it is to know how to write automated tests will depend on the project's characteristics.

Where automated tests aren't important

There are several ways automated tests can save time and money. Some of them are: Reduce manual testing time. Prevent regression bugs. Give feedback on the modularity of the codebase, which can be used to make it easier to maintain.

If we're using React to work on projects where none of the issues addressed by automated tests exist, not knowing how to make them isn't a problem. Simple blogs, portfolios, and landing pages tend to fit this category. We can manually test them quickly, and they usually don't get new functionalities or benefit from activities such as refactoring. I'd even say that for projects of this nature, writing automated tests might be detrimental as the cost of creating and maintaining them may surpass the benefits.

Where automated tests make all the difference

Automated tests can make a significant difference in projects that will continuously get new features, have multiple people working on it, and long term maintainability is a real concern. Which if we're working on a company with a React-based product will be the case most of the time.

As the project starts to grow and more people begin to work on it, not everyone will know every corner of the codebase. And that together with how much frontends tend to change, the probability that someone introduces a regression skyrockets.

Manual testing becomes prohibitively expensive as the number of logic branches only increases. And that's not to mention how mind-numbingly boring manual testing can become when we need to test for quirky browsers like Safari.

The codebase design starts to matter, as it is hard to add new features or change existing ones in a poorly designed application, thus reducing the maintainability of the project.

These are all issues that cost us time and money, and that automated tests can help us with. This is not to say that automated tests are the definitive cure for all software problems, far from it. But it can make such a difference that some companies won't accept developers that don't know how to write automated tests.

Conclusion

In summary, the importance of automated tests depends on the characteristics of each project.

If we only work on projects where automated tests won't save us money or time, learning how to do them might be unnecessary.

However, on complex applications with multiple people working on it, automated tests can make such a difference that we might not even be allowed to work on the project if we don't write automated tests for what we develop.

Other articles about testing

If you enjoyed this article, you might also like the following:

1. How to get started testing React applications
2. Don't know what to test on your React App? Learn how to make a test list.
3. Not sure how to write tests for your React app? This might help.

I want an image to do an animation whenever it is changed. I've created the animation but it only happens once upon creation.

Let's say we want to build a simple app that displays an image chosen by the user. Each time a new image appears, we want to show it with an animation.

function ImageAnimation() {
  const [imgId, setImgId] = useState(10)

  return (
    <div>
      <input
        style={{ display: 'block' }}
        value={imgId}
        type="number"
        onChange={(e) => setImgId(e.target.value)}
      />
      <img
        style={{ animation: 'flash 1.5s .5s' }}
        alt="user selected"
        src={`https://i.picsum.photos/id/${imgId}/300/300.jpg`}
      />
    </div>
  )
}

The code above makes a request to Lorem Picsum API to fetch an image. The image shown will depend on value of the input. If the user changes the input value, a new request to the API will be done to fetch the photo with an id equal to the current input value.

Currently, the animation will only work on the first shown image. It won't work as the user changes the image.

The animation works for the first the image, because an animation executes when a DOM element enters the DOM. But it won't execute again if the src attribute of the element is changed. This is important since, for our current code, React will only update the src attribute whenever the image changes. It won't unmount and remount the image element.

In vanilla JS, what React is doing is analogous to the following:

imageDomElement.setAttribute(
  'src',
  `https://i.picsum.photos/id/${newImageId}/300/300.jpg`,
)

One way to solve this bug, is to tell React that whenever the image is changed, it should be considered a new element. Thus, React shouldn't reuse the existing DOM element and should use a new one instead. What we want to happen, is something similar to what the code below does:

var imageParent = imageDomElement.parentNode
imageParent.removeChild(imageDomElement)

var newImageElement = document.createElement('img')
newImageElement.setAttribute('style', 'animation: flash 1.5s .5s;')
newImageElement.setAttribute(
  'src',
  `https://i.picsum.photos/id/${newImageId}/300/300.jpg`,
)

imageParent.appendChild(newImageElement)

To do this, we can use React's key attribute. If we add a key attribute with the value of the input to the image, and change it whenever the input value is updated, React won't try to reuse the current DOM element. You can read more about the key attribute here.

function ImageAnimation() {
  const [imgId, setImgId] = useState(10)

  return (
    <div>
      <input
        style={{ display: 'block' }}
        value={imgId}
        type="number"
        onChange={(e) => setImgId(e.target.value)}
      />
      <img
        key={imgId}
        style={{ animation: 'flash 1.5s .5s' }}
        alt="user selected"
        src={`https://i.picsum.photos/id/${imgId}/300/300.jpg`}
      />
    </div>
  )
}

This way, the animation will be triggered when the image is changed since it just got added to the DOM.

Conclusion

The takeaway from this blog post could easily be to remember that an animation will be triggered when a DOM element gets added into the DOM, and that we can make React not reuse the current DOM element by using the key attribute. But I think it runs deeper than that.

I'd say the takeaway from this blog post is that we need to understand how the tools we use work. Without that, we'll be limited in what we can build and the problems we can solve.

Keep learning about how the tools you use work, and why they were designed like that. It will make you a much better software developer.

My code works, but I think it is implemented incorrectly.

After we've been programming for a while, we reach the conclusion that making our React applications work is not enough to produce good quality software.

We now worry about things like maintainability, readability, and best practices. And that's a good thing and a sign that we're becoming better developers. But when we don't have a concrete grasp of what those concepts mean, and of what really makes software valuable, it's easy to start constantly doubting the quality of our work.

In this article I'm sharing mental models and a strategy we can use to get more confident about the code we make. I Hope this proves to be as useful to other as it is to me.

The content of this article is applicable not only to React applications. And so that we don't get distracted by React technicalities, I'll keep the terms used as general to the context of software development as possible.

We'll start by going over what makes software valuable, so we can understand what good quality software is. After we've got a grasp of what that is, let's talk about an intuitive strategy that doesn't really help improve code quality and why. Then we'll go into some characteristics of poor quality software and how those can be addressed. After that, we'll go over a simple but effective strategy we can use to help us improve the quality of our software. Let's get started.

The characteristics of good quality software

The value of software comes from its correctness and its maintainability. Correctness is about software conforming to the requirements. If a piece of software does what the requirements expect of it, it is correct. Maintainability refers to the software ability to adapt to the future. We can consider that a piece of software is maintainable if, as time goes by, the cost of adding, removing or changing features does not increase.

Given that correctness and maintainability are what make software valuable, we can therefore conclude that good quality software needs to fill the expected requirements at all times, and have a structure which will allow it to adapt to the future.

If you'd like to know why correctness and maintainability are what make software valuable, you can read this article

What makes a code base unmaintainable

Usually it is fairly simple to tell the correctness of our software. We can perform tests, automated and manual, that will give us confidence that the requirements are being filled. However, when dealing with maintainability it tends not to be as straight forward, since we don't have that obvious and immediate feedback as we have with correctness. Therefore, we are sort of left in the uncertainty wondering if our software will be able to adapt to the future or not.

As a rule of thumb, it's easier to find out what will make something fail than it is what will make it succeed. So when we're not sure of the decisions we have to take, just keeping in mind the ones we have to avoid can be a good pretty good strategy. So let's look at one of the most instinctive ways of trying to make our code adapt to the future, and know why we need to resist that urge.

Don't try to predict the future

One of the first instincts that comes when dealing with the uncertainty of the future, is to try to predict it. As such, we'll try to write our code in a way that it is prepared for the changes we believe will happen.

The problem with forecasting is that we as humans are awful at it. If we weren't, software wouldn't change nearly as much as it does. We tend to believe that a feature will be a hit, only to find out later that no one really uses it. As such, if we try to make guesses as to where the software is headed, and the more long term those guesses are the worse, we'll end up with a lot of code that does not contribute to correctness, and probably never will. And code that does not contribute to correctness nor improves maintainability, only makes our lives harder and wastes our time.

Another big problem with the forecasting approach is that it makes it really hard to tell when we're done implementing a feature. Since now we have to imagine all the possible ways that the feature might evolve, it's really easy to start getting paranoid and thinking that we are not writing the necessary code to protect our software from the future. The negative impact this has on the confidence we have on our code is huge! And not to mention how unnecessarily long a feature development can get.

Avoid predicting the future. Let's stick to what we know for sure and not make more code than the necessary to fill requirements we currently have at hand.

Know what makes a code base hard to change

In the spirit of avoiding the path of failure to achieve success, let's look at what generally makes a code base really hard to change, and try to figure out a strategy to deal with that.

1. Fear of breaking what's already working
2. Incomprehensible code
3. Highly coupled code

Fear of breaking what's already working

When making a change to an existing code base, the number one risk we're taking is breaking features that already work. Technically speaking, we have to avoid regressions.

Aside from having a huge negative impact in the morale of the development team, regressions can have a devastating impact on the goals that the software is trying to accomplish. If the goal is a business goal, it might mean a big loss of revenue. A single introduced bug might cause hundreds of clients to lose their trust on the software and stop using it, and that's a risk no one wants to take.

Also, if when we're trying to change or add something new, we're breaking what's already working, when will we be finished with our work? The answer might as well be never.

Incomprehensible code

If we want to change some feature on our software, but can't reason about the code we're looking at, how effective can we really be? What if we can't even find the code responsible for making a feature work, because it is scattered all around or due to it being really poorly named?

Code that gives no way for a developer to understand how it works as a whole, and/or how its individuals pieces work, is doomed to be unmaintainable.

Highly coupled code

If we have to change 10s of files to make a small change in our software behavior, we have highly coupled code.

The problem with highly coupled code, besides being hard to understand, is that it takes a lot of time to change. Because we have to figure out all the places we'll need to modify, as well as be careful not to inadvertently modify any other features.

As time goes by, if there's not a conscious effort to prevent it, code bases tend to rot. To deal with this, a code base needs to allow us to make small and continuous improvements to the existing code, without compromising the release of new features. If we've got highly coupled code, we won't be able to do those improvements fast enough not to jeopardize the time to market of new features.

Keeping it maintainable

So now that we've seen what generally makes a code base hard to maintain, let's look at how we can address those concerns.

Fear of breaking what's already working

Fear of breaking what's already working can be mitigated by tests. A well-built and taken care suite of tests can save developers from countless hours of anxiety and despair, as well as save the life of the business that depends on the software working correctly.

It's important that the test suite is mainly composed of automated tests that can be quickly executed. This makes it possible for developers to know if they broke something almost immediately. The test suite should also contain some tests that simulate a user and interact with the system as a whole. Manual testing, as part of a test suite, should be kept to a minimum and reserved to situations where the automation might be prohibitively expensive. After executing all the tests of our test suite, we should have gone through all the possible use-cases for our software.

An automated suite of tests allows us to quickly change our software. Therefore, improving maintainability.

Incomprehensible code

Incomprehensible code comes from not being able to understand what a piece of code intends to do. Some reasons that can happen are:

1. Code organized into huge pieces, that are so big, that it's too much for us to reason about.
2. Code organized in a way that we can't reason about each piece in isolation.
3. Code for a single functionality being scattered all around the code base
4. Misleading names

We can address all the points above if we modularize our code into small independent modules that make sense on their own, and give them a name that reveals what they intend to do.

By keeping our modules small and independent, we avoid our modules being too big for us to understand, as well as allow us to ignore other modules that the current module may interact with. This greatly reduces the cognitive load necessary to understand a code base, because now we can reason about one module at a time.

By grouping our code into modules that we can name in a way that reveal what it intends to do in the context of the software's domain, we are grouping small pieces of code into units that belong together. Otherwise, we wouldn't be able to give our modules meaningful names. This results in code that is easier to understand what it does as a whole, as well as what each single piece does. Also, by following this approach, code that contributes to the same behavior will tend not to be scattered.

Understandable code allows for changes to our software to be made quickly and with confidence. Thus, directly improving its maintainability.

Highly coupled code

When solving the problem of incomprehensible code by organizing our code into small independent modules which make sense on their own, we are already solving the problem of highly coupled code.

Think about it, if we can reason about a piece of code in isolation, that means there is a clear boundary between modules and is easy to understand what each module should do. If we can understand what each module does, and given that it is small, we can safely and quickly refactor it. We can even throw an entire module away and re-write if it needs to be! This kind of modularity allows developers to continuously improve the quality of a code base, without compromising the time to market of new features.

Decoupled code allow us to continuously and quickly improve the quality of our code base. This allows us to renew rotten code that is making our software harder to change as time goes by.

Testing and modular design may not be the only way to keep a code base maintainable. But it certainly is a proven way that works across many kinds of code bases.

Building a strategy to improve code quality

We know that for software to have quality it needs to fill its requirements and it needs to be capable of adapt to future change. We've seen that forecasting is not a good approach to maintainability, and that "Fear of breaking what's working", "Incomprehensible code" and "Highly coupled code" are the main reasons that make a code base unmaintainable. We've also looked at how automated testing and modular design can help us stay away from what makes our code hard to change.

Now, let's organize all of this knowledge into questions that will give us feedback about the quality of our code, and that we can constantly ask ourselves when we are faced with a design decisions or when we've finished implementing or changing a feature.

These questions have the goal of making us check if our code is correct and of maximizing its capacity of changing in the future. If we can answer yes to all the questions, we can have confidence in the quality of our code. So let's go over what each question means and how we can use testing and modular design to answer each one.

1. Does the code do what the requirements ask of it?
2. If a working feature broke, would we quickly know it and be able to easily find out what and where it broke?
3. If we wanted to add, remove or change a feature, would we know exactly where to look?
4. Can we rewrite any feature in a timely manner?

Does the code do what the requirements ask of it?

This question assures our software is doing what it is intended to do. If it doesn't do what is expected, it probably won't be contributing to achieve the established goals. So we can't really call it good quality software.

We can answer this question by relentlessly testing our software and making no assumptions that something works without solid proof of it.

If a working feature broke, would we quickly know it and be able to easily find out what and where it broke?

As we've already talked about, if we want software that can adapt to the future, we need to know when something that was already done, stopped working. We need to know it fast, and we need to be able to fix it quickly.

One way to accomplish this is to have a suite of automated tests that are quick to execute, and that when they fail, point us to the piece of code that is failing. By having a suite of automated tests that points us to the piece of code that is failing, we are also designing our code into small independent modules. Otherwise, we won't be able to tell what part of our code stopped working.

If we wanted to add, remove or change a feature, would we know exactly where to look?

When we want to change the behavior of our software, first we need to know where the code responsible for that behavior is. If we can't tell where it is, we can't really change it.

To achieve this, we can organize our code into modules that we can name in such a way that it's obvious what it does in the context of our software. We should do it at an higher and lower level. When done correctly, our names will work out as road signs that will tell us what our code does and where to look when we want to make changes.

Also, if we were able to give our modules meaningful names, it's likely that we succeed at grouping our code such that the reasons for it to change are the same or very closely related. The result is not having to look at wildly scattered code when wanting to change some behavior. Which makes our task of finding out what needs to change much easier.

Can we rewrite any feature in a timely manner?

As we've already talked about, a code base will change a lot during its lifetime. And as it undergoes many changes, it will start to deteriorate. It might be because we had a wrong understanding of the requirements. Maybe the requirements proved out to not be appropriate to achieve the software goal. Or simply there was not enough time to implement the feature in a none sloppy way. Either way, after the mess is done, we need to be capable of cleaning it in a timely manner. Otherwise, the mess will start to spread out and contaminate every part of the code base. The result of that is a code base that can't be changed.

By timely manner I mean an amount of time that is small enough not to compromise the release of new features. I do not mean that any complete rewrite of a feature should be able to be done in one go, but that we should at least be able to do it little by little without compromising the schedule. It might be hard to convince management that we need a refactor sprint, better if we don't even need to ask for it.

Yet again, organizing our code into small independent modules can allow us to answer yes to this question. If our modules are small we can quickly rewrite them. And if they are independent of one another, we won't have to worry much about breaking any other modules. This allows us to continuously and quickly renew our code base.

When to ask the questions

Let's ask these questions when we're done implementing or changing a feature. Let's also ask them whenever we have decision to make that is not so obvious. If after asking these questions we still don't know which path to take, let's get back to the principle of maximizing the capacity to change.

Conclusion

Next time we're programming, let's remember that every line of code should either contribute to our code correctness or to its maintainability. If we implement a feature in a way that makes it harder for us to change it in the future, we are not helping ourselves.

In order to get feedback about the correctness and maintainability of our code, we can ask ourselves these questions:

1. Does it do what the requirements ask of it?
2. If a working feature broke, would we quickly know it and be able to easily find out what and where it broke?
3. If we wanted to add, remove or change a feature, would we know exactly where to look?
4. Can we rewrite any feature in a timely manner?

If we can answer yes to the questions above and if we keep in mind that our decisions should make our code base easier to change, we can be confident that we have produced good quality code.

As said at the beginning, I didn't go over how to apply these principles in a React app. But if you liked what you read, or have any question, let me know! You can send me a message on twitter at @JooForja.

I hope you liked this article and that it proved useful to you!

1. Analyze the defect and find the broken code.
2. Reproduce the bug in a targeted automated test and fix it.
3. Improve the code design to reduce the likelihood of bugs.
4. Perform root-cause analysis to find the origin of the bug.
5. 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 video 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 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:

1. 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.
2. Why didn't the developer know about race conditions? - It was his first time dealing with API requests, and he did it alone.
3. Why didn't he ask for help from a colleague? - He felt afraid of being judged by his colleagues.
4. 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.

Can't make a query from the browser since CORS blocks it

Whenever we're developing a React application that has to communicate with an API, we'll probably run into Cross-Origin Resource Sharing (CORS) errors. The error message will be similar to this:

Access to fetch at 'http://localhost:8081/auth' from origin 'http://localhost:3000' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://localhost:3000' is therefore not allowed access. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.

A CORS error may happen whenever a web application makes a request for a resource that has a different origin (domain, protocol, or port) from its own. In the case of the error message above, the web app which was served from http://localhost:3000 was making a request for http://localhost:8081/auth. Since the ports are different and localhost:8081 does not allow for CORS request, we got an error. You can read more about CORS here.

Solutions

There are two common ways to solve CORS issues in a development environment:

1. Enable CORS on the API server.
2. Configure a proxy on the development server that's serving the React application.

Depending on the context in which we're developing the application, it might not be possible, or desirable, to configure the API server to allow for CORS. Therefore, adding a proxy tends to be the preferable solution.

The idea behind using a proxy to solve this issue is simple. Instead of making a request directly to the API server, we'll be making a request to the development server and have the development server forward unknown requests to the API server. This way, the React application will be making requests to its own origin, therefore solving the CORS issue.

In order for the proxy solution to work, we need to make sure that the React app is making requests to the development server. So if we were using absolute paths to reach the API server, we'll now use relative ones to make the requests go to the development server instead. So if we have code like fetch('http://localhost:8081/auth'), we'll have to change it to fetch('/auth').

Given we're now making API requests to the development server, all that's left is to configure a proxy so the requests are forwarded to the API server.

How to exactly set up a proxy will depend on the set up of the React application. So I won't be going in detail on that in this article. It is usually easy, so don't worry. If you used Create React App (CRA) to set up your React application, you can check this page of their documentation on how to configure a proxy. If you're serving your React app with webpack-dev-server, this page of the documentation might be helpful. In case you're using other tools, looking up their documentation for proxy or making a google search should do the trick.

By now the CORS issue should be solved. However, if the API server is using https, you may need to configure the development server to use https as well. Yet again, how to do it will depend on the tools you're using. If you've used CRA to setup the application check this page, otherwise check the documentation of the tools you're using.

Conclusion

If you're facing a CORS issue when making a request to your API server, you can fix it with these steps:

1. Make the requests to the API server go to the development server instead.
2. Configure a proxy on the development server to forward unknown requests to the API server.
3. If the API server uses https, configure the development server to use https as well.

All of this testing thing is like I'm in a maze!

If you don't have experience writing tests, getting started can be daunting. Especially if you're trying to test code that interacts with a framework/library like it is when you're testing a React application.

In this article, we'll go over the usual tools to test a React application, how to get unstuck when we don't know how to test a piece of code, and also a basic testing methodology that allows us to get started right away. In the end, there will be an exercise to put into practice what we've covered.

Learning how to write tests is a long process. Don't be discouraged!

Keep in mind that learning how to write tests effectively has a steep learning curve. You'll have doubts about what to test. You won't know how to test some piece of code. You'll under-test. You'll over-test. You'll feel slowed down by testing and start wondering why to do it at all, and eventually, you'll reach a point where you're comfortable writing automated tests and understand the tradeoffs you're making with each test you write.

The struggle is normal, and it's part of the journey, don't be discouraged by it. Keep testing, and it will get better.

Tools

To run and write tests, you'll need support from tools. In the React ecosystem, as of now, the mainstream tools for testing are Jest, React Testing Library and Cypress

Jest is a testing framework that allows you to run your automated tests and also provides you with functions to make assertions, such as "did this function returned the expected value?" or "has this function thrown the expected exception?".

Testing React components has some peculiarities. So the community uses React Testing Library, which is a library that provides utility functions to make testing React components easier.

Cypress is a tool that's normally used to run E2E tests. If you're starting, don't worry too much about learning this tool. You'll be using it the least, and if you feel comfortable using Jest and React Testing Library, it'll be easier to get the hang of Cypress.

To avoid complications setting up a testing environment with Jest, while still getting familiar with the tools, I suggest starting a project with Create React App. It already has Jest configured, and also has excellent documentation on how to run and debug tests.

Recipes

One of the challenges with testing is knowing how to test a particular use-case. Use-cases can be general like data-fetching or triggering events, or more particular like how to test a piece of code that uses React Router. The strategies to handle those use-cases we call testing recipes or testing patterns.

You don't need to know all recipes before starting to write tests. What's important is that you know that the concept of recipes exist and you know where to look for them when you need them.

The best place to find testing recipes is usually the documentation of the tools you're using to write tests and the documentation of the libraries you're using to write your production code.

Testing some code that uses React Router? Check their documentation on testing. Using React Testing Library? Check their guides and recipes. Using React? React also has documentation on testing. And the same goes for Jest.

When you don't know how to test a piece of code or want to find a better way to test it, check the documentation of the tools you're using.

Methodology

Recipes tell you how to test something, but they won't tell you what to test and how to incorporate testing in your development process. That's where a methodology comes in.

Some of the important things about a testing methodology are:

1. Give you confidence that the code you wrote works.
2. Allow you to refactor code without fear of breaking what's working.
3. It makes you more productive on the medium to long term.

Effectively using a testing methodology is the hardest of writing automated. Most of your frustrations and doubts will come from here.

My suggestion when starting is to keep it as simple as possible, so you can start writing tests right away. Usually, the more natural approach is to program a feature or a sub-feature and then write tests for it, so I recommend you start there. You may need to change the code you've written to write tests for it, and that's fine.

If you're not sure what constitutes a feature, think of it as a set of behaviors your user cares about. Are you making an app that lets your user search for movies? Then it's a good idea to have a set of tests that checks the user can search for a movie and see the results of that search, as well as what happens when you don't find any movies or if there was an error.

I use Test-Driven-Development(TDD), so my testing methodology is embedded in this broader development process. Although some people can take it way too far and turn it into a religion, I recommend you try it out with a pragmatic mindset. It helps me know what to test and stay focused on my work. If you're curious about learning TDD, I recommend you read the book Test Driven Development: By example by Kent Beck.

Exercise: Get comfortable with testing tools and documentation

The goal of this exercise is to get you familiar with the tools you'll be using for testing, and also to create the habit of checking documentation for testing recipes. Keep in mind that the tests you'll be writing in this exercise aren't necessarily the tests you'd be writing in a professional application.

1. Read Create React App documentation on running and debugging tests

Even if not everything on those two pages seems useful, finish reading them. It will help breed familiarity with the tools and make them easier to use.

2. Create a React application using Create React App

This application is where you'll be writing your tests.

3. Write a test for an add function

Write a simple add function and then write a test to assert that 6 + 4 = 10. If you're not sure how to assert two values are equal, check Jest's documentation. Now that you've written a test, run it. If you read Create React App documentation on running tests, you should know how to do it.

4. Read React Testing Library Introduction and Example

Reading React Testing Library documentation will give you familiarity with the tool principles and API and thus make you use it better. Yet again, don't worry if not everything makes sense from the start.

Notice that the version of React Testing Library that comes by default with the Create React App may not be the most up to date, so the methods shown in the documentation may not be available to you. To update to the current version of React Testing Library, you'll need to reinstall it. You may also need to update the jsdom version Jest is using. To do that, install the most up to date package of the jsdom environment for Jest, as of now jest-environment-jsdom-sixteen, and change the testing script to use the new environment. It should look something like this: "test": "react-scripts test --env=jest-environment-jsdom-sixteen"

5. Write tests for a React component that adds two numbers

Make a simple React component that allows a user to add two numbers and see the result. Use the add function from before. Keep the UI simple. Two labeled inputs for the numbers, a button to make the addition, and a place to see the result.

Now write a simple test using React Testing Library to assert that the two inputs and the button to perform the addition are rendered. If you've read Jest's documentation on running tests, you've already seen a piece of code that uses what you need for this.

Now write a test that asserts 3 + 4 = 7. For this, you'll need to simulate a user entering numbers and clicking on the button to perform the addition. If you've read Rect Testing Library example, you already know what module from React Testing Library you'll have to use to simulate a user changing an input and clicking on a button. If you're still lost, use the search bar on React Testing Library documentation to look for docs about what you're trying to test.

6. Make your add function async and adapt your code and tests to the change

Make your add function return a Promise of a number instead of a number. The Promise should resolve after 500ms. Also, adapt the React component to work with the now asynchronous add function.

You now have to change the tests for the add function and the React component, since now they're failing.

For the add function, you'll have to change your test to assert the result of a Promise. You may not be sure how to test a function that returns a promise, in which case check the documentation.

For the React component, you'll have to deal with the fact that the result of the addition won't be there right after the user clicks the button. A simple approach to this problem is to wait for the result to appear on the screen. By now, you probably already know where to look for that. But in case you're in doubt, here's the react testing library documentation.

If you've managed to get to the end of this exercise congratulations! You now have some familiarity with the tools involved in the day to day testing of a React application, as well as some experience with testing asynchronous code.

If doing this exercise felt hard and not that straightforward, don't worry. Struggling with the tools and exploring documentation is part of the learning process. Next time it will be easier.

In case you want to check what a solution to this exercise, you can check this gist.

Conclusion

Keep in mind that learning how to write tests effectively has a steep learning curve. Don't be discouraged if it feels like it's hard work.

To effectively write tests, you'll need to know some tools, know where you can find testing recipes, and have a testing methodology established.

If you're struggling with testing a piece of code, look for a solution on the documentation of tools and libraries you're using.

Start with the simple testing methodology of writing automated tests after writing the code for a feature. Test the behavior the user cares about and test enough to make yourself comfortable that the code works. If you want to check other testing methodology, consider reading Test Driven Development: By example

Do the exercise shown in this article so that you get comfortable with testing tools and documentation.

And last but not least, keep writing tests and evaluate the value they're bringing to you and the project. If you do this, the quality of your tests and code will keep improving.

Next steps

One of the challenges of writing automated tests is knowing what to test. And great way to deal with this problem is to learn how to make a test list out of feature requirements.

So if you're looking to improve your testing skills, learning how to make a test list is a great next step to take.

I am quite confused with mocking in Jest. I just want to mock different expected behaviors per test

Although not always possible, a more straightforward approach than mocking a module with Jest is to change the React component to receive the dependency as a prop. This approach allows us to pass a different mock function or mock value per test, without having to worry about the quirks of mocking modules.

So we don't have to change code that uses the component we're testing, we can use default parameters.

Here's how this approach looks like:

import { fetchTodosFromAPI } from './api-client'

function TodosList({ fetchTodos = fetchTodosFromAPI }) {
  // gets todos from fetchTodos() and renders result
}

// tests using react-testing-library
test('shows message when to-do list is empty', () => {
  const fetchEmptyListOfTodos = jest.fn().mockResolvedValue([])
  render(<TodosList fetchTodos={fetchEmptyListOfTodos} />)
  // asserts renders message for empty to-dos list
})

test('shows list with one to-do', () => {
  const fetchListWithOneTodo = jest
    .fn()
    .mockResolvedValue([{ id: 1, title: 'Study testing' }])
  render(<TodosList fetchTodos={fetchListWithOneTodo} />)
  // assert renders single todo
})

test('shows error message when there is a network failure', () => {
  const rejectWithNetworkFailure = jest
    .fn()
    .mockRejectedValue(new Error('Network failure'))
  render(<TodosList fetchTodos={rejectWithNetworkFailure} />)
  // asserts renders error message
})

Put it into practice

1. Change the component to receive the dependency as a prop.
2. Use default parameters to pass the production dependency to the component.
3. Go to your tests, and instead of mocking the dependency module, give a mock function to the component through the new prop.

Although I only referenced React components, this approach also works well for everyday javascript function.

Before we start to develop something, we need to have a good grasp of what it is that we want to build. So let's elaborate a bit more on the context in which we'll implement an infinite scroll and how exactly it should behave.

Context and Requirements

We will implement an infinite scroll in the context of a simple web app, which its goal is to show images from the API Lorem Picsum. The app will have a single page that will work similarly to a feed from a social networking app. But instead of showing posts, it will show images.

The requirements for the infinite scroll app are:

1. Shows images from Lorem Picsum API;
2. While fetching images, the app should show a loading message;
3. If there's an error fetching images, the app should allow the user to retry fetching;
4. Whenever the user has seen all the images on his screen, the app should request new ones;
5. If the user has consumed all the content from the API, the app should show him a message saying so;
6. After the user has seen all the images from the API, the app shouldn't make more API requests;
7. While the app is making an API request, there shouldn't be any more API requests.

Note: If you're curious about how the app will look like, you can take a look at this demo.

States, actions, and transitions

A useful way to structure UIs that have some complexity is as a state machine. For our app, the following states come right up to mind:

1. Idle - The app isn't fetching images.
2. Loading - The app is fetching new images
3. Error - There was an error fetching images.
4. Finished - The app has fetched all images from the API.

We'll need to have actions to transition our app from state to state. The actions that come to mind are:

1. Start Fetch - Fetch new images.
2. Fetch Success - Successfully fetched new images.
3. Fetch Error - There was an error fetching new images.
4. Reached End - The API didn't have more images.

We can represent our states and actions in code using constants:

const startFetch = 'START_FETCH'
const fetchSuccess = 'FETCH_SUCCESS'
const errorFetch = 'FETCH_ERROR'
const reachedEnd = 'REACHED_END'

const idleStatus = 'IDLE'
const errorStatus = 'ERROR'
const loadingStatus = 'LOADING'
const finishedStatus = 'FINISHED'

We also need to define how the states and actions will interact with each other. In other words, we need to set the transitions.

When the app is IDLE, the only action that we'll need to listen to is START_FETCH, and that will cause a transition to LOADING.

The state ERROR is the same as the IDLE on from the perspective of transitions. It also only listens to START_FETCH, which will cause a change to LOADING.

State LOADING listens to the actions FETCH_SUCCESS, FETCH_ERROR, and REACHED_END. On FETCH_SUCCESS it should go to IDLE. On FETCH_ERROR it should go to ERROR. And on REACHED_END it should go to FINISHED.

The state FINISHED is a terminal state. The app won't have any more state changes from there, so it doesn't need to listen to any actions.

Since we're using React and React has the useReducer hook, we'll be representing the state transitions in our code using a reducer.

function infiniteScrollReducer(state, action) {
  switch (state.status) {
    case idleStatus:
    case errorStatus:
      return action.type === startFetch
        ? { ...state, status: loadingStatus }
        : state

    case loadingStatus:
      if (action.type === errorFetch) {
        return { ...state, status: errorStatus }
      }
      if (action.type === reachedEnd) {
        return { ...state, status: finishedStatus }
      }
      if (action.type === fetchSuccess) {
        return {
          ...state,
          status: idleStatus,
        }
      }
      return state
    case finishedStatus:
      return state
    default:
      throw new Error('Unknown state')
  }
}

Fetch images request

Now that we've gone over the states and actions the app will have, let's implement the function that will fetch the images.

Given we need to have an error and a finished state, we need to define what constitutes an error, and what signals that we've reached the end.

We'll consider that there was an error if the API response status is different than 200 or if the request throws an error. We'll assume that we've consumed all images if the API returns an empty array.

Since we're fetching images to show later, we'll need to store them somewhere. The API uses a pagination system, so we'll also have to save the current page as well. Given we're already using a reducer, let's add those values to the reducer state and have the fetch function receive it.

We'll also need the fetch request to dispatch actions, so we'll give it the dispatch function as well.

async function fetchImages(state, dispatch) {
  try {
    const res = await fetch(
      `https://picsum.photos/v2/list?page=${state.pageNumber}&limit=5`,
    )
    if (res.status === 200) {
      const imgs = await res.json()
      if (imgs.length === 0) {
        return dispatch({ type: reachedEnd })
      }
      return dispatch({
        type: fetchSuccess,
        payload: { imagesUrls: imgs.map((i) => i.download_url) },
      })
    } else {
      dispatch({ type: errorFetch })
    }
  } catch (e) {
    dispatch({ type: errorFetch })
  }
}

To wrap up this part of our code, all we have left to do is to store the newly retrieved images and to increment the page number if the request was successful. We can handle that at the reducer.

 case loadingStatus:
      //code to handle other actions
      ...
      if (action.type === fetchSuccess) {
        return {
          ...state,
          imagesUrls: [...state.imagesUrls, ...action.payload.imagesUrls],
          pageNumber: state.pageNumber + 1,
          status: idleStatus
        };
      }

Trigger images fetch

To fulfill the requirements, we need to fetch and show new images when the user has seen all the current ones. Which pops up the question "How do we know the user has seen all the images?"

A common approach is to check the scroll bar position. If the scroll bar is at the end of the page, the user has seen all content. However, this approach takes for granted that we'll fetch enough images from the start to fill up the height of the user's screen, thus creating a scroll bar. Depending on the height of the user's screen, this might not be true.

A more robust approach is to use the browser's Intersection Observer API.

Intersection Observers allow us to know when an element is being shown on the screen. So what we'll do is have an HTML element that will be after the last image shown to the user. If that element appears on the screen, we know the user as seen all the images. Let's call that element borderBottom.

When the Intersection Observer notifies us that borderBottom is showing, we want to fetch new images, so we should dispatch START_FETCH.

To use an Intersection Observer on a React component, we need to have the borderBottom HTML element. To do that we'll use a callback ref. After React creates the HTML element of borderBottom, it will call the callback ref, and we'll check for when borderBottom becomes visible to the user through an Intersection Observer. This approach results in the following:

const observeBorder = useCallback(node => {
    if (node !== null) {
      new IntersectionObserver(
        entries => {
          entries.forEach(en => {
            if (en.intersectionRatio === 1) {
              dispatch({ type: startFetch });
            }
          });
        },
        { threshold: 1 }
      ).observe(node);
    }
  }, []);

function renderBottomBorder() {
    return <div ref={observeBorder} />;
  }

The only thing that's left to do is the actual API call.

useEffect(() => {
  if (state.status === loadingStatus) {
    fetchImages(state, dispatch)
  }
}, [state])

By giving state as a dependency to useEffect hook, we get the possibility to execute a function when entering a new state. For our app, we only want to execute a function when entering LOADING. So we check that we're now loading and fetch new images. We must be careful not to change the identity of the object state, unless we're changing the state of the app. Otherwise, we'll be triggering the useEffect callback. Which, in our case, might result in doing API calls while the app is loading. This is especially easy to happen when implementing the reducer. All it takes is to return {...state} instead of state on default cases.

Views

We're almost done. All that's left is to render the images, messages, and the error button when the state is appropriate. Also, remember that the user should be able to click the error button to fetch the images again. So we'll have to dispatch an action when the user clicks the button.

return (
    <>
      {renderImages()}
      {state.status === errorStatus && renderErrorRetryButton()}
      {state.status === loadingStatus && renderLoadingMessage()}
      {state.status === finishedStatus && renderNoMoreImagesMessage()}
      {renderBottomBorder()}
    </>
  );

  function renderBottomBorder() {
    return <div ref={observeBorder} />;
  }

  function renderNoMoreImagesMessage() {
    return <p>There aren't more images</p>;
  }

  function renderImages() {
    return state.imagesUrls.map(url => (
      <img key={url} style={imageStyle} src={url} alt="mock alt" />
    ));
  }

  function renderErrorRetryButton() {
    return (
      <button type="button" onClick={() => dispatch({ type: startFetch })}>
        Error! Click to try again
      </button>
    );
  }

  function renderLoadingMessage() {
    return <p>Loading...</p>;
  }

End result

We've implemented all the pieces of the app. Let's take a look at the final result.

const startFetch = "START_FETCH";
const fetchSuccess = "FETCH_SUCCESS";
const errorFetch = "FETCH_ERROR";
const reachedEnd = "REACHED_END";

const idleStatus = "IDLE";
const errorStatus = "ERROR";
const loadingStatus = "LOADING";
const finishedStatus = "FINISHED";

function infiniteScrollReducer(state, action) {
  switch (state.status) {
    case idleStatus:
    case errorStatus:
      return action.type === startFetch
        ? { ...state, status: loadingStatus }
        : state;

    case loadingStatus:
      if (action.type === errorFetch) {
        return { ...state, status: errorStatus };
      }
      if (action.type === reachedEnd) {
        return { ...state, status: finishedStatus };
      }
      if (action.type === fetchSuccess) {
        return {
          ...state,
          imagesUrls: [...state.imagesUrls, ...action.payload.imagesUrls],
          pageNumber: state.pageNumber + 1,
          status: idleStatus
        };
      }
      return state;
    case finishedStatus:
      return state;
    default:
      throw new Error("Unknown state");
  }
}

async function fetchImages(state, dispatch) {
  try {
    const res = await fetch(
      `https://picsum.photos/v2/list?page=${state.pageNumber}&limit=5`
    );
    if (res.status === 200) {
      const imgs = await res.json();
      if (imgs.length === 0) {
        return dispatch({ type: reachedEnd });
      }
      return dispatch({
        type: fetchSuccess,
        payload: { imagesUrls: imgs.map(i => i.download_url) }
      });
    } else {
      dispatch({ type: errorFetch });
    }
  } catch (e) {
    dispatch({ type: errorFetch });
  }
}

const initialState = { imagesUrls: [], status: idleStatus, pageNumber: 1 };

function InfiniteScroll() {
  const [state, dispatch] = useReducer(infiniteScrollReducer, initialState);
  useEffect(() => {
    if (state.status === loadingStatus) {
      fetchImages(state, dispatch);
    }
  }, [state]);

  const observeBorder = useCallback(node => {
    if (node !== null) {
      new IntersectionObserver(
        entries => {
          entries.forEach(en => {
            if (en.intersectionRatio === 1) {
              dispatch({ type: startFetch });
            }
          });
        },
        { threshold: 1 }
      ).observe(node);
    }
  }, []);

  return (
    <>
      {renderImages()}
      {state.status === errorStatus && renderErrorRetryButton()}
      {state.status === loadingStatus && renderLoadingMessage()}
      {state.status === finishedStatus && renderNoMoreImagesMessage()}
      {renderBottomBorder()}
    </>
  );

  function renderBottomBorder() {
    return <div ref={observeBorder} />;
  }

  function renderNoMoreImagesMessage() {
    return <p>There aren't more images</p>;
  }

  function renderImages() {
    return state.imagesUrls.map(url => (
      <img key={url} style={imageStyle} src={url} alt="mock alt" />
    ));
  }

  function renderErrorRetryButton() {
    return (
      <button type="button" onClick={() => dispatch({ type: startFetch })}>
        Error! Click to try again
      </button>
    );
  }

  function renderLoadingMessage() {
    return <p>Loading...</p>;
  }
}

const imageStyle = {
  width: "300px",
  height: "200px",
  display: "block",
  marginBottom: "20px"
};

Considerations

Since we're dealing with images in the context of our app, we could have done some further optimizations. Lazy loading images and making them responsive being two that come right up to my mind. But given the focus of this article is on implementing infinite scroll, I left that part out of the scope.

Another vital thing that I didn't go over in this article is how to test this implementation. The way I prefer to do it is actually to start out by writing tests and then the implementation. However, I couldn't manage to mirror that process in this article while keeping it at a reasonable size and understandable. Instead, I opted to leave a link to a Repository where you can find this app and the tests to it. In the future, I might write an article on how to test/test drive this app.

I hope that this approach of defining the requirements, followed by designing architecture and then going over to implementation, made sense to you. It's an approach that has proved useful to me time and time again.

If you enjoyed this article, you might also like this one about how to perform a search when a user stops typing using React and Hooks.

How do I pass state to a child component? How can I get state from a child component to a parent?

A decision we constantly have to make when developing a React app, is how to share state between multiple component. There are a lot of tools and patterns that we can use to tackle this problem. However, sometimes we can get to a better solution by removing instead of adding.

If you don't have multiple components, you don't have to worry about passing state between them.

Ask yourself, do I really need this to be a component?

If you don't intend on reusing it across multiple different components, and it isn't so complex that it's hard to reason unless it is isolated, then you probably don't need it to be it's own component.

As an alternative, to keep your code readable, we can just have our previous child components be variables inside the parent component. Using this method all previous components will have direct access to the intended state, which means we no longer have to worry about passing it.

Below is an example of what it looks like to use variables instead of components.

function CounterPage() {
  const [counter, setCounter] = useState(0)

  const header = (
    <header>
      <h1>This is a page for a counter</h1>
    </header>
  )

  const counterValueSection = (
    <section>
      <h2>Counter value</h2>
      <p>{counter}</p>
    </section>
  )

  const counterControllersSection = (
    <section>
      <h2>Counter controllers</h2>
      <button type="button" onClick={() => setCounter((c) => c + 1)}>
        +
      </button>
      <button type="button" onClick={() => setCounter((c) => c - 1)}>
        -
      </button>
    </section>
  )

  return (
    <div>
      {header}
      {counterValueSection}
      {counterControllersSection}
    </div>
  )
}

Next time you're faced with the decision of how to pass state between components, ask yourself if you really need to have multiples components, or if they can just be one.

You'll be amazed by how easy your life will get if you try to solve problems by removing instead of adding.

What if the browser gets Refreshed? How do we keep the state persistent?

Sometimes it is necessary to keep the state of a React component persistent even after a browser refresh. A simple way to accomplish this without having to rely on any third party library, is to use the localStorage API together with useEffect hook.

Making state persistent

Let's say we want to build a counter component which its state should persist after a page refresh. Starting out, our component would look something along these lines:

function Counter() {
  const [count, setCount] = useState(0)

  return (
    <div>
      <div>{count}</div>
      <button onClick={() => setCount((c) => c + 1)}>+</button>
      <button onClick={() => setCount((c) => c - 1)}>-</button>
    </div>
  )
}

First, we want to save the value of count to the local storage every time it changes. For that we'll use useEffect hook.

function Counter() {
  const [count, setCount] = useState(0)

  useEffect(() => {
    localStorage.setItem('count', String(count))
  }, [count])

  return (
    <div>
      <div>{count}</div>
      <button onClick={() => setCount((c) => c + 1)}>+</button>
      <button onClick={() => setCount((c) => c - 1)}>-</button>
    </div>
  )
}

If you try to refresh you app right now, you'll notice that the value of the counter is still not persistent. However, if you inspect the local storage, you'll notice that count is being stored. Now we only need to pass the value of count to the counter component before it has been rendered for the first time. To do that, we'll pass the value in local storage as the initial state of useState.

function Counter() {
  const storedValueAsNumber = Number(localStorage.getItem('count'))
  const [count, setCount] = useState(
    Number.isInteger(storedValueAsNumber) ? storedValueAsNumber : 0,
  )

  useEffect(() => {
    localStorage.setItem('count', String(count))
  }, [count])

  return (
    <div>
      <div>{count}</div>
      <button onClick={() => setCount((c) => c + 1)}>+</button>
      <button onClick={() => setCount((c) => c - 1)}>-</button>
    </div>
  )
}

Using the Number constructor is necessary, since an item retrieved from local storage comes as a string. Since a user can change the number persisted to the local storage to any arbitrary value, it's a good idea to check if the retrieved value is actually an integer.

Considerations about this solution

By using this solution, we're actually creating shared mutable state between all instances of the Counter component. This might or might not be a problem depending on the specific situation. As a rule of thumb, if we want to reuse a component across an application, this is not a good approach. However, remember to always think things through according to your current situation. No rule of thumb is better than a well done analysis of the situation that is right in front of you.

For this example, we used the string count as key for our counter value. On a real world application, we may want to use a unique ID to make sure we are not using and/or overriding any value that is being stored at the local stored. A key such as count-mhvXdrZT4jP5T8vBxuvm75 would be appropriate.

As an alternative, if we don't want different instances of the Counter component to share state, we could receive the key for the local storage as a prop to the component.

Give it a try

Next time you're faced with having to make a React component's state persistent across a browser refresh, remember to:

1. Analyze your current situation to check if using Local Storage together with useEffect hook is appropriate
2. Get a unique key to store your component state in order to avoid collisions at the Local Storage
3. Add the necessary useEffect hook to update your component's persisted state

index.js keeps failing in my test coverage report

When we start a project with Create React App and set test coverage thresholds, index.js file becomes a problem since it prevents us from hitting the configured thresholds.

We can solve this by writing the following test for index.js and get 100% test coverage on it.

// index.test.js
import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'

// mocks react-dom and its render method
// so that we can assert that render is
// called with <App /> and HTML element with id = root
jest.mock('react-dom', () => ({ render: jest.fn() }))

test('renders with App and root div', () => {
  // Create and append to document body
  // an HTML element with id = root
  const root = document.createElement('div')
  root.id = 'root'
  document.body.appendChild(root)

  // Requires index.js so that react-dom render method is called
  require('./index.js')

  // Asserts render was called with <App />
  // and HTML element with id = root
  expect(ReactDOM.render).toHaveBeenCalledWith(<App />, root)
})

// index.js
import React from 'react'
import ReactDOM from 'react-dom'
import './index.css'
import App from './App'

ReactDOM.render(<App />, document.getElementById('root'))

However, an important question to ask before we write a test is "What are we trying to achieve with this test?".

When we write tests, we should write them with a clear vision of their goals, and not just for the sake of test coverage.

The code above tests that index.js does what we expect of it. But it doesn't test that the application starts, and maybe that's what we want to check.

To test that the application starts without problems, we can write an E2E test that asserts an element of the home page is rendered. We can use a tool like Cypress for that.

Writing the E2E test and a test specifically for index.js are not mutually exclusive approaches, and we should do both if that gives us more confidence that our application is working correctly. But I'd argue that since an E2E test covers 100% of index.js and since index.js is easy to understand, that writing a test just for it ends up being redundant.

If you end up going with only doing the E2E test, you'll need to remove index.js from the test coverage report. Otherwise, you won't meet the test coverage threshold. To do that, add the option below to package.json.

"jest": {
"collectCoverageFrom": [
    "src/**/*.{js,jsx,ts,tsx}",
    "!src/index.js"
  ],
  ...
}

Put it into practice

1. Define what you want to test.
2. If it is that the application starts, write an E2E test, and remove index.js from the test coverage.
3. If it is that index.js does what is expected, write a targeted test like the one shown in this article.
4. If you want to test both, write the E2E test and the targeted index.js test.

To illustrate the process, we'll test a component that scrolls to the top of the page whenever there's a change in the current route.

// Uses React router, Jest and react testing library
function ScrollToTop({ children, scrollTo = window.scrollTo }) {
  const prevLocation = useRef(null)
  const location = useLocation()
  useEffect(() => {
    if (prevLocation.current && location !== prevLocation.current) {
      scrollTo(0, 0)
    }
    return () => (prevLocation.current = location)
  }, [location, scrollTo])
  return children
}
// NOTE: This implementation serves the purpose of supporting this article.
// It doesn't have production concerns in mind.

To test the code above, we'll have to figure out how to simulate a change in the current route. We could try to mock useLocation and return different values each time we call it, but this approach exposes to our test that we use the useLocation hook. This means that if we refactor ScrollToTop not to use useLocation, our tests will break. A more robust way to write this test is to recreate the environment in which ScrollToTop will be used and trigger a route change similarly to how a user would.

For our test, we'll start by wrapping ScrollToTop in a Router and have it render two routes. The first route will have a link that points to the second route, and the second route will have some text. Then we'll simulate a click on the link of the first route and wait for the text on the second route to appear. After that, all that's left is to assert that we've scrolled to the top of the page.

To assert we've scrolled to the top of the page, we'll mock the scrollTo function and check that we called it with the coordinates that correspond to the top of the page. You might be wondering if this approach has the same issues that mocking useLocation had. The answer is that it does, but we don't have a better option. Since Jest uses JSDOM to simulate a browser, and since JSDOM doesn't implement window.scrollTo the best we can do in this environment is to mock scrollTo and confirm we're calling it correctly.

This approach results in the test bellow.

test('Scrolls to top of page when route changes', async function test() {
  const scrollTo = jest.fn()
  render(
    <MemoryRouter initialEntries={['/']}>
      <ScrollToTop scrollTo={scrollTo}>
        <Route exact path="/">
          <Link to={'/other'}>Change route</Link>
        </Route>
        <Route exact path="/other">
          <p>Other route</p>
        </Route>
      </ScrollToTop>
    </MemoryRouter>,
  )
  fireEvent.click(screen.getByText('Change route'))
  await screen.findByText('Other route')

  expect(scrollTo).toHaveBeenCalledTimes(1)
  expect(scrollTo).toHaveBeenLastCalledWith(0, 0)
})

Put it into practice

We can look at the work we did to test ScrollToTop as the following 4 step process:

1. Recreate a routing environment similar to that in which the component will be used.
2. Perform an action that causes navigation between routes.
3. Assert that the navigation was done.
4. Assert the component under test behaved as expected.

Next time you have to test a component that exhibits some behavior when a route changes, try the steps above.

Exercise: test component that shows an alert when routes change

Try to use the process delineated in this article to test the following component that creates an alert with the message "Hello world!" when there's a change in the current route.

function AlertOnRouteChange({ children, message, alert = window.alert }) {
  const prevLocation = useRef(null)
  const location = useLocation()
  useEffect(() => {
    if (prevLocation.current && location !== prevLocation.current) {
      alert('Hello world!')
    }
    return () => (prevLocation.current = location)
  }, [alert, location])
  return children
}

test('Alerts when route changes', async function test() {
  const alert = jest.fn()
  render(
    <MemoryRouter initialEntries={['/']}>
      <AlertOnRouteChange alert={alert}>
        <Route exact path="/">
          <Link to={'/other'}>Change route</Link>
        </Route>
        <Route exact path="/other">
          <p>Other route</p>
        </Route>
      </AlertOnRouteChange>
    </MemoryRouter>,
  )
  fireEvent.click(screen.getByText('Change route'))
  await screen.findByText('Other route')

  expect(alert).toHaveBeenCalledTimes(1)
  expect(alert).toHaveBeenLastCalledWith('Hello world!')
})

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:

1. Preparation before writing tests
2. Defining boundaries for testing
3. 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:

1. Shows an empty message when there aren't characters
2. Shows one character with expected info
3. Shows three characters, each with the expected info
4. 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:

1. Shows an empty message when there aren't characters
2. 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:

1. 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.
2. 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.
3. 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.
4. 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.

How in general should I know what to test?

During the daily meeting with your team, you find out that the client wants a new feature, and you're in charge of implementing it. You've wanted to write automated tests for a while, and this seems like an excellent opportunity. But where do you start? What tests should you even write?

In this article, we'll go over a process to turn a feature request into a list of tests that we can automate and use to help us in our development process. We'll start by looking at the requirements for the feature, and then go over the goals we want to achieve with the tests we'll be writing. After that, we'll make a more thorough analysis of the requirements that will allow us to write the test list.

The feature we'll be implementing

The goal of the feature is to allow users to see information about characters from Rick and Morty. More specifically, the user should be able to:

1. See a character name, picture, species, gender, and status (Alive/Dead/Unknown).
2. Search characters for their name.
3. Search characters for their status (Alive/Dead/Unknown).
4. See the characters in a paginated fashion.

We're also told that there's an API that will give us the character information.

Goals for the tests

When writing a test list, we need to keep in mind the goals of the tests. Otherwise, we'll be lost, and we won't know what tests to write. The main objectives are:

1. Document the feature - After someone has read the tests, he/she should know the behaviors of the feature.
2. Prevent errors now and/or in the future - Whenever the feature stops working, tests should tell us.

Notice that I didn't put "finding unexpected bugs" as a goal for the tests of the test list. That's because trying to think about possible bugs for a feature that doesn't exist yet is extremely hard, time-consuming, and ineffective.

A better approach to find unexpected bugs in a feature is to build the feature worrying only about filling the given requirements and then use a technique like Exploratory Testing to find bugs.

Making the test list

By making a test list, we're looking to discover a set of examples that define essential behaviors of the feature. Those examples will then guide the automated tests we'll write, and by consequence, the implementation of the feature.

The test list is not something that we do once before implementing a feature, and we're done with it. While developing, we'll discover new behaviors that we'll want to test. When that happens, we should add the new test to the test list, so we don't forget about it.

Since we probably won't know every test we should have on our test list before starting to implement the feature, it's not worth it being too exhaustive. If we've got a couple of tests and we've been thinking about more examples for a minute and can't find new ones, we're in a good place to start writing code.

Decompose the feature

Depending on the size of the feature, knowing which tests to write first can be hard. One solution is to decompose it into smaller sub-features that we know how to write tests for.

Helpful questions to ask when trying to decompose a feature are "What's the simplest version of this feature that will still mean progress?" and "What's the behavior of this feature that without nothing else makes sense?". By answering these questions, we'll instinctively start to decompose the feature into sub-features, and we'll get to the core behavior(s). After we get to the core, we should be able to plan tests for it.

If we analyze the requirements for our Rick and Morty characters feature, we can decompose it into at least three sub-feature:

1. Search for characters by name and status
2. Show the characters' information
3. Shows characters in a paginated format

The core behavior for this example is "Show the characters' information". Without that, searching for characters and pagination doesn't make sense. Also, the application showing the characters' information means substantial progress towards the completion of the feature.

We have already concluded that the sub-feature "Show the characters' information" is a good place to start. And from the requirements, we also know that for each character, we need to show its name, picture, gender, and status. But besides asserting that the application shows the expected information, what other tests can we write?

Look at the inputs and outputs for test ideas

A great way to find tests is to look at the inputs and outputs of a feature and ask, "What values can the inputs have, and how does that affect the outputs?"

If we analyze our sub-feature, we can consider that there are one main input and one main output. The main input is the API response with the list of Rick and Morty characters. The main output is the information about the characters.

So what kind of values can the list of characters have, and how will that influence what we show to the user? Since we're dealing with a collection, we can use the "Zero One Many Lots Oops" analysis.

The idea of "Zero One Many Lots Oops" is to make us question what happens when:

1. The collection is empty
2. Only has one item
3. Has multiple items
4. Has a vast number of items
5. There's an error trying to get the collection.

Looking at situation 1 makes us wonder if the API can return 0 characters, and what to do if that happens. I'm not entirely sure if that can happen, so to stay on the safe side, let's prepare the app for it and show a message. So we should write a test that asserts the app shows a message if the API returns an empty list.

Situations 2 and 3 represent common success paths for our sub-feature, so we want to write some tests to tell us if they stop working.

Since we won't work on pagination right now, we won't worry about situation 4. We'll assume that if we can show a small number of characters, like 3, we can also display a large number like 250. We can always get back to this in the end if it gives us more confidence that the application works.

Situation 5 makes us deal with errors. What kind of errors can happen? Should we distinguish between them or not? For our particular example and to not make this overly complicated, we'll treat any HTTP response besides a 200 as an error and don't distinguish between them. If an error happens, we just show a message to the user saying he/she has to reload the application.

The test list

So we've gone over the basic requirements, we settled on the core behavior of the feature and we also did an input output analysis aided by the "Zero One Many Lots Oops" methodology to help us find interesting test cases. That lead us to the following tests:

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

Remember that this is by no means an exhaustive list, but it is enough to get us started and to produce something of value when we're done making these tests pass. While we're implementing these tests and writing the code for them, we'll surely remember more use cases that should be tested. When that happens we write those down and implement them when we find it appropriate.

After we're finished with these tests and others that may appear during development, we go back to the feature requirements and repeat the process for the search behavior and the pagination behavior.

Put it into practice

Next time you'll be implementing a feature, follow these steps to help you produce a test list that can get you started testing and developing:

1. Go over the requirements.
2. Decompose the feature into sub-features and start with the core one. If it's not possible to decompose, start with what you have.
3. Analyze the feature inputs and outputs to get test ideas.
4. Turn the requirements and input/output analysis into a list of tests and start developing. Don't worry if the list is thorough. You'll find more test-cases as you implement the feature.
5. One by one, make the tests pass.
6. If there are other sub-features, go back to them and repeat the process.

If after applying steps 1, 2, and 3 you don't know where to start, chances are you're not sure about what the feature should do. Try to clarify the requirements with the management team if that's the case.

Exercise: test list for the search sub-feature

If you want an exercise to put the above steps into practice, try to make a test list for the search behavior of the Rick and Morty feature. You can find the test list I'd write for that sub-feature at the end of this section.

Don't worry if your test list doesn't match mine exactly. What's important is that the relevant input/output combinations are covered.

Implementing the tests

Do you want to know how the actual code for the tests would look like? Then you will like this article.

I plan to keep updating this Cheat Sheet as more meaningful recipes come to mind. If you'd like to be notified of updates to this cheat sheet, you can subscribe to the newsletter at the bottom of this article.

Note: Keep in mind that the components or hooks under test aren't production-ready and that their only purpose is to illustrate how to test a particular behavior.

Table of Contents

1. Invokes given callback
2. Changes current route
3. High Order Component
4. Component cleans up on unmount
5. Depends on Context Provider
6. Uses functions that depend on time
7. Custom hooks
8. Portal
9. Focus is on correct element
10. Order of elements
11. Selected Option
12. Dynamic page titles
13. Other resources

Invokes given callback

• We're testing that after some interaction the component calls a given callback.
• We give a mock function to the component under test and interact with it so that it calls the callback. Then we assert we called the function with the expected parameters. If relevant, we also check the number of times the function was called.

import React from 'react'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

test('callback is called on button click', function test() {
  const callback = jest.fn()
  render(<Button action={callback} />)

  userEvent.click(screen.getByRole('button', { name: /call/i }))

  expect(callback).toHaveBeenCalledTimes(1)
  expect(callback).toHaveBeenCalledWith()
})

function Button({ action }) {
  return <button onClick={() => action()}>Call</button>
}

Changes current route

• We're testing that the component redirects the user to an expected router with the expected query parameters after an interaction.
• We first create a routing environment similar to that in which we'll use the component. We set up that environment so we can capture the URL to which the component will redirect us. We interact with the component to cause the redirect. We then assert that we were redirected to the URL we expected.

import React, { useState } from 'react'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { MemoryRouter, Route, useHistory } from 'react-router-dom'

test('On search redirects to new route', async function test() {
  let location
  render(
    <MemoryRouter initialEntries={['/']}>
      <Route path="/">
        <SearchBar />
      </Route>
      <Route
        path="/*"
        render={({ location: loc }) => {
          location = loc
          return null
        }}
      />
    </MemoryRouter>,
  )

  await userEvent.type(screen.getByLabelText(/search/i), 'react')
  userEvent.click(screen.getByRole('button', { name: /submit/i }))

  expect(location.pathname).toEqual('/search-results')
  const searchParams = new URLSearchParams(location.search)
  expect(searchParams.has('query')).toBe(true)
  expect(searchParams.get('query')).toBe('react')
})

function SearchBar() {
  const history = useHistory()
  const [query, setQuery] = useState('')

  return (
    <form
      onSubmit={function redirectToResultsPage(e) {
        e.preventDefault()
        history.push(`/search-results?query=${query}`)
      }}
    >
      <label htmlFor="query">search</label>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.currentTarget.value)}
        id="query"
      />
      <input type="submit" value="go" />
    </form>
  )
}

High Order Component

• We're testing that a HOC gives the props we expect to the wrapped component.
• We first create a mock component for the HOC to wrap. The mock component will store the received props in a variable. After rendering the component returned by the HOC we assert that it gave the mock component the props we expected.

import React from 'react'
import { render } from '@testing-library/react'

test('Adds number and gives result as a prop', function test() {
  let result
  function WrappedComponent({ sum }) {
    result = sum
    return null
  }
  const ComponentWithSum = withSum(WrappedComponent, [4, 6])
  render(<ComponentWithSum />)

  expect(result).toBe(10)
})

function withSum(WrappedComponent, numbersToSum) {
  const sum = numbersToSum.reduce((a, b) => a + b, 0)
  return () => <WrappedComponent sum={sum} />
}

Component cleans up on unmount

• We want to assert that a component subscribes after mount and unsubscribes after unmount.
• We start by mocking the subscription methods so we can assert they get called. We then render the component and assert that it subscribed. All that's left to do is make the component unmount and assert it unsubscribed.

import React, { useEffect } from 'react'
import { render } from '@testing-library/react'

test('Subscribes and unsubscribes when appropriate', function test() {
  const subscriptionService = {
    subscribe: jest.fn(),
    unsubscribe: jest.fn(),
  }

  const { unmount } = render(
    <ComponentThatSubscribes subscriptionService={subscriptionService} />,
  )

  expect(subscriptionService.subscribe).toHaveBeenCalledTimes(1)
  expect(subscriptionService.subscribe).toHaveBeenCalledWith()

  unmount()

  expect(subscriptionService.unsubscribe).toHaveBeenCalledTimes(1)
  expect(subscriptionService.unsubscribe).toHaveBeenCalledWith()
})

function ComponentThatSubscribes({ subscriptionService }) {
  useEffect(() => {
    subscriptionService.subscribe()
    return () => subscriptionService.unsubscribe()
  }, [subscriptionService])
  return null
}

Depends on Context Provider

• We want to test a component that depends on a context Provider
• To test the component, we'll recreate the environment in which we'll use the component. In other words, we'll wrap the component in the Context Provider.

import React, { useContext } from 'react'
import { render, screen } from '@testing-library/react'

test('displays name of current user', function test() {
  render(
    <UserContext.Provider value={{ user: { fullName: 'Giorno Giovanna' } }}>
      <UserFullName />
    </UserContext.Provider>,
  )
  expect(screen.getByText('Giorno Giovanna')).toBeVisible()
})

const UserContext = React.createContext()

function UserFullName() {
  const { user } = useContext(UserContext)
  return <p>{user.fullName}</p>
}

Uses functions that depend on time

• We want to test a component that depends on real-time. In this example, that dependency comes from using setTimeout().
• When testing components that depend on real-time, we need to be aware that those tests shouldn't take too long. One way to do that is to have the component receive the time interval as a prop to allow us to configure a shorter time interval for tests than we would have in production.

import React, { useState, useEffect } from 'react'
import {
  render,
  screen,
  waitForElementToBeRemoved,
} from '@testing-library/react'

test('Changes from red to green to after timeout', async function test() {
  render(<TrafficLight timeUntilChange={10} />)

  expect(screen.getByText(/red/i)).toBeVisible()
  await waitForElementToBeRemoved(() => screen.getByText(/red/i))
  expect(screen.getByText(/green/i)).toBeVisible()
})

function TrafficLight({ timeUntilChange = 500 }) {
  const [light, setLight] = useState('Red')
  useEffect(() => {
    setTimeout(() => setLight('Green'), timeUntilChange)
  }, [timeUntilChange])
  return <p>{light}</p>
}

Custom hooks

• We want to test a custom hook.
• Since we're testing a hook, we'll need to call it inside a component otherwise we'll get an error. Therefore, we'll create a mock component, use the hook inside it, and store what the hook returns in a variable. Now we can assert what we need to assert using that variable.

import React, { useState, useCallback } from 'react'
import { render, act } from '@testing-library/react'

test('counter increments', function test() {
  let counter
  function MockComponent() {
    counter = useCounter()
    return null
  }

  render(<MockComponent />)

  expect(counter.count).toEqual(0)
  act(() => counter.increment())
  expect(counter.count).toEqual(1)
})

function useCounter() {
  const [count, setCount] = useState(0)
  const increment = useCallback(() => setCount((x) => x + 1), [])
  return { count, increment }
}

• Another approach is to use react hooks testing library.

import React, { useState, useCallback } from 'react'
import { renderHook, act } from '@testing-library/react-hooks'

test('counter increments with react hooks testing library', function test() {
  const { result } = renderHook(() => useCounter())
  expect(result.current.count).toBe(0)
  act(() => result.current.increment())
  expect(result.current.count).toBe(1)
})

function useCounter() {
  const [count, setCount] = useState(0)
  const increment = useCallback(() => setCount((x) => x + 1), [])
  return { count, increment }
}

• If you're looking for more examples on how to test react hooks, I recommend you take a look at the usage section of the react hooks testing library documentation. They have excellent documentation on how to deal with other use cases like errors and asynchronous updates.

Portal

• We want to test a component that's a portal.
• A portal needs a DOM node to be rendered into. So to test it, we'll have to create that DOM node. After we make the assertions, we'll have to remove the DOM node as not to affect other tests.

import React, { useRef, useEffect, useState } from 'react'
import ReactDOM from 'react-dom'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

test('PortalCounter starts at 0 and increments', function test() {
  const modalRoot = document.createElement('div')
  modalRoot.setAttribute('id', 'modal-root')
  document.body.appendChild(modalRoot)

  render(<PortalCounter />)

  expect(screen.getByTestId('counter')).toHaveTextContent('0')
  userEvent.click(screen.getByRole('button', { name: 'inc' }))
  expect(screen.getByTestId('counter')).toHaveTextContent('1')

  document.body.removeChild(modalRoot)
})

function PortalCounter() {
  const el = useRef(document.createElement('div'))
  const [count, setCount] = useState(0)

  useEffect(() => {
    const modalRoot = document.getElementById('modal-root')
    const currentEl = el.current
    modalRoot.appendChild(currentEl)
    return () => modalRoot.removeChild(currentEl)
  }, [])

  return ReactDOM.createPortal(
    <>
      <section aria-live="polite">
        count: <span data-testid="counter">{count}</span>
      </section>
      <button type="button" onClick={() => setCount((c) => c + 1)}>
        inc
      </button>
    </>,
    el.current,
  )
}

Focus is on correct element

• We want to test that the focus on the element we expect.
• We can verify if an element has focus or not by using toHaveFocus().

import React from 'react'
import { render } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

test('clicking on label gives focus to name input', () => {
  const { getByText, getByLabelText } = render(<NameForm />)

  const nameLabel = getByText('Name')
  userEvent.click(nameLabel)

  const nameInput = getByLabelText('Name')
  expect(nameInput).toHaveFocus()
})

function NameForm() {
  return (
    <form>
      <label htmlFor="name">Name</label>
      <input id="name" type="text" />
    </form>
  )
}