The Problem with useRouter in Cypress

Oct 13, 2025 by wbrum.org 148 views

Introduction

When testing components in Cypress, especially those built with Next.js, we often encounter the challenge of mocking the useRouter hook from next/navigation. This hook is used to navigate between pages in a Next.js application. In this article, we will explore how to mock useRouter in Cypress, allowing us to write more comprehensive and reliable tests for our components.

Why Mock useRouter?

The useRouter hook is a crucial part of the Next.js navigation system. It provides a way to access the router's methods, such as push, replace, and reload, which are used to navigate between pages. However, when testing components that use useRouter, we need to isolate the navigation behavior and ensure that our tests are not affected by the actual navigation.

The Problem with useRouter in Cypress

When we use useRouter in our components, Cypress will throw an error because it cannot find the useRouter hook in the component's context. This is because useRouter is a part of the Next.js router, which is not available in the Cypress testing environment.

Solution: Mocking useRouter in Cypress

To mock useRouter in Cypress, we can use the cy.stub command to replace the useRouter hook with a mock implementation. Here's an example of how to do this:

import { mount } from '@cypress/react';
import { useRouter } from 'next/navigation';

describe('MyComponent', () => {
  it('should navigate to another page when button is clicked', () => {
    // Mock useRouter
    cy.stub(useRouter, 'push').as('push');

    // Mount the component
    mount(<MyComponent />);

    // Click the button
    cy.get('button').click();

    // Verify that the push method was called
    cy.get('@push').should('have.been.called');
  });
});

In this example, we use the cy.stub command to replace the push method of the useRouter hook with a mock implementation. We then mount the component and click the button. Finally, we verify that the push method was called using the should command.

Using a Custom Router

Another approach to mocking useRouter is to create a custom router that provides a mock implementation of the useRouter hook. Here's an example of how to do this:

import { useRouter } from 'next/navigation';

const customRouter = {
  push: (url: string) => {
    // Mock implementation of push method
    console.log(`Navigating to ${url}`);
  },
};

const MockedUseRouter = () => {
  return {
    useRouter: () => customRouter,
  };
};

We can then use the MockedUseRouter component in our tests to provide a mock implementation of the useRouter hook.

import { mount } from '@cypress/react';
import { MockedUseRouter } from './MockedUseRouter';

describe('MyComponent', () => {
  it('should navigate to another page when button is clicked', () => {
    // Mount the component with the custom router
    mount(<MockedUseRouter><MyComponent /></MockedUseRouter>);

    // Click the button
    cy.get('button').click();

    // Verify that the push method was called
    cy.log('Navigating to another page');
  });
});

Conclusion

Mocking useRouter in Cypress is a crucial step in writing comprehensive and reliable tests for our components. By using the cy.stub command or creating a custom router, we can isolate the navigation behavior and ensure that our tests are not affected by the actual navigation. In this article, we explored two approaches to mocking useRouter in Cypress and provided examples of how to use them in our tests.

Best Practices

When mocking useRouter in Cypress, keep the following best practices in mind:

Use the cy.stub command to replace the useRouter hook with a mock implementation.
Create a custom router that provides a mock implementation of the useRouter hook.
Use the should command to verify that the mock implementation was called.
Keep the mock implementation simple and focused on the specific behavior being tested.

Q: Why do I need to mock useRouter in Cypress?

A: When testing components in Cypress, especially those built with Next.js, we often encounter the challenge of mocking the useRouter hook from next/navigation. This hook is used to navigate between pages in a Next.js application. If we don't mock useRouter, Cypress will throw an error because it cannot find the useRouter hook in the component's context.

Q: How do I mock useRouter in Cypress?

A: There are two approaches to mocking useRouter in Cypress:

Using the cy.stub command: You can use the cy.stub command to replace the useRouter hook with a mock implementation. This is a simple and straightforward approach.
Creating a custom router: You can create a custom router that provides a mock implementation of the useRouter hook. This approach gives you more control over the mock implementation and can be useful if you need to test specific behavior.

Q: What is the difference between `cy.stub` and creating a custom router?

A: The main difference between cy.stub and creating a custom router is the level of control you have over the mock implementation.

cy.stub provides a simple way to replace the useRouter hook with a mock implementation. You can use it to verify that the useRouter hook was called, but you don't have control over the mock implementation.
Creating a custom router gives you more control over the mock implementation. You can define the behavior of the mock router and use it to test specific scenarios.

Q: How do I use `cy.stub` to mock useRouter?

A: Here's an example of how to use cy.stub to mock useRouter:

import { mount } from '@cypress/react';
import { useRouter } from 'next/navigation';

describe('MyComponent', () => {
  it('should navigate to another page when button is clicked', () => {
    // Mock useRouter
    cy.stub(useRouter, 'push').as('push');

    // Mount the component
    mount(<MyComponent />);

    // Click the button
    cy.get('button').click();

    // Verify that the push method was called
    cy.get('@push').should('have.been.called');
  });
});

Q: How do I create a custom router to mock useRouter?

A: Here's an example of how to create a custom router to mock useRouter:

import { useRouter } from 'next/navigation';

const customRouter = {
  push: (url: string) => {
    // Mock implementation of push method
    console.log(`Navigating to ${url}`);
  },
};

const MockedUseRouter = () => {
  return {
    useRouter: () => customRouter,
  };
};

Q: Can I use both `cy.stub` and creating a custom router in the same test?

A: Yes, you can use both cy.stub and creating a custom router in the same test. However, be careful not to create conflicts between the two approaches.

Q: What are some best practices for mocking useRouter in Cypress?

A: Here are some best practices for mocking useRouter in Cypress:

Use the cy.stub command to replace the useRouter hook with a mock implementation.
Create a custom router that provides a mock implementation of the useRouter hook.
Use the should command to verify that the mock implementation was called.
Keep the mock implementation simple and focused on the specific behavior being tested.

By following these best practices, you can write more comprehensive and reliable tests for your components and ensure that your applications are stable and reliable.