Frontend Testing Guide

Welcome to our testing guide! This document outlines our approach to testing Next.js applications with React Query and server components. Following these practices helps us maintain a robust, reliable codebase.

Our Testing Philosophy

We believe in thorough testing that gives us confidence in our application’s behavior. Our tests should:

• Be easy to write and maintain
• Simulate real user interactions
• Test both happy paths and error scenarios
• Properly test redirects and server actions

Testing Stack

• Vitest: For running tests and mocking
• React Testing Library: For rendering components and simulating user interactions
• @testing-library/user-event: For simulating realistic user interactions
• @tanstack/react-query: For managing server state

Mocking Strategy

We use a centralized mocking approach with vi.hoisted to create mock functions that can be reused across tests:

1
const mocks = vi.hoisted(() => ({
2
  toast: {
3
    success: vi.fn(),
4
    error: vi.fn(),
5
  },
6
  actions: {
7
    submitName: vi.fn(),
8
    getMyUserInfo: vi.fn(),
9
  },
10
  nextNavigation: {
11
    redirect: vi.fn(),
12
  },
13
  // ... other mocks
14
}));

This approach makes our tests more readable and maintainable, as all mocks are defined in one place.

Module Mocking

We mock modules at the file level:

1
vi.mock('next/navigation', () => ({
2
  redirect: mocks.nextNavigation.redirect,
3
}));
4

5
vi.mock('./actions', () => ({
6
  submitName: mocks.actions.submitName,
7
  getMyUserInfo: mocks.actions.getMyUserInfo,
8
}));

Testing Components

Setting Up Components for Testing

We use a helper function to set up components with the necessary providers:

1
function createQueryClient() {
2
  return new QueryClient({
3
    defaultOptions: { queries: { retry: false } },
4
  });
5
}
6

7
async function setupPageComponent() {
8
  const queryClient = createQueryClient();
9
  let page = await Page();
10
  return <QueryClientProvider client={queryClient}>{page}</QueryClientProvider>;
11
}

Testing Client Components

For client components, we test user interactions and verify that the right actions are triggered:

1
it('should submit name', async () => {
2
  // arrange
3
  render(await setupPageComponent());
4
  const user = userEvent.setup();
5

6
  // act
7
  await user.type(screen.getByPlaceholderText('Enter your name'), 'John Doe');
8
  await user.click(screen.getByText('Submit'));
9

10
  // assert
11
  expect(mocks.toast.success).toHaveBeenCalled();
12
});

Testing Error Scenarios

We also test how our components handle errors:

1
it('should handle error', async () => {
2
  // arrange
3
  render(await setupPageComponent());
4
  const user = userEvent.setup();
5
  mocks.actions.submitName.mockRejectedValue(new Error('error'));
6

7
  // act
8
  await user.type(screen.getByPlaceholderText('Enter your name'), 'error');
9
  await user.click(screen.getByText('Submit'));
10

11
  // assert
12
  expect(mocks.toast.error).toHaveBeenCalled();
13
  expect(mocks.actions.submitName).toHaveBeenCalledWith('error');
14
});

Testing Server Actions and Redirects

Selective Unmocking

One powerful technique we use is selective unmocking, where we test the real implementation of certain modules while keeping others mocked:

1
it("should redirect to onboarding if user not found", async () => {
2
  // Reset mocks to use real implementation for actions
3
  vi.resetModules();
4
  vi.doUnmock("./actions");
5
  vi.doUnmock("./page");
6
  vi.doMock("server-only", () => ({}));
7
  vi.doMock("@/lib/auth0", () => ({
8
    auth0: {
9
      getAccessToken: vi.fn().mockResolvedValue({
10
        token: "token",
11
      }),
12
    },
13
  }));

This approach allows us to:

1. Test the real behavior of specific modules
2. Keep control over external dependencies
3. Create targeted test scenarios

Testing Redirects

For testing redirects, we mock the Next.js redirect function to simulate its behavior:

1
// in real nextjs, redirect throws an error to prevent further execution
2
mocks.nextNavigation.redirect.mockImplementation(() => {
3
  throw new Error('NEXT_REDIRECT');
4
});

Then we can test that the redirect happens in the right circumstances:

1
await expect(async () =>
2
  render(<QueryClientProvider client={getQueryClient()}>{await Page()}</QueryClientProvider>)
3
).rejects.toThrow(/NEXT_REDIRECT/);
4
expect(mocks.nextNavigation.redirect).toHaveBeenCalledWith('/onboard');

Testing with Tanstack Query

Tanstack Query is a bit quirky. I have already told you that how you can setup your page (whether server or client component based), and test it. But since tanstack query is asynchronous, how do you make sure the client has finished loading the queries? For that we use waitFor and queryClient.isFetching() and wait until the client has finished mutating.

1. First, We will modify our createQueryClient function a bit to return to us both the page and the query client.

   1
   // ...
   2
   async function setupPageComponent() {
   3
     const queryClient = createQueryClient();
   4
     const page = await Page();
   5
     return {
   6
       // return the page...
   7
       page: <QueryClientProvider client={queryClient}>{page}</QueryClientProvider>,
   8
       queryClient, // and the query client
   9
     };
   10
   }

2. Then, in our test we will wait until the query client has finished fetching the data.

   1
   // ... set up mock functions and imports using vi.hoisted and vi.mock
   2
   
   3
   it('should display api keys', async () => {
   4
     // imagine this mocked server action is used by the query client inside the page
   5
     mocks.getApiKeys.mockResolvedValue({
   6
       tenant: 'foobar',
   7
     });
   8
   
   9
     // Act
   10
     const { page, queryClient } = await setupPageComponent(); // get both the page and the query client
   11
     render(page); // render the page
   12
     await waitFor(() => {
   13
       expect(queryClient.isFetching()).toBe(0); // IMPORTANT: wait for the query client to resolve all queries
   14
     });
   15
   
   16
     // Assert
   17
     // once the query client has finished fetching, the text/expected result should be present in the DOM.
   18
     expect(screen.getByText('foobar')).toBeInTheDocument();
   19
   });

Best Practices

1. Organize tests with describe blocks: Group related tests together
2. Follow the AAA pattern: Arrange, Act, Assert
3. Reset mocks between tests: Use vi.resetAllMocks() in afterEach
4. Test user flows: Simulate realistic user interactions
5. Test edge cases and error scenarios: Don’t just test the happy path
6. Use explicit assertions: Be specific about what you’re testing
7. Selectively unmock when needed: Use vi.doUnmock() to test real implementations
8. Mock external dependencies: Don’t call real APIs in tests
9. Test redirects properly: Simulate Next.js redirect behavior

Common Testing Patterns

Testing Server Components

Server components require special handling:

1. Mock the data they fetch
2. Render them with the necessary providers
3. Verify they render correctly with the mocked data

Testing Client Components with Server Actions

1. Mock the server actions
2. Render the component
3. Simulate user interactions
4. Verify the right server actions are called with the right arguments

Testing Redirects

1. Mock the redirect function to throw an error (like real Next.js)
2. Verify the component throws when it should redirect
3. Verify the redirect function was called with the right path