DEV Community: Derek N. Davis

Stop Serving Context Soup with Your React Testing Library Tests

Derek N. Davis — Fri, 30 Jul 2021 16:11:48 +0000

If you've worked on a production React app for any amount of time, you've probably noticed the accumulation of Provider components that wrap the top level component. When it comes to writing tests, these contexts become an extra hurdle to set up new test files.

We have to make sure all useContext usages in the component are covered. One missing Provider, and we get failing tests.

// don't forget one!
render(
  <GlobalCacheProvider>
    <I18nProvider i18n={i18n}>
      <NotificationProvider>
        <UserScreen />
      </NotificationProvider>
    </I18nProvider>
  </GlobalCacheProvider>
);

And what happens when there's a new global context added?

We have a couple options:

Add it it to all the test suites hoping we don't miss one.
Go the lazy route and only add it to the test suite using it. This creates a landmine for our coworkers (or our future selves), so when they use the new context, the tests are missing the Provider and fail. Gee, thanks!

We can solve both of these problems with one solution.

The Context Wrapper

Let's create a wrapper component called GlobalTestProvider that includes all our global context Provider components.

function GlobalTestProvider({ i18n, children }) {
  return (
    <GlobalCacheProvider>
      <I18nProvider i18n={i18n}>
        <NotificationProvider>
          {children}
        </NotificationProvider>
      </I18nProvider>
    </GlobalCacheProvider>
  );
}

Then the line to render the component becomes much more palatable:

render(
  <GlobalTestProvider i18n={i18n}>
    <UserScreen />
  </GlobalTestProvider>
);

Not to mention, when we add a new context, there's only one place to do it, and all test suites get updated together. Boom.

Summary

Reduce friction in creating new tests and make them more maintainable by creating a wrapper component that includes all global context providers.

Within Reach: Testing Lists with React Testing Library

Derek N. Davis — Wed, 30 Jun 2021 17:26:29 +0000

When it comes to targeting elements with React Testing Library, it's easy when there's only one. Throw in a getByText or getByRole, and you're off to the races.

Have a list of something? Then you get hit with this:

Found multiple elements with the text of: ${text}

You now have some more decisions to make.

Let's get into some examples of how to test your component that's rendering a list of elements.

The Component Under Test

For demonstrating these concepts, we're going to be testing a simple component that manages a list of characters from The Office.

It only does a few things:

shows a list of characters
adds characters to the front of the list
deletes characters

function OfficeCharacters() {
  const [characters, setCharacters] = useState([
    'Michael Scott',
    'Dwight Schrute',
    'Jim Halpert'
  ]);
  const [newCharacter, setNewCharacter] = useState('');

  function add(e) {
    e.preventDefault();

    setCharacters((prev) => [newCharacter, ...prev]);
    setNewCharacter('');
  }

  function deleteCharacter(character) {
    setCharacters(
      (prev) => prev.filter((c) => c !== character)
    );
  }

  return (
    <>
      <form onSubmit={add}>
        <label htmlFor="newCharacter">New Character</label>
        <input
          type="text"
          id="newCharacter"
          value={newCharacter}
          onChange={(e) => setNewCharacter(e.target.value)}
        />
        <button>Add</button>
      </form>
      <ul>
        {characters.map((character, i) => (
          <li key={i} data-testid="character">
            <span data-testid="name">{character}</span>{' '}
            <button
              type="button"
              onClick={() => deleteCharacter(character)}
            >
              Delete
            </button>
          </li>
        ))}
      </ul>
    </>
  );
}

Setting Up the Test Render Function

The testing pattern I'm a big fan of involves setting up a test render function (read more about it in Solving the Maintenance Nightmare). In short, it abstracts the element-targeting logic and keeps the individual tests focused on the scenarios.

Beginning with the Form

The form part of the component will be the easy part. Here's what we have:

<form onSubmit={add}>
  <label htmlFor="newCharacter">New Character</label>
  <input
    type="text"
    id="newCharacter"
    value={newCharacter}
    onChange={(e) => setNewCharacter(e.target.value)}
  />
  <button>Add</button>
</form>

Let's create our test render function and add those elements to the return.

describe("OfficeCharacters", () => {
  function renderOfficeCharacters() {
    render(<OfficeCharacters />);

    return {
      newCharacterInput:
        screen.getByLabelText('New Character'),
      addButton: screen.getByText('Add'),
    };
  }
});

Querying the List with `within`

For the next part, we tackle the list.

<ul>
  {characters.map((character, i) => (
    <li key={i} data-testid="character">
      <span data-testid="name">{character}</span>{' '}
      <button
        type="button"
        onClick={() => deleteCharacter(character)}
      >
        Delete
      </button>
    </li>
  ))}
</ul>

Now, we could use a getAllBy* query to get all the names and then another query to get all the delete buttons. But then we'd have to stitch them back together based on index. Yeah... Let's not do that.

Instead, let's use a handy function from React Testing Library called within.

We can use it to query within a container. There's a variety of ways we could specify the container for each list item, but I like to use a data-testid to signal that it's only needed for testing.

<li key={i} data-testid="character">
  ...
</li>

In our test render function, we can now loop over the elements with data-testid="character" and get the name and delete button for each one.

return {
  newCharacterInput: screen.getByLabelText('New Character'),
  addButton: screen.getByText('Add'),
  getCharacters() {
    return screen.getAllByTestId('character')
      .map((item) => ({
        name: within(item)
          .getByTestId('name')
          .textContent,
        deleteButton: within(item)
          .getByText('Delete')
      }));
  }
};

Testing Add

When testing add (or anything really), we need to first verify the initial state is what we expect. If we assume something is or isn't there and eventually that changes, we could end up getting a false positive.

With the test render function in place, everything else becomes straight-forward because we don't have any query logic directly in the test.

it('should add a character', () => {
  const {
    newCharacterInput,
    addButton,
    getCharacters
  } = renderOfficeCharacters();

  const pam = 'Pam Beesly';

  // verify pam is NOT in the initial list
  expect(
    getCharacters().find(
      (character) => character.name === pam
    )
  ).not.toBeTruthy();

  // add pam
  fireEvent.change(
    newCharacterInput,
    { target: { value: pam } }
  );
  fireEvent.click(addButton);

  // verify pam is first in the list
  expect(
    getCharacters().findIndex(
      (character) => character.name === pam
    )
  ).toBe(0);
});

Testing Delete

For delete, we just get the delete button for a particular character, click it, verify the character is no longer there, and we're done!

it('should delete a character', () => {
  const { getCharacters } = renderOfficeCharacters();

  const jim = 'Jim Halpert';

  // get the delete button for Jim
  const deleteJim = getCharacters().find(
    (character) => character.name === jim
  ).deleteButton;

  // delete Jim
  fireEvent.click(deleteJim);

  // verify Jim is NOT in list
  expect(
    getCharacters().find(
      (character) => character.name === jim
    )
  ).not.toBeTruthy();
});

Here's the CodeSandbox to view the full solution:

Summary

For testing lists, put a data-testid on the repeating container, and use within to query the individual elements.
All of your tests can make assertions off of the array property returned from the test render function.

Fix Your Failing Tests: A Debugging Checklist for React Testing Library

Derek N. Davis — Sun, 30 May 2021 20:01:18 +0000

When you get stuck fixing your React Testing Library tests, it's hard to remember all the tips and tricks for every issue, and you don't always have a coworker available to help get back on track. But typically, all it takes is asking the right questions.

Today, I'm going to be your coworker. Let's fix those tests.

Making this Process Quicker

Before we get started, I would recommend taking a couple minutes (literally) to read 3 Steps to Frictionless TDD with Jest and VS Code. It will make the debugging process go much smoother, and you'll be happy you did.

And with that, let's begin.

Can't Find My Element

Not being able to find an element is generally a symptom of something else, but it is the most common problem you'll run into. You might be seeing one of these errors:

Unable to find an element with the text: ${text}. This could be because the text is broken up by multiple elements. In this case, you can provide a function for your text matcher to make your matcher more flexible.

Unable to fire a ${event.type} event - please provide a DOM element.

The most important thing to figure out are the conditions that determine when the element is rendered and go through them one by one.

A Query Typo

Starting with the most common issue, verify that your query (getByText, getByRole, getByPlaceholderText, getByTitle, getByTestId) matches the attributes you're targeting on the element. Copy and paste the correct text to make sure a typo isn't what's causing the issue.

API Mocking

Are you missing an API call that should be mocked?
Did you mock your API call with the wrong data?
Does your API response not meet the conditions to render that element?

For verifying API responses, console.log() is your friend.

getUser(userId).then((user) => {
  // verify your API call is getting the correct response
  console.log('getUser ', user);

  setUser(user);
});

Pro Tip

If your code looks like this:

getUser(userId).then((user) => setUser(user));

You don't have to add curly braces to fit in your console.log(). You can do this little trick to save some time:

getUser(userId).then((user) => 
  console.log(user) || setUser(user)
);

`setTimeout` and `setInterval`

If your code is using a setTimeout or setInterval and the callback for it plays a part in making your element show up, save yourself the headache, and put this line at the top of your test file:

jest.useFakeTimers();

Now your test doesn't have to wait on real time to elapse.

Read more about the timer mocks in the Jest Docs.

Using `Promise.all`? `waitFor` it... `waitFor` it...

Another issue you might run into with elements not showing up is with Promise.all. Say your code looks like this:

Promise.all([
    getUser(userId),
    getUserPermissions(userId)
]).then(([user, permissions]) => {
    // set state to make `myElement` show up
});

Wrap your assertion in a waitFor to allow Promise.all to resolve.

await waitFor(() => expect(myElement).toBeInTheDocument());

This would also apply to using other Promise methods like Promise.allSettled or Promise.race.

`screen.debug()` Your Queries

When your query can't find a particular element, you need to see what React Testing Library is seeing, and screen.debug() is your window into that. If you have a small component, calling screen.debug() without any parameters will be sufficient. But if your component is really big, the output will be truncated, and that doesn't help very much.

Instead, it's better to narrow down what you're looking for. You can put a temporary data-testid on the container of the element you're targeting, and print that out. Now you won't have to sift through 7000 lines of HTML in a terminal.

screen.debug(screen.getByTestId('tempContainerId'));

If you really want to see more than 7000 lines of output, which is the default, it can be changed like this:

DEBUG_PRINT_LIMIT=10000 npm test

Element Is Not Supposed to be There, But It Is

Sometimes you need to ensure that an element is no longer in the DOM, but your test isn't cooperating. Here are a couple of things to try to get in the green again.

Stale Query

One problem you may have in verifying the element is gone is a stale query. Here's the setup:

const hideNameButton = screen.getByText('Hide Name');
const name = screen.queryByText('Derek');

// name should be there
expect(name).not.toBeNull();

// hide it
fireEvent.click(hideNameButton);

// name should not be there.. but it still is :(
expect(name).toBeNull();

In the final assertion, name isn't re-queried. It's stale.

For most test suites, I recommend the solution I discuss in my article on targeting conditional elements. But for a quick fix, you can also inline the queries:

// name should be there
expect(screen.queryByText('Derek')).not.toBeNull();

// hide it
fireEvent.click(hideNameButton);

// name should not be there
expect(screen.queryByText('Derek')).toBeNull();

`waitForElementToBeRemoved`

Another way of solving this problem is the waitForElementToBeRemoved function. This is more useful in cases where the element may not be removed immediately after some action. Maybe it makes an API call and the promise callback is what removes it. In that case, you could do this:

// name should be there
expect(screen.queryByText('Derek')).not.toBeNull();

// delete the person
fireEvent.click(deletePersonButton);

// name should not be there
await waitForElementToBeRemoved(() => 
  expect(screen.queryByText('Derek')).toBeNull()
);

My Test Passes When Ran by Itself, But Fails When Ran with Other Tests

One of the most frustrating situations is when a test passes by itself, but as soon as you run the whole suite, it fails. Here are a few things to check to solve that problem.

Are You Forgetting an `async` Somewhere?

Probably the most common cause of tests that fail when ran together is a missing async. When a test runs an operation that needs to be awaited but doesn't have one, it's effectively running that code after the test has completed. This can potentially wreak havoc on the next test, causing it to fail.

To make sure you're not missing an async with React Testing Library functions, you can use eslint-plugin-testing-library . This will warn you if you're using async unnecessarily or you're missing it entirely.

As for your own functions that you're calling from your test, you'll just have to look over them carefully to make sure you're not missing the async keyword.

Do You Have Global Variables in Your Test Suite?

If you're mutating global variables in your test suite, it could lead to some strange issues when running all the tests together.

let user = {
  userName: 'user1'
};

it('should do something', () => {
  // mutating a global variable
  user.userName = 'user2';

  // ...
});

it('should do something else', () => {
  // user.userName is now 'user2' for this test. whoops!
});

One way to solve this is using a beforeEach:

let user;

beforeEach(() => {
  user = {
    userName: 'user1'
  };
});

But a better way is to use a test render function:

function renderUser({ user }) {
  render(<User user={user} />);

  return {
    // ... information and controls in the User component ...
    saveButton: screen.getByText('Save')
  };
}

it('should ...', () => {
  const { saveButton } = renderUser({ user: { userName: 'user1' } });

  // ...
});

This pattern completely removes the question of "did I forget to reset my variables in beforeEach?"

Is Your Component Mutating Global Data?

It's also possible that your component is mutating global variables. Maybe there's data that is set in localStorage, sessionStorage, or (heaven forbid) on the window object during the run of one of your tests. If the next test is expecting to work with a clean copy of those storage mechanisms, that can cause a problem.

Make sure you're resetting those variables in your test render function or beforeEach.

My `react-router` Params Are Undefined

When you're testing a component directly that is rendered under a react-router Route component in your app, you've got to make sure the path is the same in both contexts. For instance, say you have this in your app:

<Route path={['/users', '/users/:companyId']}>
  <UserScreen />
</Route>

In your test, you have to render the component with the same path:

render(
  <MemoryRouter>
    <Route path={['/users', '/users/:companyId']}>
      <UserScreen />
    </Route>
  </MemoryRouter>
);

Let's say you forget and only do part of the path:

render(
  <MemoryRouter>
    <Route path="/users">
      <UserScreen />
    </Route>
  </MemoryRouter>
);

Then when you try to access companyId from useParams, it will be undefined because it was never declared in the route definition.

const { companyId } = useParams();

console.log(companyId); // undefined

So if your route parameters aren't changing after clicking links or doing a history.push in your test, the first thing to check is the path.

Summary

Testing can become really frustrating when you get stuck debugging a long list of failing tests.
Use this checklist to get back in the green again.

Hey! If this helped you fix a failing test, please share!

If you've got suggestions for other fixes to common testing scenarios, let me know, so it can help others.

Solving the Maintenance Nightmare with React Testing Library

Derek N. Davis — Fri, 02 Apr 2021 13:16:01 +0000

Writing tests is a crucial part of quality software, and with React, the go-to solution is React Testing Library. But if we're not careful, our test suite can turn into a maintenance nightmare.

Let's fix that.

Test Render Function

The best thing we can do for the maintainability of our tests is to have a single function that renders our component and queries its elements. We'll call it a test render function.

Kent C. Dodds mentions this approach in his article on test isolation, and it has the potential to transform the way you write your tests.

Here's an example:

import { render, screen } from '@testing-library/react';
import ToDoScreen from './ToDoScreen';

describe('ToDoScreen', () => {
  function renderToDoScreen() {
    render(<TodoScreen />);

    return {
      name: screen.getByLabelText('Task'),
      add: screen.getByText('Add')
    };
  }

  it('should add a task', () => {
    const { name, add } = renderToDoScreen();

    // ...
  });
});

Let's dig into what this approach gives us.

Keep Tests Easy to Read

Have you ever read through a test and it took way longer than it should have to understand what was going on? Querying logic adds an extra layer of code we have to sift through to get to what we're really after: the scenario.

Here's an example of inlining all the queries:

it('should close the form after add', async () => {
  render(<PersonScreen />);

  // open the form
  fireEvent.click(screen.getByText('Toggle Form'));

  // fill it out
  fireEvent.change(
    screen.getByLabelText('Name'),
    { target: { value: "Derek" } }
  );

  // click add
  fireEvent.click(screen.getByText('Add'));

  // the form should now be closed
  expect(screen.queryByLabelText('Name')).toBeNull();
});

To be honest, it's not that bad for small tests like this, but when the tests get bigger, it's harder to get past the noise and understand the scenario.

Let's change it to use a test render function and compare.

it('should close the form after add', async () => {
  const { toggleForm, form } = renderPersonScreen();

  // open the form
  fireEvent.click(toggleForm);

  // fill it out
  fireEvent.change(
    form.name,
    { target: { value: "Derek" } }
  );

  // click add
  fireEvent.click(form.add);

  // the form should now be closed
  expect(form.name).toBeNull();
});

I'm not sure about you, but I like this a lot better. When reading a test, do we really care if the button came from getByText, getByRole, or getByTestId? Having a test render function helps our tests focus on scenarios and not get bogged down with targeting UI elements. The steps should be obvious. Everything else is just implementation detail.

Predictable Tests

The results of running a test by itself should be the same as running it with all the tests in a suite. Setting global variables during tests can cause failures when running tests together if any of those variables aren't reset properly in a beforeEach.

A test render function isolates each test so they're more predictable. Let's look at an example:

describe('AsyncSelect', () => {
  function renderAsyncSelect() {
    const fetchOptions = jest.fn();

    render(
      <AsyncSelect
        getOptions={fetchOptions}
        {/* other props */}
      />
    )

    return {
      fetchOptions,
      openMenu: // ...
    };
  }

  it('should call the fetch after the menu opens', () => {
    const { fetchOptions, openMenu } = renderAsyncSelect();

    expect(fetchOptions).not.toHaveBeenCalled();

    openMenu();

    expect(fetchOptions).toHaveBeenCalled();
  });

  it('should call the fetch on search', () => {
    const { fetchOptions, openMenu } = renderAsyncSelect();

    expect(fetchOptions).not.toHaveBeenCalled();

    // ...
  });
});

In the above example, we had two tests back to back making assertions on the fetchOptions mock, and this works without any extra thought because the mock is rebuilt in the test render function.

Consider the alternative:

describe('AsyncSelect', () => {
  let fetchOptions = jest.fn();

  function renderAsyncSelect() {
     // ...
  }

  // ...
});

If we did this, we'd have a problem. The mock isn't being reset between tests, so the tests would pass individually, but fail when ran as a group.

This is the kind of thing that makes you question your career choice. And it's all because we forgot we needed a beforeEach.

let fetchOptions;

beforeEach(() => {
  fetchOptions = jest.fn();
});

Using a test render function removes this problem altogether, and we don't even need to think about it.

Centralizes Queries

Querying UI elements directly in our tests causes extra work when our HTML structure changes or there's a change in a newer version of a third party component we use or even React Testing Library itself. We would then have to go around to every failing test to fix it.

If all of our querying is centralized in a test render function, we only have to correct the problem in one place.

Reusable Components

So far we've been talking about test render functions for a single file, but we can expand that to the most reusable components in our codebase: modals, date pickers, dropdowns, etc.

Most, if not all, of our tests interact with these kinds of components. If we decide to switch from one third party dropdown to another, we would have to go update every test to fix it.

We can avoid that nightmare by building test helpers for these components so that swapping out a third party component just requires an update to our test helper.

Summary

Test render functions help us solve the maintenance nightmare.
Abstracting query logic makes our tests easier to read.
Isolating tests makes them more predictable.
Centralizing queries and writing test helpers for the most reusable components future proofs our tests.

Wary of the Query: Targeting Conditional Elements with React Testing Library

Derek N. Davis — Mon, 15 Mar 2021 13:01:35 +0000

One problem I frequently run into when testing is that conditionally rendered parts of the UI can be difficult to target with React Testing Library. As I'm planning out my tests, I continually ask myself questions like:

When am I able to query this element?
Is the query stale?
Do I need to query it again?

It all feels like a tight rope act to get it right.

Typically I get the answers to those questions when the Unable to find an element ... error pops up in the terminal. Then I end up having to sift through debug output to check if React Testing Library is lying to me or not (it never is).

If you've ever found yourself in this situation, I've got a solution you'll find useful.

The Basic Test Setup

We're going to be writing a test for the PersonScreen component. It's just a form with a name field and an add button.

function PersonScreen() {
  const [name, setName] = useState('');

  function add(e) {
    // ...
  }

  return (
    <form onSubmit={add}>
      <div>
        <label htmlFor="name">Name</label>
        <input
          id="name"
          type="text"
          value={name}
          onChange={(e) => setName(e.target.value)}
        />
      </div>
      <button>Add</button>
    </form>
  );
}

When I write a test suite for a component, the first thing I do is make a render{ComponentName} function at the top of my describe. For the PersonScreen component, my render function would look something like this:

import { render, screen } from '@testing-library/react';
import PersonScreen from './PersonScreen';

describe('PersonScreen', () => {
  function renderPersonScreen() {
    render(<PersonScreen />);

    return {
      name: screen.getByLabelText('Name'),
      add: screen.getByText('Add')
    };
  }

  // ... tests ...
});

This way all of the element querying is done in one centralized location, the tests are isolated, and they're easier to read.

But sometimes we can run into a problem with this approach.

Conditionally Rendered UI

Let's change this component to so the user can hide and show the form with a toggle button.

function PersonScreen() {
  const [name, setName] = useState('');
  const [show, setShow] = useState(false);

  function add(e) {
    // ...
    // close the form after add
    setShow(false);
  }

  return (
    <section>
      <button onClick={() => setShow((s) => !s)}>
        Toggle Form
      </button>
      {show && (
        <form onSubmit={add}>
          <div>
            <label htmlFor="name">Name</label>
            <input
              id="name"
              type="text"
              value={name}
              onChange={(e) => setName(e.target.value)}
            />
          </div>
          <button>Add</button>
        </form>
      )}
    </section>
  );
}

Since the form is no longer shown when the first getByLabelText runs, it's going to produce an error in the console:

TestingLibraryElementError: Unable to find a label with the
text of: Name

queryByLabelText would get rid of the error, but when we try to access name, it'll be null. What we need is a way to query the form elements after they are shown while still keeping their queries centralized.

The Function Approach

One way we can fix this is by having a getForm() function.

function renderPersonScreen() {
  render(<PersonScreen />);

  function getForm() {
    return {
      name: screen.queryByLabelText('Name'),
      add: screen.queryByText('Add')
    };
  }

  return {
    toggleForm: screen.getByText('Toggle Form'),
    getForm
  };
}

We call it every time we want to access the form controls.

it('should close the form after add', () => {
  const { toggleForm, getForm } = renderPersonScreen();

  // open the form
  fireEvent.click(toggleForm);

  // get the form now that it's open
  let form = getForm();

  // fill out the form
  fireEvent.change(form.name, { target: { value: 'Derek' } });

  // click add
  fireEvent.click(form.add);

  // get the form again since it's now hidden
  form = getForm();

  // the form should now be closed
  expect(form.name).toBeNull();
});

This works, but it's annoying to have to call getForm() to access the controls on it, and then after something changes, call it again to get the most up to date results.

We can do better.

Property Getters

Let's make a few tweaks to the render function. Instead of getForm(), we have a form property with name and add property getters.

function renderPersonScreen() {
  render(<PersonScreen />);

  return {
    toggleForm: screen.getByText('Toggle Form'),
    form: {
      get name() {
        return screen.queryByLabelText('Name');
      },
      get add() {
        return screen.queryByText('Add');
      }
    }
  };
}

Now our test is even more simple:

it('should close the form after add', async () => {
  // now we destucture `form`, and we don't
  // have to call getForm() anymore
  const { toggleForm, form } = renderPersonScreen();

  // open the form
  fireEvent.click(toggleForm);

  // fill it out
  fireEvent.change(form.name, { target: { value: "Derek" } });

  expect(form.name.value).toBe("Derek");

  // click add
  fireEvent.click(form.add);

  // the form should now be closed
  // no need to requery `form.name`!
  expect(form.name).toBeNull();
});

With property getters, we get to use dot notation, we don't have to call getForm() to access our controls, and we don't have to worry about form being stale. We can have our cake and eat it too.

That's more like it.

Note

One thing to note with this approach is that we can't destructure the properties when using getters. The act of destructuring will call the getters, and then we're back to the problem we had in the first place. We can fix it by grouping the conditional elements in an object like we did in the above examples or not destructuring at all (and sometimes that's not such a bad thing).

Summary

Targeting conditionally shown elements inside a centralized render function can be difficult in React Testing Library.
Use JavaScript property getters to ensure your element queries aren't stale and improve the testing experience.

3 Steps to Frictionless TDD with Jest and VS Code

Derek N. Davis — Wed, 24 Feb 2021 13:59:21 +0000

If you're looking to make writing your Jest tests easier in VS Code, look no further. In my quest to optimize my testing, I've tried several approaches, but I always come back to this workflow.

1. Configure VS Code

No more tiny terminal squeezed at the bottom of the editor. View your terminal and test file side by side by dragging the terminal to the action bar.

2. Target a Single File in Watch Mode

Jest watch mode will automatically re-run your tests when anything changes. Provide it a file name or pattern to limit what files are ran. Here we're running just the "string" file.

jest --watch string

Something to note here is that "string" will match on folders and file names. There are various ways to target different test files to run. Check out the Jest Docs to learn more.

3. Focus on One Test

You may have used it.skip to skip certain tests, but we can also make it run a certain test with it.only. In this case, we're focusing on the "should trim" test.

it.only('should trim', () => {
  schema.trim().cast(' 3  ').should.equal('3');
});

Make your test pass, and go back to step 2!

P.S. Don't forget to remove .only before you run jest --coverage, or you'll have a heart attack when your percentage drops to nothing.

Summary

Setup VS Code to show your terminal side by side with your test
Focus on a single test at a time to reduce noise in the terminal and boost your productivity

Happy testing

Put Down the Destructuring Hammer

Derek N. Davis — Thu, 18 Feb 2021 13:57:46 +0000

Destructuring is one of JavaScript's most handy features. Once I wrapped my head around the odd-looking syntax, I was a big fan of what it can do. I mean, what's not to love? If we want to destructure a property, we can do it.

Objects? We can destructure that.

const { firstName, lastName } = person;

Arrays? We can destructure that.

const [person, setPerson] = useState(null);

An array of objects in an object? We can destructure that too.

const {
  firstName,
  lastName,
  employmentHistory: [
     { company, startDate, endDate, title }
  ]
} = person;

It even works on strings, believe it or not.

const { length } = "hello"; // But don't do this. Just no.

What about if we want to default a value if there's not one? No problem.

const { firstName = 'Derek', lastName = 'Davis' } = person;

But with all that power, there's potential for problems.

Naming Clashes

Once we go down the path of destructuring, we'll inevitably run into the next most common problem it causes: variable naming clashes.

const { firstName, lastName } = person1;
// whoops! can't do that.
const { firstName, lastName } = person2;

firstName and lastName are taken. So what do we do? Destructuring has an answer for that.

const {
    firstName: person1FirstName, 
    lastName: person1LastName
} = person1;
const {
    firstName: person2FirstName,
    lastName: person2LastName
} = person2;

// ... later on ...

alert(`
    hello ${person1FirstName} ${person1LastName}
    and ${person2FirstName} ${person2LastName}!
`);

We've renamed our properties to fix the error, but what have we gained? We have several hideous lines of JavaScript, and we can use person1FirstName without putting a dot in it.

Dot Notation to the Rescue

Check this out.

// the destructuring lines are gone! 

// ... later on ...

alert(`
    hello ${person1.firstName} ${person1.lastName}
    and ${person2.firstName} ${person2.lastName}!
`);

If we use dot notation, we don't have to destructure anything, we don't have the variable naming conflict, we have less code, and it's more readable!

Let's look at another example.

The Lure of Shorthand Property Names

Shorthand property names are one of my favorite features in JavaScript. I love how clean the syntax looks.

// old school
setPerson({ name: name, city: city });

// shorthand property names. so clean.
setPerson({ name, city });

But sometimes we can have tunnel vision when we're trying to use this feature. If what we have to destructure is deeply nested, we've only created more noise.

const {
    name,
    demographics: { address: { city } }
} = person; // a game of match the brackets

setPerson({ name, city });

So what's the answer?

Dot Notation Again

We've gotten rid of the destructuring and all those brackets. It's so much more readable this way.

// no destructuring

setPerson({
  name: person.name,
  city: person.demographics.address.city
});

But hey, maybe you don't want to use all the dots. Destructuring only the top level properties keeps things readable.

// just the right amount of destructuring
const { name, demographics } = person;

setPerson({
  name,
  city: demographics.address.city
});

What's easy to forget is that dot notation and destructuring can be used in combination for better readability. For instance, if we want to pull out the properties of address, we can do this:

// not ideal
const {
    demographics: { address: { city, state, zip } }
} = person;

// so much better
const { city, state, zip } = person.demographics.address;

Destructuring is one of those features that's great in its flat form, but when it becomes nested, the readability starts to degrade quickly.

Naming Ambiguity

Imagine this. You're trying to understand an area of your application you're not familiar with. You're 200 lines into one of the files, and you come across a variable called name. There's not a local declaration of it; it's just being used for something, and you have no idea what it is. So you go hunting and find this:

const { name, address, phone } = company;

In this case, using destructuring created an overly generic variable name because it removed the context of where it came from. If it hadn't been destructured, company.name would have been totally clear. No variable hunting required.

When we decide to destructure something, keep it as close to where it's being used as possible, especially if the variable name is generic.

Summary

When destructuring causes naming clashes, it's a code smell. It might be okay, but then again, it also might be a sign you shouldn't be using destructuring.
Prefer keeping destructuring as flat as possible to avoid a mess of brackets. Using dot notation and destructuring in combination can help keep things flat.
Destructured objects should be as close as possible to where they are used to help readability. Overly generic names make code hard to understand.

Cheat Code for a Lightning Fast Front End - Building an Optimistic UI

Derek N. Davis — Fri, 12 Feb 2021 14:17:46 +0000

In the never ending pursuit of building faster and faster web apps, there are no options off limits. We split our databases to optimize for reading and writing, make our services scale up and down with demand and have complex caching strategies on top of all of it.

Despite that effort, we still show our users a spinner every time they click a save button. No matter how much we optimize on the back end, that delay will be noticeable to our users. We've trained them to click and wait.

When you think about it though, do we really need to? If our API is reliable and fast, we're inconveniencing our users on the 1% chance something will fail. Instead of doing further optimizations to the API to make our app feel fast, there's a different approach we can take that's almost like cheating. When a user clicks a button, we no longer wait for the request to complete. We assume it's going to be successful.

So what does that mean in practice?

When the user clicks the save button, boom. Green check. Instant feedback. The delete button? One click, and immediately it's done. No spinner, no delay, no nonsense. We've moved the waiting out of the way, our users are more engaged and can now focus on their workflow completely. This is the essence of the optimistic UI pattern.

We see this in the wild all over the web with the most well-known example being the like button on just about any social platform.

Here's an example from Twitter. We've clicked the like button, and it's showing the change in the UI, but the Network tab tells a different story. Notice how every request is still pending.

The Sample App

To demonstrate applying the optimistic UI pattern, we will be going through a really simple app for managing a list of books. The user can add, edit, delete, and mark a book as their favorite. It's currently written in a "pessimistic" way, but we're about to change that.

The example code is written with React, but the pattern can be applied whether you're using Angular, Vue, Svelte or just Vanilla JavaScript.

Where NOT to Apply It

This pattern can be applied with POST, PUT, and DELETE requests, but the better question is when should we use it. We might not want to use this pattern in cases where:

The API is applying validation that the UI is not For instance, if we're deleting something that is potentially referenced elsewhere
The API has a tendency to be slow If a particular endpoint takes a long time to persist changes, applying an optimistic update is not a good fit. Depending on how long an update takes, the user may have time to leave the screen and pull up a totally different record. If that update was to fail, we definitely don't want to have to pull them back into something they're no longer thinking about. As long as operation tends to complete in less than 2 seconds, it's okay to make it optimistic.
The API is unreliable If an endpoint relies on an operation or third party service that has a higher failure rate, then it's not a good candidate for an optimistic update.

In short, we should only apply it to fast and reliable endpoints.

An Optimistic Toggle

The best place to start sprinkling in some optimism to our code is a toggle. For our app, we have a button to mark which book is our favorite. Currently the code for setting that data looks like this:

function updateFavorite(id) {
  fetch(`/favorite/${id}`, { method: 'PUT' })
    .then(() => setFavoriteBookId(id));
}

We make the update and when it completes, we set the favorite book id.

Now let's make this go a little faster.

function updateFavorite(id) {
  setFavoriteBookId(id);
  fetch(`/favorite/${id}`, { method: 'PUT' });
}

We skip the waiting and immediately set the favorite book id, and then we fire off an API call to persist it.

Optimistic Delete and Edit

Delete and edit are the same story when it comes to applying this pattern. We update state and then make the API call.

function deleteBook(id) {
  // delete the book from state
  setBooks((prev) =>
    prev.filter((book) => book.id !== id)
  );

  // fire off our request
  fetch(`/books/${id}`, { method: 'DELETE' });
}

function updateBook(book) {
  // update the book in state
  setBooks((prev) => {
    const bookIndex = prev.findIndex(
      (b) => b.id === book.id
    );
    return [
      ...prev.slice(0, bookIndex),
      book,
      ...prev.slice(bookIndex + 1)
    ];
  });

  // fire off our request
  fetch(`/books/${book.id}`, {
    method: 'PUT',
    body: JSON.stringify(book)
  });
}

An Optimistic Create

The most challenging usage of the optimistic UI pattern is when creating a record. With updates and deletes, we have all the information on the client side, so updating state before we make an API call is no big deal. But with a create, there's one key piece of information we have no choice but to wait on: the new record's ID.

How we go about it is largely dependent on the UX of our screen. In the case our book app, we just have a small list of books with an inline edit form, so our dependence on the ID is so that we can render it in the list.

To get around it, we generate a temporary ID for the record while we wait on the API and then update it to the real ID once we have it.

function addBook({ title, author }) {
  // generate a random negative id
  const tempId = generateTemporaryId();
  const book = { id: tempId, title, author };

  // immediately add the book
  setBooks((prev) => [...prev, book]);

  fetch('/books', {
    method: 'POST',
    body: JSON.stringify({ title, author })
  })
    .then((res) => res.json())
    .then((newBook) => {
      // update the id of the book after the POST completes
      setBooks((prev) => {
        const bookIndex = prev.indexOf(book);
        return [
          ...prev.slice(0, bookIndex),
          newBook,
          ...prev.slice(bookIndex + 1)
        ];
      });
    });
}

Handling Errors

Now, if you've gotten to this point, you're probably wondering how we handle when things actually fail. Since we've essentially been lying to the user, we need a good way to confess when things aren't so optimistic.

The big advantage of an optimistic UI is getting a user engaged in our app and into a flow state. They're no longer thinking about how our app is working. They're 100% focused on the task at hand. When we show a user an error, it is pulling them out of that flow, and we need to take great care in how we help them resolve the issue.

In some cases, like setting a favorite, it may not be worth it to show that it didn't succeed. Keeping user engagement may be priority over highlighting an unimportant failure.

In fact, Facebook does exactly that with their like button. With WiFi turned off, it will appear to let you like things, but after a refresh, you'll discover nothing actually saved.

UX Options When a Request Fails

No Error Message

For nonessential operations where user engagement is more important, we can forgo the error message.

Toast Notification

Having a clear error message show as part of our application's notification system should be the most common error handling method. Even if the user leaves the screen, we need to make sure the error is still able to show.

A Modal or Toast Notification with Buttons

In certain cases, we need to give the user options to resolve the error. They could have spent a lot of time creating or updating a record, and if they have already left the screen, we need a way of informing them of the error and giving them some options as to what they can do.

A modal would be the most urgent option to stop a user in their tracks, while a notification with buttons would be a little less jarring.

Depending on the cause of an error, a button to retry would be helpful. Timeout errors and system maintenance can certainly cause an HTTP 500 or 503 response from time to time, and a retry could resolve the issue outright. However, the retry button should not use an optimistic update. We need to give the user confidence their information is saved correctly this time, so a spinner on the button would be appropriate here.

The other option is to take the user back to the screen they were on with all their information filled out again. At that point, they can correct any issues, or in the worst case, save off their responses to another application until the API defect is resolved and they can re-enter the record.

In any case, we need to do everything we can to make sure our users don't lose their work.

Now, let's see how we can apply this to our book app.

Set Favorite

To be a little more honest with our users, we're setting the favorite book back to the original one in case the update fails. For this case, we're choosing to not show an error message.

function updateFavorite(id) {
  const previousFavorite = favoriteBookId;

  setFavoriteBookId(id);
  fetch(`/favorite/${id}`, { method: 'PUT' })
    .catch(() => setFavoriteBookId(previousFavorite));
}

Delete

For a delete, the simplest thing we can do to get back to a correct state is similar to what we did for setting the favorite. We save a copy of the books and roll it back if it fails. To inform our users, we're going to show an error notification.

function deleteBook(book) {
  const previousBooks = books;

  // delete the book from state
  setBooks((prev) =>
    prev.filter((b) => b.id !== book.id)
  );

  // fire off our request
  fetch(`/books/${id}`, { method: 'DELETE' })
    .catch(() => {
      // roll it back
      setBooks(previousBooks);
      // show an error
      toast.error(
        `An error occurred deleting ${book.title}`
      );
    });
}

Create / Update

For create and update, we're going to handle errors in the same way. After a failed POST, we just need to delete the book out of the books array.

function addBook({ title, author }) {
  // generate a random negative id
  const tempId = generateTemporaryId();
  const book = { id: tempId, title, author };

  // ...immediately add the book...

  fetch('/books', {
    method: 'POST',
    body: JSON.stringify({ title, author })
  })
    // ...
    .catch((error) => {
      // delete the newest book
      setBooks((prev) =>
        prev.filter((b) => b.id !== book.id)
      );

      // inform the calling code there was an error
      throw error;
    });
}

And for a failed PUT, we roll back the books to the original.

function updateBook(book) {
  const previousBooks = books;

  // ...update the book in state...

  // fire off our request
  fetch(`/books/${book.id}`, {
    method: 'PUT',
    body: JSON.stringify(book)
  })
    .catch((error) => {
      // roll it back
      setBooks(previousBooks);

      // inform the calling code there was an error
      throw error;
    });
}

Notice how in both catch handlers we throw the error again at the end. This is so that the calling code can do more application-specific logic to handle the error.

In the onSave of handler for our book form, we save the book, and if there's a failure, we show a custom error toast that allows the user to retry saving the book.

function onSave(book) {
  setSelectedBook(null);

  // add or update the book
  const promise = book.id >= 0
    ? updateBook(book)
    : addBook(book);

  // handle errors in the same way for add and update
  promise.catch(() => {
    toast.error(
      <ErrorToast
        message={`An error occurred saving ${book.title}.`}
        // reset the book as selected, so the user
        // can try again
        onTryAgain={() => setSelectedBook(book)}
      />,
      { autoClose: false }
    );
  });
}

Here's the full CodeSandbox to see everything from end to end.

Summary

The optimistic UI pattern assumes our API calls will succeed and uses that to make our app feel extremely fast. This increases engagement and helps our users get more done.
It's best to apply this pattern to endpoints that are fast and reliable.
When it comes to handling errors, think through the UX to determine the best way to inform the user and make sure they don't lose any of their work.

How are you using the optimistic UI pattern in your app?

Clean Up Your useEffect, But Not Too Much

Derek N. Davis — Mon, 11 Jan 2021 14:00:15 +0000

Like a lot of developers, I love to write code that is to the point and stripped of all the fluff. Something about getting code down to its smallest form is really satisfying. Although, at a certain point, conciseness and maintainability are tugging on opposite ends of the same strand.

Where this has particularly bitten me is with the cleanup function of a useEffect.

The Scenario

We start with a really simple useEffect.

useEffect(() => thing.register(), []);

Nothing special, right? Well, let's say later on we come back in here and decide brackets would look nicer, so it gets changed.

useEffect(() => {
  thing.register();
}, []);

Except... we have a problem now. These do not behave the same way. What we forgot is that thing.register() actually returns an unregister function that needs to be called in the effect cleanup. So what we should have done was this:

useEffect(() => {
  // now works the same as the implied return
  return thing.register();
}, []);

Conciseness vs. Maintainability

Let's consider this setup though.

Will we (or anyone else on our team) remember in 6 months that register() returns an unregister function that useEffect will call in its cleanup? We can only hope. The implied return in that first example makes it even more "magic."

Instead of hoping we remember that, let's instead create an intermediate variable to make it more clear.

useEffect(() => {
  const unregister = thing.register();
  return unregister;
}, []);

It's not as concise as the original, but I could come back after a long period of time and know exactly what that code is doing.

Summary

After refactoring, consider the impact to the maintainability of your code.
Make it clear when a useEffect has a cleanup function to avoid future defects.

Don't Sacrifice Your Declarative API for One Use Case - A React Pattern for Conditional Hooks

Derek N. Davis — Wed, 30 Dec 2020 04:52:19 +0000

Imagine this. You're designing a React component, and it's going great. You've been able to elegantly handle all the use cases you need in a declarative way. But then... You think of a new scenario that doesn't fit into your design, and a wrench gets thrown into your beautiful API. It needs to do something imperative like manually reload a grid or reset a form. You've got the perfect API for 90% of the use cases, but this one tiny requirement has ruined it all. What do you do?

Believe me, I've been there. It's driven me crazy for a while, but I finally came up with a pattern that solves it pretty well. Let me show you.

Let's Build a Grid

Let's say we're trying to make a paged grid component that fetches its own data. This is going to be used everywhere in the company as the go-to grid component, so we want to make it as simple as possible for a developer to implement.

We set it up with a source prop for fetching the data, and call it in a useEffect when the page number changes.

function Grid({ source }) {
  const [data, setData] = useState({ values: [], count: 0 });
  const [page, setPage] = useState(1);

  // fetch data on page change
  useEffect(() => {
    getData();
  }, [page]);

  function getData() {
    // call the `source` prop to load the data
    return source(page).then((results) => {
      setData(results);
    });
  }

  return (
    // ... 
  );
}

It would be used like this:

function PersonGrid() {
  return (
    <Grid
      source={page =>
        fetch(`/api/people?page=${page}`)
          .then(res => res.json())
      }
      // ...
    />
  );
}

This works great for really simple use cases. The developer just has to import Grid, pass in source, and it just works.

Here Comes the Wrench

Later on, functionality is added to the PersonGrid screen that allows the user to add new people, and a problem arises. The Grid controls the fetch, and since it doesn't know that a new person is added, it doesn't know to reload. What we need is an external way of handling the data. Let's refactor what we have to do that.

We'll move the state and fetching logic into its own hook called useGrid, which makes the Grid component really simple. Its only job now is to render data from the instance prop.

function useGrid({ source }) {  
  const [data, setData] = useState({ values: [], count: 0 });
  const [page, setPage] = useState(1);

  useEffect(() => {
    getData();
  }, [page]);

  function getData() {
    return source(page).then((results) => {
      setData(results);
    });
  }

  return {
    data,
    page
  };
}

function Grid({ instance }) {
  return (
    // ... 
  );
}

In our PersonGrid component, we create our grid instance with the hook and pass it to the Grid.

function PersonGrid() {
  const grid = useGrid({
    source: page =>
        fetch(`/api/people?page=${page}`)
          .then(res => res.json())
  });

  return (
    <Grid
      instance={grid}
      // ...
    />
  );
}

With our data being handled in its own hook, that makes the reload scenario straight forward.

function useGrid({ source }) {  
  const [data, setData] = useState({ values: [], count: 0 });
  const [page, setPage] = useState(1);

  useEffect(() => {
    getData();
  }, [page]);

  function getData() {
    return source(page).then((results) => {
      setData(results);
    });
  }

  return {
    data,
    page,
    reload: getData
  };
}

Now after we add a person in PersonGrid, we just need to call grid.reload().

Analyzing the APIs

Let's take a step back and analyze these two approaches based on the scenarios.

The first iteration where the Grid was handling its fetching internally was really easy to use. It only ran into issues when we got into the data reloading scenario.

The second iteration using the useGrid hook made the data reloading scenario simple, yet made basic use cases more complex. The developer would have to know to import both useGrid and Grid. This increase in surface area of the component API needs to be taken into consideration, especially for the simple use cases.

We want to have the component-only API for simple use cases, and the hook API for more complex ones.

Two APIs, One Component

If we go back to the Grid component, we can include both the source and instance props.

function Grid({
  source,
  instance = useGrid({ source })
}) {
  // Any optional props that need to be used in here should come through the `useGrid` hook.
  // `instance` will always exist, but the optional props may not.
  return (
    // ... 
  );
}

Notice that we're getting source in as a prop, and we're using it to create a useGrid instance for the instance prop.

With this pattern, we can have both component APIs. Going back to the two different usages, they will both work now using the same Grid component.

In this case, we use the instance prop (the source prop isn't needed, since it's in the hook).

function PersonGrid() {
  const grid = useGrid({
    source: page =>
        fetch(`/api/people?page=${page}`)
          .then(res => res.json())
  });

  return (
    <Grid
      instance={grid}
      // ...
    />
  );
}

And in this case, we use the source prop, which builds an instance under the hood.

function PersonGrid() {
  return (
    <Grid
      source={page =>
        fetch(`/api/people?page=${page}`)
          .then(res => res.json())
      }
      // ...
    />
  );
}

The Rules of Hooks

Now before you bring out your pitchforks and say "you can't optionally call hooks!", hear me out. Think of why that is a rule in the first place. Hooks must be always called in the same order so the state doesn't get out of sync. So what that means is that a hook must always be called or it can never be called.

In our new API, there will never be a case when a developer conditionally provides the instance prop. They will either provide the instance prop, which means the defaulted useGrid won't be used, or they'll use the source prop, meaning the useGrid hook will always be called. This satisfies the rules of hooks, but you'll have to tell ESLint to look the other way.

Summary

Mixing declarative and imperative APIs can be difficult to produce the most simple API in all use cases
Using a hook to control the component's logic and making it a default prop value allows both imperative and declarative APIs to coexist

Multiple React Roots in AngularJS

Derek N. Davis — Thu, 24 Dec 2020 20:57:44 +0000

One of the biggest challenges with incrementally migrating an app to React is how to manage multiple React “root” components. In a brand new React app, this isn’t a concern, since there’s a single top-level component. If there are any global providers, they're always at the top.

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

function App() {
  return (
    <GlobalCacheProvider>
      <NotifierProvider>
        {/* components */}
      </NotifierProvider>
    </GlobalCacheProvider>
  );
}

The basic setup for a React app

However, in a migration scenario, there are multiple top-level components. Maybe only the user editing screen and product viewing screen have been converted to React. These components will need all the global providers typically found in an App component and may need to access shared state, like app configuration, internationalization, a router or cache.

An AngularJS app with multiple React root components

An Easy Way to Create React Root Components

When managing multiple React roots, it is important to have an easy way to "Angularize" React components and wrap them in all the global providers. Creating a helper function hides away the complexity of shared state and services when defining a new React root.

The buildReactRoot function is what we'll use to define our new React root components.

// buildReactRoot.js

import React from 'react';
import GlobalCacheProvider from '...';
import NotifierProvider from '...';

export default function buildReactRoot(
  WrappedComponent,
  propNames = []
) {
  return react2Angular(
    ({ reactRoot, ...props }) => (
      <GlobalCacheProvider cacheService={reactRoot.cacheService}>
        <NotifierProvider notifier={reactRoot.notifier}>
          <WrappedComponent {...props} />
        </NotifierProvider>
      </GlobalCacheProvider>
    ),
    propNames,
    ['reactRoot']
  );
}

Let's break this function down.

We're passing ['reactRoot'] as an argument to react2Angular. This parameter specifies that the reactRoot Angular Service should be passed as a prop to the component.

Since we're destructuring the the props, we pass everything else (other than reactRoot) onto the WrappedComponent. This allows us to still pass props from Angular code directly to the component.

Let's define the reactRoot service that includes the shared global services.

// appModule.js

import userModule from './userModule';
import { createCache } from '...';

const cacheService = createCache();

angular
  .module('app', [userModule.name])
  .factory('reactRoot', (notifier) => {
    return {
      cacheService,
      notifier,
    };
  });

We used userModule above, but we haven't defined that yet. We'll build that out next to define a React component with the new React root setup.

// userModule.js

import React from 'react';
import { react2angular } from 'react2angular';
import buildReactRoot from './buildReactRoot';

// a component that uses the notifier and cache providers
function UserScreen() {
  const notifier = useNotifier();
  const cache = useCache();

  return (
    // ...
  );
}

// defining the component is just a single line of code!
const userModule = angular.module('userModule', [])
  .component('reactUserScreen', buildReactRoot(UserScreen)));

export default userModule;

Now when we use that component in an Angular UI Router state
definition, we treat it as a normal Angular component, and we don't have to pass any global services to it. reactRoot does all of that for us behind the scenes.

$stateProvider.state({
  name: 'user',
  url: '/user',
  template: `<react-user-screen></react-user-screen>`,
});

Passing Props from Angular

We can also pass props from Angular by listing them in the component definition.

// userModule.js

// ...

const userModule = angular.module('userModule', [])
  .component(
    'reactUserScreen',
    buildReactRoot(UserScreen, ['currentUser']))
  );

Then we can just pass them in like Angular component bindings.

$stateProvider.state({
  name: 'user',
  url: '/user',
  controller: function (currentUser) {
    this.currentUser = currentUser;
  },
  template: `
    <react-user-screen
      current-user="currentUser"
    >
    </react-user-screen>
  `,
});

Shared State Between Root Components

An important thing to note about having multiple root components is that global state cannot be held inside React. It could be in the Angular code or just in a plain function. This is so it can be part of the reactRoot service, which is passed to each React root component.

In the above example, the cache service was created in the appModule.js file and added to reactRoot.

// appModule.js

import userModule from './userModule';
import { createCache } from '...';

const cacheService = createCache();

angular
  .module('app', [userModule.name])
  .factory('reactRoot', (notifier) => {
    return {
      cacheService,
      notifier,
    };
  });

Then in buildReactRoot, we passed the cacheService to the
GlobalCacheProvider, which gives each React root access to the shared service.

export default function buildReactRoot(
  WrappedComponent,
  propNames = []
) {
  return react2Angular(
    ({ reactRoot, ...props }) => (
      <GlobalCacheProvider cacheService={reactRoot.cacheService}>
        <NotifierProvider notifier={reactRoot.notifier}>
          <WrappedComponent {...props} />
        </NotifierProvider>
      </GlobalCacheProvider>
    ),
    propNames,
    ['reactRoot']
  );
}

In Summary

An incremental migration to React requires an easy way to wrap new React root components in global providers.
A single AngularJS service of all global state and services helps facilitate defining new React root components.
All global state needs to be held outside of React.

Calling AngularJS Services from React

Derek N. Davis — Thu, 24 Dec 2020 20:52:06 +0000

First off, why would you want to call an AngularJS service from React? It is likely there are global services that haven’t been converted to React yet that still need to be used. It’s a lot easier and less error-prone to use the Angular service directly rather than attempting to synchronize state with a copy of the same service in React.

A big part of the AngularJS design is the digest cycle. It checks for changes in state and then updates the DOM. When doing all development within AngularJS, you almost never have to think about it. Digests are triggered at all the likely times that state changes: button clicks and when HTTP calls and timers complete. But calling AngularJS code from React is taking it outside this environment, and it takes extra steps to tell AngularJS what's going on.

AngularJS Services in React

We start with a basic React component that calls an AngularJS service to increment a counter.

import { react2angular } from 'react2angular';

const exampleModule = angular.module('exampleModule', []);

function IncrementButton({ counterService }) {
  return (
    <button
      type="button"
      onClick={() => counterService.increment()}
    >
      Increment
    </button>
  );
}

exampleModule.component(
  'reactIncrementButton',
  react2Angular(IncrementButton, ['counterService'])
);

Next we have our counterService. Nothing revolutionary here. Just a count and an increment method.

exampleModule.factory('counterService', () => {
  let count = 0;

  return {
    count,
    increment() {
      count++;
    },
  };
});

And here is our AngularJS component to pull it all together. We pass in the counterService as a prop to the React component and display the count in the template.

exampleModule.component('example', {
  controller: function (counterService) {
    this.counterService = counterService;
  },
  template: `
      <div>
        {{counterService.count}}
        <react-increment-button
          counter-service="counterService"
        >
        </react-increment-button>
      </div>
    `,
});

After running this, clicking the increment button doesn't appear to work, but that’s not entirely true. The count is actually being incremented in the state, but Angular doesn’t know it has changed. It doesn’t own the increment button, so a digest cycle is not being triggered to update the count in the DOM.

To fix this, we need to give Angular a little help by telling it to kick off a digest. The way we do that is by wrapping the service before we hand it to React.

We make a new service called reactCounterService, and its job is to call through to the counterService and trigger a digest cycle.

exampleModule.factory(
  'reactCounterService',
  (counterService, $rootScope) => {
    function increment() {
      // call the original
      counterService.increment();
      // digest!
      $rootScope.$apply();
    }

    return { ...counterService, increment };
  }
);

Then we need to make one little update in our component's controller. We'll now use the reactCounterService instead.

exampleModule.component('example', {
  controller: function (reactCounterService) {
    this.counterService = reactCounterService;
  },
  template: `
      <div>
        {{counterService.count}}
        <react-increment-button
          counter-service="counterService"
        >
        </react-increment-button>
      </div>
    `,
});

Now when the button is clicked, AngularJS knows to update the DOM, and the count is displayed correctly.

Creating a React Context for an Angular Service

In a lot of cases, the services passed down from Angular are global and should be accessible throughout the React component tree. The best way to solve that problem is to set up a React context. Let's make a context for our counterService.

// counterContext.js

import React, { useContext } from 'react';

const CounterContext = React.createContext();

export function CounterProvider({ counterService, ...props }) {
  return (
    <CounterContext.Provider value={counterService} {...props} />
  );
}

export function useCounter() {
  return useContext(CounterContext);
}

Now let's use this new context provider to wrap our IncrementButton when its passed to react2Angular.

import React from 'react';
import react2Angular from 'react2Angular';
import { useCounter, CounterProvider } from './counterContext';

// ...

exampleModule.component(
  'reactIncrementButton',
  react2Angular(
    ({ counterService, ...props }) => (
      <CounterProvider counterService={counterService}>
        <IncrementButton {...props} />
      </CounterProvider>
    ),
    ['counterService']
  )
);

At this point, you might be asking what we've gained by making this context. I'll admit this is a contrived example. Considering IncrementButton is literally just a button, it wasn't necessary. But if our IncrementButton was a whole React screen, having that counterService available at any level in the component tree is extremely helpful.

One thing you'll also notice is that the component definition got a lot more verbose just by adding that single provider. In a larger app, there will likely be several global providers for things like routing, internationalization, toast notifications, and caching. The next post, Multiple React Roots in AngularJS, deals with how to make defining these React root components simple.

In Summary

AngularJS only updates the DOM when there is a digest cycle.
Calling AngularJS services from React typically requires manually running the digest cycle with $rootScope.$apply().
Wrapping the global service in a React context will allow it to be called at any level of the component tree.

DEV Community: Derek N. Davis

Stop Serving Context Soup with Your React Testing Library Tests

The Context Wrapper

Summary

Within Reach: Testing Lists with React Testing Library

The Component Under Test

Setting Up the Test Render Function

Beginning with the Form

Querying the List with within

Testing Add

Testing Delete

Summary

Fix Your Failing Tests: A Debugging Checklist for React Testing Library

Making this Process Quicker

Can't Find My Element

A Query Typo

API Mocking

setTimeout and setInterval

Using Promise.all? waitFor it... waitFor it...

screen.debug() Your Queries

Element Is Not Supposed to be There, But It Is

Stale Query

waitForElementToBeRemoved

My Test Passes When Ran by Itself, But Fails When Ran with Other Tests

Are You Forgetting an async Somewhere?

Do You Have Global Variables in Your Test Suite?

Is Your Component Mutating Global Data?

My react-router Params Are Undefined

Summary

Solving the Maintenance Nightmare with React Testing Library

Test Render Function

Keep Tests Easy to Read

Predictable Tests

Centralizes Queries

Reusable Components

Summary

Wary of the Query: Targeting Conditional Elements with React Testing Library

The Basic Test Setup

Conditionally Rendered UI

The Function Approach

Property Getters

Note

Summary

3 Steps to Frictionless TDD with Jest and VS Code

1. Configure VS Code

2. Target a Single File in Watch Mode

3. Focus on One Test

Summary

Put Down the Destructuring Hammer

Naming Clashes

Dot Notation to the Rescue

The Lure of Shorthand Property Names

Dot Notation Again

Naming Ambiguity

Summary

Cheat Code for a Lightning Fast Front End - Building an Optimistic UI

The Sample App

Where NOT to Apply It

An Optimistic Toggle

Optimistic Delete and Edit

An Optimistic Create

Handling Errors

UX Options When a Request Fails

No Error Message

Toast Notification

A Modal or Toast Notification with Buttons

Set Favorite

Delete

Create / Update

Summary

Clean Up Your useEffect, But Not Too Much

The Scenario

Conciseness vs. Maintainability

Summary

Don't Sacrifice Your Declarative API for One Use Case - A React Pattern for Conditional Hooks

Let's Build a Grid

Here Comes the Wrench

Analyzing the APIs

Two APIs, One Component

The Rules of Hooks

Querying the List with `within`

`setTimeout` and `setInterval`

Using `Promise.all`? `waitFor` it... `waitFor` it...

`screen.debug()` Your Queries

`waitForElementToBeRemoved`

Are You Forgetting an `async` Somewhere?

My `react-router` Params Are Undefined