Mocking useRouter from next/navigation (App Router) in Cypress

The uncaught exception Error: invariant expected app router to be mounted can be resolved by wrapping the component in <AppRouterContext.Provider value={router}>.

That's the major fix, but there's also some secondary ones:

• The 'next/router' is used in the test, but "next/navigation" in the component. These should be the same router in both places.

• To stub useRouter from the Router object, you need to name the default import
  with: import * as Router from "next/navigation"
  not : import Router from "next/navigation"

  This solves the error Trying to stub property 'useRouter' of undefined

• the alias used in the calledOnce assertion should be the same name as used in the stub.

Here is my test for the NextJs sample component

component

'use client'
 
import { useRouter } from 'next/navigation'
 
export default function Page() {
  const router = useRouter()
 
  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  )
}

test

import React from 'react'
import { AppRouterContext } from 'next/dist/shared/lib/app-router-context.shared-runtime'
import * as Router from "next/navigation";
import Page from './example-client-component.js'

it('stubs the router', () => {
  const router = {
    push: cy.stub().as('router:push')
  }
  cy.stub(Router, 'useRouter').returns(router)

  cy.mount(
    <AppRouterContext.Provider value={router}>
      <Page />
    </AppRouterContext.Provider>
  )

  cy.get('button').click()

  cy.get('@router:push').should((mock) => {
    expect(mock).to.have.been.calledOnce
  })
})

test log

I've extended previous solution to support also usePathname and useSearchParams hooks from next/navigation.

Custom router mock wrapper:

import { AppRouterContext, AppRouterInstance } from "next/dist/shared/lib/app-router-context.shared-runtime";
import { PathnameContext, SearchParamsContext } from "next/dist/shared/lib/hooks-client-context.shared-runtime";
import { ReactNode, useState } from "react";

export const NextNavigationRouterMock = ({
  children,
  router
}: {
  children: ReactNode;
  router: Partial<AppRouterInstance>;
}) => {
  const [searchParams, setSearchParams] = useState<URLSearchParams>(new URLSearchParams());
  const routerProxy = new Proxy(router, {
    get(target: Record<string, () => void>, prop: string) {
      if (["push", "replace"].includes(prop)) {
        return function () {
          const [paramsString] = [...arguments];
           
          // update search params values
          setSearchParams(new URLSearchParams(paramsString?.split("/")?.[1]));
          
          // invoke the original method
          target[prop].apply(null, [...arguments] as []);
        };
      }

      return target[prop];
    }
  });

  return (
    <AppRouterContext.Provider value={routerProxy}>
      <SearchParamsContext.Provider value={searchParams}>
        <PathnameContext.Provider value={"/"}>{children}</PathnameContext.Provider>
      </SearchParamsContext.Provider>
    </AppRouterContext.Provider>
  );
};

Component:

'use client'
 
import { useRouter, usePathname, useSearchParams } from 'next/navigation'
 
export const Page = () => {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const onUpdateParams = () => {
    searchParams.set('params', '1');
  }
 
  const onNavigate = () => {
    router. (`${pathname}?${searchParams.toString()}`);
  }
 
  return (
   <>
    <button type="button" onClick={onUpdateParams}>
      Update params
    </button>
    <button type="button" onClick={onNavigate}>
     Navigate to page
    </button>
   </>
  )
}

Cypress test:

import React from 'react'
import { NextNavigationRouterMock } from "@cy/mocks";
import Page from './page'

describe("Navigation", () => {
  beforeEach(() => {
   const routerStub = {
       replace: cy.stub().as("router:replace")
   };

   cy.mount(
       <NextNavigationRouterMock value={routerStub}>
          <Page />
        </NextNavigationRouterMock>
   );
  });

  it('updates URL', () => {
     cy.get('button').click()
     cy.get("@router:replace").should("have.been.calledWith", "/?params=1");
   });
});

NextJS: 15.1 and React: 19.0

Typescript was complaining for me about router not having all of the necessary methods:

Type '{ push: Omit<SinonStub<any[], any>, "withArgs"> & SinonSpyAgent<SinonStub<any[], any>> & SinonStub<any[], any>; }' 
is missing the following properties from type 'AppRouterInstance': 
back, forward, refresh, replace, prefetchts (2739)

So I used Partial to prevent typescript from expecting the missing methods:

import React from 'react';

import {
  AppRouterContext,
  AppRouterInstance,
} from 'next/dist/shared/lib/app-router-context.shared-runtime';
import * as Router from 'next/navigation';

describe('<FullscreenButton />', () => {
  it('renders', () => {
    const router = {
      push: cy.stub().as('router:push'),
    }  as Partial<AppRouterInstance>
    cy.stub(Router, 'useRouter').returns(router)
  
    cy.mount(
      <AppRouterContext.Provider value={router as AppRouterInstance}>
        <Page />
      </AppRouterContext.Provider>
    )
  })
})