NuxtLink<\/code> to the correct detail route:<\/p>\nimport { mountSuspended } from '@nuxt\/test-utils\/runtime'\nimport TodoItem from '~\/components\/TodoItem.vue'\n\nconst mockTodo = {\n id: 42,\n label: 'Buy groceries',\n date: '2026-02-13',\n checked: false,\n}\n\ndescribe('TodoItem', () => {\n it('renders a NuxtLink pointing to \/todos\/:id', async () => {\n const wrapper = await mountSuspended(TodoItem, {\n props: { todo: mockTodo },\n })\n\n const link = wrapper.findComponent({ name: 'NuxtLink' })\n expect(link.exists()).toBe(true)\n expect(link.props('to')).toBe('\/todos\/42')\n })\n})<\/pre>\nYou could test this with plain mount<\/code>, but you would need to wire up the router manually:<\/p>\nit('using mount() requires much more manual setup', () => {\n const router = createRouter({\n history: createMemoryHistory(),\n routes: [\n { path: '\/todos\/:id', component: { template: '<div \/>' } },\n { path: '\/:pathMatch(.*)*', component: { template: '<div \/>' } },\n ],\n })\n\n const wrapper = mount(TodoItem, {\n props: { todo: mockTodo },\n global: { plugins: [router] },\n })\n\n const link = wrapper.findComponent({ name: 'NuxtLink' })\n expect(link.exists()).toBe(true)\n expect(link.props('to')).toBe('\/todos\/42')\n expect(link.attributes('href')).toBe('\/todos\/42')\n})<\/pre>\nThe second test is not wrong, but it obscures the intent. The test is about the component\u2019s route output, not about manually creating a router. mountSuspended<\/code> keeps the setup closer to how the component actually runs in Nuxt.<\/p>\nMock Nuxt server routes with registerEndpoint<\/code><\/h3>\nNuxt\u2019s data-fetching APIs require a different mocking strategy than ordinary browser fetch<\/code> calls.<\/p>\nThe root page in the demo app fetches todos with useFetch<\/code>:<\/p>\nconst { data } = await useFetch<Todo[]>('\/api\/todos')<\/pre>\nIn Nuxt, useFetch<\/code> and $fetch<\/code> do not always call the global browser fetch<\/code> API directly. During SSR, Nuxt can resolve routes like \/api\/todos<\/code> through Nitro server handlers, bypassing HTTP. That means mocking global fetch<\/code> may not affect a useFetch<\/code> call.<\/p>\nUse registerEndpoint<\/code> to mock Nuxt server API routes inside the Nuxt runtime:<\/p>\nimport { registerEndpoint, renderSuspended } from '@nuxt\/test-utils\/runtime'\nimport { screen } from '@testing-library\/vue'\nimport IndexPage from '~\/pages\/index.vue'\n\nconst mockTodos = [\n { id: 1, label: 'Buy groceries', date: '2026-02-11', checked: false },\n { id: 2, label: 'Walk the dog', date: '2026-02-10', checked: true },\n { id: 3, label: 'Write tests', date: '2026-02-09', checked: false },\n]\n\nregisterEndpoint('\/api\/todos', () => mockTodos)\n\ndescribe('Index Page', () => {\n it('renders todos from the mocked \/api\/todos endpoint', async () => {\n await renderSuspended(IndexPage)\n\n expect(screen.getByText('Buy groceries')).toBeDefined()\n expect(screen.getByText('Walk the dog')).toBeDefined()\n expect(screen.getByText('Write tests')).toBeDefined()\n })\n})<\/pre>\nregisterEndpoint<\/code> is an API function, not a macro. The first argument is the route, and the second argument returns the response that the Nuxt data-fetching call should receive.<\/p>\nBecause this example uses @testing-library\/vue<\/code>, it uses renderSuspended<\/code>, which plays the same role as mountSuspended<\/code> but follows Testing Library\u2019s rendering model.<\/p>\nStub Nuxt components with mockComponent<\/code><\/h3>\nSometimes you want to test a component that renders another nontrivial child component. In the demo app, TodoList<\/code> renders multiple TodoItem<\/code> components. To focus the test on the list behavior, we can replace TodoItem<\/code> with a small stub.<\/p>\n@nuxt\/test-utils<\/code> provides mockComponent<\/code> for this:<\/p>\n\/\/ TodoList.test.ts\nimport { mockComponent, renderSuspended } from '@nuxt\/test-utils\/runtime'\nimport { screen } from '@testing-library\/vue'\nimport { defineComponent, h } from 'vue'\nimport TodoList from '~\/components\/TodoList.vue'\nimport { useTodosStore } from '~\/stores\/todos'\n\nconst mockTodos = [\n { id: 1, label: 'Buy groceries', date: '2026-02-11', checked: false },\n { id: 2, label: 'Walk the dog', date: '2026-02-10', checked: true },\n { id: 3, label: 'Write tests', date: '2026-02-09', checked: false },\n]\n\nmockComponent('~\/components\/TodoItem.vue', () =>\n defineComponent({\n props: { todo: Object },\n setup(props) {\n return () =>\n h('div', {\n 'data-testid': 'todo-item-stub',\n 'todo-label': props.todo?.label,\n })\n },\n })\n)\n\ndescribe('TodoList', () => {\n it('renders one stub per todo seeded into the store', async () => {\n const store = useTodosStore()\n store.setTodos(mockTodos)\n\n await renderSuspended(TodoList)\n\n const stubs = screen.getAllByTestId('todo-item-stub')\n expect(stubs).toMatchSnapshot()\n })\n})<\/pre>\nThe TodoList<\/code> component reads from the Pinia store, so the test seeds the store before rendering the component.<\/p>\nThe render-function version above is explicit, but it can be hard to read. Because the Nuxt test environment includes Vue\u2019s runtime template compiler, you can write the stub more simply with a template:<\/p>\n
mockComponent('~\/components\/TodoItem.vue', {\n props: ['todo'],\n template: '<div data-testid=\"todo-item-stub\" :todo-label=\"todo?.label\" \/>',\n})<\/pre>\nOne caveat: mockComponent<\/code> is a macro that is hoisted to the top of the file. In practice, that means it is best for file-level stubs. If you need a different stub per test, use a global stub through @vue\/test-utils<\/code> instead:<\/p>\n\/\/ TodoList.globalstub.test.ts\ntest('renders one stub per todo seeded into the store', async () => {\n const store = useTodosStore()\n store.setTodos(mockTodos)\n\n await renderSuspended(TodoList, {\n global: {\n stubs: {\n TodoItem: {\n props: ['todo'],\n template: '<div data-testid=\"todo-item-stub\" :todo-label=\"todo?.label\" \/>',\n },\n },\n },\n })\n\n const stubs = screen.getAllByTestId('todo-item-stub')\n expect(stubs).toMatchSnapshot()\n})<\/pre>\nA good rule of thumb: use mockComponent<\/code> when one file-level stub is enough, and use global stubs when each test needs more flexibility.<\/p>\nMock auto-imports with mockNuxtImport<\/code><\/h3>\nNuxt auto-imports composables like useRuntimeConfig<\/code>, useState<\/code>, and useHead<\/code>. When you need to replace one of those imports in a test, use mockNuxtImport<\/code>.<\/p>\nFor example, the default layout reads the app title from runtime config:<\/p>\n
\/\/ layouts\/default.vue\nconst { appTitle } = useRuntimeConfig().public<\/pre>\nTo test this layout, mock useRuntimeConfig<\/code> and return a custom value:<\/p>\n\/\/ DefaultLayout.test.ts\nimport { mockNuxtImport, renderSuspended } from '@nuxt\/test-utils\/runtime'\nimport { screen } from '@testing-library\/vue'\nimport DefaultLayout from '~\/layouts\/default.vue'\n\nmockNuxtImport('useRuntimeConfig', () => {\n return () => ({\n app: { baseURL: '\/' },\n public: {\n appTitle: 'My Custom Title',\n },\n })\n})\n\ndescribe('Default Layout', () => {\n test('renders the appTitle from useRuntimeConfig in the headline', async () => {\n await renderSuspended(DefaultLayout)\n\n expect(screen.getByText('My Custom Title')).toBeDefined()\n })\n})<\/pre>\nmockNuxtImport<\/code> can only be used once per imported symbol per test file because it is transformed into a hoisted vi.mock<\/code>. When you need to reuse the same mock with different values, pair it with vi.hoisted<\/code>.<\/p>\nConsider this useDarkMode<\/code> composable, which relies on Nuxt\u2019s auto-imported useState<\/code>:<\/p>\n\/\/ app\/composables\/useDarkMode.ts\nimport themeConfig from '@\/utils\/theme'\n\nexport const useDarkMode = () => {\n const isDark = useState('darkMode', () => true)\n const theme = computed(() =>\n isDark.value ? themeConfig.DARK : themeConfig.LIGHT,\n )\n\n function toggleDarkMode() {\n isDark.value = !isDark.value\n }\n\n return { isDark, theme, toggleDarkMode }\n}<\/pre>\nIn the test, create one hoisted mock function and set its return value inside each test:<\/p>\n
\/\/ useDarkMode.test.ts\nimport { mockNuxtImport } from '@nuxt\/test-utils\/runtime'\nimport { ref } from 'vue'\nimport themeConfig from '~\/utils\/theme'\nimport { useDarkMode } from '~\/composables\/useDarkMode'\n\nconst { useStateMock } = vi.hoisted(() => ({ useStateMock: vi.fn() }))\n\nmockNuxtImport('useState', () => useStateMock)\n\ndescribe('useDarkMode', () => {\n test('starts in dark mode and toggles to light', () => {\n useStateMock.mockReturnValue(ref(true))\n\n const { isDark, theme, toggleDarkMode } = useDarkMode()\n\n expect(isDark.value).toBe(true)\n expect(theme.value).toEqual(themeConfig.DARK)\n\n toggleDarkMode()\n\n expect(isDark.value).toBe(false)\n expect(theme.value).toEqual(themeConfig.LIGHT)\n })\n\n test('starts in light mode and toggles to dark', () => {\n useStateMock.mockReturnValue(ref(false))\n\n const { isDark, theme, toggleDarkMode } = useDarkMode()\n\n expect(isDark.value).toBe(false)\n expect(theme.value).toEqual(themeConfig.LIGHT)\n\n toggleDarkMode()\n\n expect(isDark.value).toBe(true)\n expect(theme.value).toEqual(themeConfig.DARK)\n })\n})<\/pre>\nThe important pattern is this pair:<\/p>\n
const { useStateMock } = vi.hoisted(() => ({ useStateMock: vi.fn() }))\n\nmockNuxtImport('useState', () => useStateMock)<\/pre>\nThat gives you one hoisted mock that each test can configure independently.<\/p>\n
Test dynamic routes and Nuxt middleware<\/h3>\n
Dynamic routes are a common source of integration bugs in Nuxt because they combine several framework features: route params, middleware, server fetching, error handling, and head management.<\/p>\n
The demo project has a todo detail page at pages\/todos\/[id].vue<\/code>:<\/p>\n\/\/ pages\/todos\/[id].vue\nimport type { Todo } from '@\/stores\/todos'\n\ndefinePageMeta({\n middleware: ['validate-todo-id'] as const,\n})\n\nconst route = useRoute()\nconst todoId = Number(route.params.id)\n\nconst { data: todo, error: fetchError } = await useFetch<Todo>(`\/api\/todos\/${todoId}`)\n\nif (fetchError.value) {\n throw fetchError.value\n}\n\nuseHead({\n title: `Todo: ${todo.value?.label}`,\n})<\/pre>\nThis page uses multiple Nuxt features:<\/p>\n
\ndefinePageMeta<\/code> to attach route middleware<\/li>\nuseRoute<\/code> to read the dynamic id<\/code> parameter<\/li>\nuseFetch<\/code> to load a todo from a Nitro server route<\/li>\nuseHead<\/code> to set the page title<\/li>\n- Nuxt error handling for invalid or missing todos<\/li>\n<\/ul>\n
Start with the happy path. The test registers a mock server endpoint, renders the page at \/todos\/42<\/code>, and verifies both the visible content and useHead<\/code> call:<\/p>\n\/\/ DetailPageHappyPath.test.ts\nimport { mockNuxtImport, registerEndpoint, renderSuspended } from '@nuxt\/test-utils\/runtime'\nimport { screen } from '@testing-library\/vue'\nimport { describe, expect, test, vi } from 'vitest'\nimport type { Todo } from '~\/stores\/todos'\nimport DetailPage from '~\/pages\/todos\/[id].vue'\n\nconst mockTodo: Todo = {\n id: 42,\n label: 'Buy groceries',\n date: '2026-03-26',\n checked: false,\n}\n\nregisterEndpoint('\/api\/todos\/42', () => mockTodo)\n\nconst { useHeadMock } = vi.hoisted(() => ({ useHeadMock: vi.fn() }))\n\nmockNuxtImport('useHead', () => useHeadMock)\n\ndescribe('Detail Page - happy path', () => {\n test('renders the todo title and date and sets the title correctly', async () => {\n await renderSuspended(DetailPage, { route: '\/todos\/42' })\n\n expect(screen.getByText('Buy groceries')).toBeDefined()\n expect(screen.getByText(\/2026-03-26\/)).toBeDefined()\n expect(useHeadMock).toHaveBeenCalledWith({ title: 'Todo: Buy groceries' })\n })\n})<\/pre>\nFor good coverage, also test the error paths. If the route contains a valid integer but the server route has no matching todo, the page should throw a 404:<\/p>\n
\/\/ DetailPageErrorCase.test.ts\nimport { registerEndpoint, renderSuspended } from '@nuxt\/test-utils\/runtime'\nimport { screen } from '@testing-library\/vue'\nimport type { NuxtError } from '#app'\nimport DetailPage from '~\/pages\/todos\/[id].vue'\nimport ErrorPage from '~\/error.vue'\n\nregisterEndpoint('\/api\/todos\/999', () => {\n throw createError({\n statusCode: 404,\n statusMessage: 'Todo with id 999 not found',\n })\n})\n\ntest('throws a 404 when the todo does not exist', async () => {\n await expect(\n renderSuspended(DetailPage, {\n route: '\/todos\/999',\n }),\n ).rejects.toMatchObject({\n statusCode: 404,\n statusMessage: 'Todo with id 999 not found',\n })\n})<\/pre>\nIf the route parameter is not a valid integer, the middleware should throw a 400:<\/p>\n
test('throws a 400 when the todo id is not a valid integer', async () => {\n await expect(\n renderSuspended(DetailPage, { route: '\/todos\/abc' }),\n ).rejects.toMatchObject({\n statusCode: 400,\n statusMessage: 'Invalid todo id: \"abc\"',\n })\n})<\/pre>\nYou can also test the error page itself:<\/p>\n
test('renders status code, message, and back to home button', async () => {\n await renderSuspended(ErrorPage, {\n props: {\n error: { status: 500, message: 'Something went wrong' } as NuxtError,\n },\n })\n\n expect(screen.getByText('500')).toBeDefined()\n expect(screen.getByText('Something went wrong')).toBeDefined()\n expect(screen.getByText('\u2190 Back to home')).toBeDefined()\n})<\/pre>\nTest Nuxt middleware in isolation<\/h3>\n
The previous examples test middleware through a real page render. That gives you confidence that the middleware is wired into the route correctly. Sometimes, though, you only want to test the middleware logic quickly.<\/p>\n
For that, import the middleware directly and call it with minimal fake route objects.<\/p>\n
Here is the middleware implementation:<\/p>\n
\/\/ app\/middleware\/validate-todo-id.ts\nexport default defineNuxtRouteMiddleware((to) => {\n const id = to.params.id as string\n\n if (!\/^\\d+$\/.test(id)) {\n abortNavigation(\n createError({\n statusCode: 400,\n statusMessage: `Invalid todo id: \"${id}\"`,\n }),\n )\n }\n})<\/pre>\nThe test mocks abortNavigation<\/code> and createError<\/code>, creates fake route objects, and verifies both the allowed and rejected cases:<\/p>\n\/\/ ValidateTodoIdMiddleware.test.ts\nimport { mockNuxtImport } from '@nuxt\/test-utils\/runtime'\nimport type { RouteLocationNormalized } from 'vue-router'\nimport validateTodoId from '~\/middleware\/validate-todo-id'\n\nconst { abortNavigationMock, createErrorMock } = vi.hoisted(() => {\n return {\n abortNavigationMock: vi.fn(),\n createErrorMock: vi.fn((err) => err),\n }\n})\n\nmockNuxtImport('abortNavigation', () => abortNavigationMock)\nmockNuxtImport('createError', () => createErrorMock)\n\nfunction fakeRoute(id: string): RouteLocationNormalized {\n return { params: { id } } as unknown as RouteLocationNormalized\n}\n\nconst homeRoute = {\n name: 'index',\n path: '\/',\n fullPath: '\/',\n} as RouteLocationNormalized\n\ndescribe('validate-todo-id middleware', () => {\n beforeEach(() => {\n vi.clearAllMocks()\n })\n\n test('allows navigation for a valid numeric id', () => {\n validateTodoId(fakeRoute('42'), homeRoute)\n\n expect(abortNavigationMock).not.toHaveBeenCalled()\n })\n\n test('aborts navigation for a non-numeric id', () => {\n validateTodoId(fakeRoute('abc'), homeRoute)\n\n expect(createErrorMock).toHaveBeenCalledWith(\n expect.objectContaining({\n statusCode: 400,\n statusMessage: 'Invalid todo id: \"abc\"',\n }),\n )\n expect(abortNavigationMock).toHaveBeenCalled()\n })\n\n test('aborts navigation for an empty id', () => {\n validateTodoId(fakeRoute(''), homeRoute)\n\n expect(createErrorMock).toHaveBeenCalledWith(\n expect.objectContaining({\n statusCode: 400,\n statusMessage: 'Invalid todo id: \"\"',\n }),\n )\n expect(abortNavigationMock).toHaveBeenCalled()\n })\n})<\/pre>\nUse isolated middleware tests for fast validation of route rules. Keep at least one page-level runtime test to confirm the middleware is actually connected to the route.<\/p>\n
Tier 3: End-to-end tests in the node<\/code> environment<\/h2>\nE2E tests exercise the full Nuxt stack. Unlike happy-dom<\/code> tests, they do not assert against a fake DOM. Unlike nuxt<\/code> environment tests, they can run against a real Nuxt server and, if needed, a real browser.<\/p>\nUse e2e tests for critical flows where SSR, routing, middleware, API handlers, hydration, and browser interaction all need to work together.<\/p>\n
Smoke test SSR output with setup<\/code> and $fetch<\/code><\/h3>\n
![\"An](\"https:\/\/blog.logrocket.com\/wp-content\/uploads\/2026\/06\/Build-a-headless-table-engine-in-Vue-3-1.png\")
\n![\"Multiple](\"https:\/\/paper-attachments.dropboxusercontent.com\/s_5103AA66F1427B1EB1DAA68D3B237BDD69BE2190D7BE6F6D82206DCEFF781726_1777834274963_difference-apis.excalidraw.svg\")