next-router-mock

To mock specific URLs or log router actions (like push or replace) in individual stories, wrap them with the <MemoryRouterProvider> component.

Important: You must import MemoryRouterProvider from a path matching your Next.js version (e.g., next-13, next-12, next-11).

Props:

• url (string | object): Sets the current route's URL.
• async (boolean): Enables async mode.
• Events:
  • onPush(url, { shallow })
  • onReplace(url, { shallow })
  • onRouteChangeStart(url, { shallow })
  • onRouteChangeComplete(url, { shallow })

// ActiveLink.story.jsx
import { action } from "@storybook/addon-actions";
import { MemoryRouterProvider } from "next-router-mock/MemoryRouterProvider/next-13";
import { ActiveLink } from "./active-link";

export const ExampleStory = () => (
  <MemoryRouterProvider url="/active" onPush={action("router.push")}>
    <ActiveLink href="/example">Not Active</ActiveLink>
    <ActiveLink href="/active">Active</ActiveLink>
  </MemoryRouterProvider>
);

For Next.js App Router (Beta) features, use next-router-mock/navigation as a drop-in replacement for next/navigation in your Jest tests.

import mockRouter from "next-router-mock";
import { render, screen, fireEvent } from "@testing-library/react";
import { usePathname, useRouter } from "next/navigation";

// Mock next/navigation with the mock implementation
jest.mock("next/navigation", () => jest.requireActual("next-router-mock/navigation"));

const ExampleComponent = ({ href = "" }) => {
  const router = useRouter();
  const pathname = usePathname();
  return <button onClick={() => router.push(href)}>The current route is: {pathname}</button>;
};

describe("next-router-mock", () => {
  it("mocks the useRouter hook", () => {
    // Set the initial url:
    mockRouter.push("/initial-path");

    // Render the component:
    render(<ExampleComponent href="/foo?bar=baz" />);
    expect(screen.getByRole("button")).toHaveTextContent("The current route is: /initial-path");

    // Click the button:
    fireEvent.click(screen.getByRole("button"));

    // Ensure the router was updated:
    expect(mockRouter).toMatchObject({
      asPath: "/foo?bar=baz",
      pathname: "/foo",
      query: { bar: "baz" },
    });
  });
});

In Jest tests, import mockRouter from next-router-mock to set the initial URL using .push() and to assert the state of asPath, pathname, and query after interactions.

import { useRouter } from "next/router";
import { render, screen, fireEvent } from "@testing-library/react";
import mockRouter from "next-router-mock";

// Mock next/router with the mock implementation
jest.mock("next/router", () => jest.requireActual("next-router-mock"));

const ExampleComponent = ({ href = "" }) => {
  const router = useRouter();
  return <button onClick={() => router.push(href)}>The current route is: "{router.asPath}"</button>;
};

describe("next-router-mock", () => {
  it("mocks the useRouter hook", () => {
    // Set the initial url:
    mockRouter.push("/initial-path");

    // Render the component:
    render(<ExampleComponent href="/foo?bar=baz" />);
    expect(screen.getByRole("button")).toHaveTextContent('The current route is: "/initial-path"');

    // Click the button:
    fireEvent.click(screen.getByRole("button"));

    // Ensure the router was updated:
    expect(mockRouter).toMatchObject({
      asPath: "/foo?bar=baz",
      pathname: "/foo",
      query: { bar: "baz" },
    });
  });
});

The MemoryRouter class is a mock implementation of NextRouter that stores the current route in memory instead of changing the browser URL. This is ideal for unit and integration testing components that rely on next/router.

Key Features

• Synchronous URL setting: Use setCurrentUrl to immediately jump to a specific route.
• Async simulation: Set the async option to true in the constructor to simulate Next.js's asynchronous routing behavior (adds a small delay before updates).
• Event Emitting: Emits standard RouterEvents (like routeChangeStart) and internal mock events.
• Snapshotting: Use MemoryRouter.snapshot(original) to create a copy of the current router state.

import { MemoryRouter } from 'next-router-mock';

// Initialize with a starting URL
const router = new MemoryRouter('/dashboard');

// Navigate to a new route
await router.push('/settings?user=123');

console.log(router.pathname); // '/settings'
console.log(router.query);     // { user: '123' }