Mocking em Testes

Q: Qual a diferença entre vi.mock(), vi.fn() e vi.spyOn()?

vi.mock() substitui um módulo inteiro no topo do arquivo. vi.fn() cria uma função mock independente que rastreia chamadas. vi.spyOn() envolve um método existente para observar chamadas sem substituir completamente o módulo.

Q: Armadilha: Por que não consigo referenciar variáveis dentro de uma fábrica vi.mock()?

vi.mock() é içado acima das importações, então variáveis declaradas antes dele não estão disponíveis dentro da fábrica. Use vi.hoisted():

Q: Como evito que o estado do mock vaze entre testes?

Chame vi.clearAllMocks() ou vi.restoreAllMocks() em beforeEach. Isso redefine o histórico de chamadas e os valores de retorno entre os testes.

Q: Armadilha: Por que vi.mocked(fetch) lança um erro em tempo de execução?

vi.mocked() é apenas um helper de tipo. Se fetch não foi substituído por vi.fn() via vi.stubGlobal("fetch", vi.fn()), chamar métodos mockados nele falhará.

Q: Como configurar MSW com Vitest?

Crie handlers em src/mocks/handlers.ts usando http.get(), http.post(), etc. Crie um servidor em src/mocks/server.ts com setupServer(...handlers). Em vitest.setup.ts, chame server.listen() em beforeAll, server.resetHandlers() em afterEach, e server.close() em afterAll.

Q: Qual é o equivalente em Jest para vi.mock()?

jest.mock() funciona da mesma maneira. Substitua vi.fn() por jest.fn() e vi.mocked() por jest.mocked(). Os padrões são idênticos.

Faça mock de módulos, funções, APIs e internos do Next.js para isolar o código sob teste.

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

import { vi } from "vitest";
 
// Mock de um módulo
vi.mock("@/lib/analytics", () => ({
  trackEvent: vi.fn(),
}));
 
// Mock de uma função
const onSubmit = vi.fn();
onSubmit.mockResolvedValueOnce({ success: true });
 
// Mock de fetch
vi.stubGlobal("fetch", vi.fn());
vi.mocked(fetch).mockResolvedValue(
  new Response(JSON.stringify({ data: [] }), { status: 200 })
);
 
// Mock de next/navigation
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: vi.fn(), back: vi.fn(), refresh: vi.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams("?tab=settings"),
}));
 
// Mock de next/image
vi.mock("next/image", () => ({
  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
    <img {...props} />
  ),
}));

Quando usar isso: Quando seu componente depende de módulos externos, chamadas de API ou internos do Next.js que você precisa controlar em testes.

Exemplo de Trabalho

// src/components/user-profile.tsx
"use client";
 
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
 
interface User {
  id: number;
  name: string;
  email: string;
}
 
export function UserProfile({ userId }: { userId: number }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const router = useRouter();
 
  useEffect(() => {
    async function loadUser() {
      try {
        const res = await fetch(`/api/users/${userId}`);
        if (!res.ok) throw new Error("Failed to load user");
        setUser(await res.json());
      } catch (err) {
        setError(err instanceof Error ? err.message : "Unknown error");
      } finally {
        setLoading(false);
      }
    }
    loadUser();
  }, [userId]);
 
  if (loading) return <p>Loading...</p>;
  if (error) return <p role="alert">{error}</p>;
  if (!user) return null;
 
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <button onClick={() => router.push(`/users/${userId}/edit`)}>
        Edit Profile
      </button>
    </div>
  );
}

// src/components/user-profile.test.tsx
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { vi, describe, it, expect, beforeEach } from "vitest";
import { UserProfile } from "./user-profile";
 
// Mock de next/navigation
const mockPush = vi.fn();
vi.mock("next/navigation", () => ({
  useRouter: () => ({
    push: mockPush,
    back: vi.fn(),
    refresh: vi.fn(),
  }),
  usePathname: () => "/users/1",
  useSearchParams: () => new URLSearchParams(),
}));
 
describe("UserProfile", () => {
  const user = userEvent.setup();
 
  beforeEach(() => {
    vi.stubGlobal("fetch", vi.fn());
    mockPush.mockClear();
  });
 
  it("shows loading state initially", () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
    expect(screen.getByText("Loading...")).toBeInTheDocument();
  });
 
  it("renders user data on success", async () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
 
    expect(await screen.findByText("Alice")).toBeInTheDocument();
    expect(screen.getByText("alice@test.com")).toBeInTheDocument();
  });
 
  it("shows error on fetch failure", async () => {
    vi.mocked(fetch).mockResolvedValue(new Response(null, { status: 500 }));
    render(<UserProfile userId={1} />);
 
    expect(await screen.findByRole("alert")).toHaveTextContent(
      "Failed to load user"
    );
  });
 
  it("navigates to edit page on button click", async () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
 
    await screen.findByText("Alice");
    await user.click(screen.getByRole("button", { name: /edit profile/i }));
 
    expect(mockPush).toHaveBeenCalledWith("/users/1/edit");
  });
});

O que isso demonstra:

Mock de nível de módulo para next/navigation
Mocking de fetch com vi.stubGlobal
Extração de mockPush para asserção
Teste de estados de carregamento, sucesso, erro e navegação

Mergulho Profundo

Como Funciona

vi.mock() substitui um módulo inteiro no topo do arquivo -- ele é içado acima das importações pela transformação do Vitest
vi.fn() cria uma função mock que rastreia chamadas, argumentos e valores de retorno
vi.mocked() é um helper de tipo que converte uma função para seu tipo mockado, permitindo autocompletar para métodos mockados
vi.stubGlobal() substitui um global como fetch e o restaura quando você chama vi.restoreAllMocks()
Mocks de módulo persistem para o arquivo de teste inteiro, a menos que você chame vi.resetModules() entre os testes

Variações

MSW (Mock Service Worker) para mocking de API:

npm install -D msw

// src/mocks/handlers.ts
import { http, HttpResponse } from "msw";
 
export const handlers = [
  http.get("/api/users/:id", ({ params }) => {
    return HttpResponse.json({
      id: Number(params.id),
      name: "Alice",
      email: "alice@test.com",
    });
  }),
 
  http.post("/api/users", async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: 99, ...body }, { status: 201 });
  }),
 
  http.get("/api/users/:id", () => {
    return HttpResponse.json(
      { message: "Not found" },
      { status: 404 }
    );
  }),
];

// src/mocks/server.ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
 
export const server = setupServer(...handlers);

// vitest.setup.ts
import { server } from "./src/mocks/server";
import { beforeAll, afterAll, afterEach } from "vitest";
 
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// Teste usando MSW -- nenhum mock de fetch manual necessário
import { http, HttpResponse } from "msw";
import { server } from "@/mocks/server";
 
it("handles 404", async () => {
  // Sobrescrever para este teste específico
  server.use(
    http.get("/api/users/:id", () => {
      return HttpResponse.json({ message: "Not found" }, { status: 404 });
    })
  );
 
  render(<UserProfile userId={999} />);
  expect(await screen.findByRole("alert")).toBeInTheDocument();
});

Mocking com Jest (mesmos padrões, API diferente):

// Equivalente a jest.mock
jest.mock("next/navigation", () => ({
  useRouter: () => ({ push: jest.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams(),
}));
 
// Equivalente a jest.fn
const handleSubmit = jest.fn();
handleSubmit.mockResolvedValue({ success: true });

Espionar um método sem mockar completamente:

import * as analytics from "@/lib/analytics";
 
it("tracks page view", () => {
  const spy = vi.spyOn(analytics, "trackEvent");
  render(<Dashboard />);
  expect(spy).toHaveBeenCalledWith("page_view", { page: "dashboard" });
  spy.mockRestore();
});

Notas de TypeScript

// vi.mocked fornece segurança de tipo completa
vi.mocked(fetch).mockResolvedValue(
  new Response(JSON.stringify(data)) // TypeScript conhece a assinatura de fetch
);
 
// Tipando implementações de mock
vi.mock("@/lib/db", () => ({
  getUser: vi.fn<[number], Promise<User>>(),
}));
 
// Asserindo chamadas de mock com tipos
const mockFn = vi.fn<[string, number], boolean>();
mockFn("hello", 42);
expect(mockFn).toHaveBeenCalledWith("hello", 42);

Armadilhas

vi.mock não içado corretamente -- Vitest iça vi.mock() para o topo do arquivo, mas variáveis definidas antes dele não estão disponíveis dentro da fábrica. Correção: Use vi.hoisted() para declarar variáveis que precisam estar disponíveis dentro de vi.mock():
```
const \{ mockPush \} = vi.hoisted(() => (\{
  mockPush: vi.fn(),
\}));
 
vi.mock("next/navigation", () => (\{
  useRouter: () => (\{ push: mockPush \}),
\}));
```
Mockando demais -- Mockar cada dependência faz com que os testes passem mesmo quando as integrações estão quebradas. Correção: Use MSW para mocking de API (testa código fetch real) e apenas mock o que é verdadeiramente externo.
Estado do mock vazando entre testes -- Valores de retorno do mock persistem entre testes no mesmo arquivo. Correção: Chame vi.clearAllMocks() ou vi.restoreAllMocks() em beforeEach.
vi.mocked em funções não mockadas -- vi.mocked(fetch) falha em tempo de execução se fetch não foi substituído por vi.fn(). Correção: Sempre vi.stubGlobal("fetch", vi.fn()) antes de usar vi.mocked(fetch).
MSW interceptando todas as requisições -- onUnhandledRequest: "error" lança um erro para requisições não correspondidas. Correção: Forneça handlers para todas as requisições que seus testes fazem, ou use "warn" durante o desenvolvimento.

Alternativas

Alternativa	Use Quando	Não Use Quando
MSW	Você quer mocking de API em nível de rede que funciona em testes e Storybook	Você precisa mockar módulos não HTTP
`vi.mock` / `jest.mock`	Você precisa substituir internos de módulos (hooks, funções utilitárias)	Você só precisa mockar chamadas HTTP (prefira MSW)
`vi.spyOn` / `jest.spyOn`	Você quer observar chamadas sem alterar o comportamento	Você precisa substituir completamente um módulo
Injeção de dependência	A arquitetura suporta passar dependências como props ou configuração	Você precisaria refatorar pesadamente

FAQs

Qual a diferença entre `vi.mock()`, `vi.fn()` e `vi.spyOn()`?

vi.mock() substitui um módulo inteiro no topo do arquivo.
vi.fn() cria uma função mock independente que rastreia chamadas.
vi.spyOn() envolve um método existente para observar chamadas sem substituir completamente o módulo.

Como faço mock de `next/navigation` em um teste?

const mockPush = vi.fn();
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: mockPush, back: vi.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams(),
}));

Armadilha: Por que não consigo referenciar variáveis dentro de uma fábrica `vi.mock()`?

vi.mock() é içado acima das importações, então variáveis declaradas antes dele não estão disponíveis dentro da fábrica. Use vi.hoisted():

const { mockPush } = vi.hoisted(() => ({
  mockPush: vi.fn(),
}));
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: mockPush }),
}));

O que é MSW e quando devo usá-lo em vez de `vi.stubGlobal("fetch")`?

MSW (Mock Service Worker) intercepta fetch no nível da rede.
Use MSW quando você tem muitos endpoints de API ou quer mocks que funcionem tanto em testes quanto no Storybook.
Use vi.stubGlobal("fetch") para mocking rápido e pontual.

Como evito que o estado do mock vaze entre testes?

Chame vi.clearAllMocks() ou vi.restoreAllMocks() em beforeEach. Isso redefine o histórico de chamadas e os valores de retorno entre os testes.

Como faço mock de `next/image` em testes?

vi.mock("next/image", () => ({
  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
    <img {...props} />
  ),
}));

Armadilha: Por que `vi.mocked(fetch)` lança um erro em tempo de execução?

vi.mocked() é apenas um helper de tipo. Se fetch não foi substituído por vi.fn() via vi.stubGlobal("fetch", vi.fn()), chamar métodos mockados nele falhará.

Como tipar parâmetros e valores de retorno de funções mock em TypeScript?

const mockFn = vi.fn<[string, number], boolean>();
vi.mock("@/lib/db", () => ({
  getUser: vi.fn<[number], Promise<User>>(),
}));

Como configurar MSW com Vitest?

Crie handlers em src/mocks/handlers.ts usando http.get(), http.post(), etc.
Crie um servidor em src/mocks/server.ts com setupServer(...handlers).
Em vitest.setup.ts, chame server.listen() em beforeAll, server.resetHandlers() em afterEach, e server.close() em afterAll.

O que `onUnhandledRequest: "error"` faz no MSW?

Ele lança um erro para qualquer requisição fetch que não corresponda a um handler definido. Isso garante que todas as chamadas de API em seus testes sejam explicitamente tratadas. Use "warn" durante o desenvolvimento se isso for muito rigoroso.

Como espionar uma função sem alterar seu comportamento?

const spy = vi.spyOn(analytics, "trackEvent");
render(<Dashboard />);
expect(spy).toHaveBeenCalledWith("page_view", { page: "dashboard" });
spy.mockRestore();

Qual é o equivalente em Jest para `vi.mock()`?

jest.mock() funciona da mesma maneira. Substitua vi.fn() por jest.fn() e vi.mocked() por jest.mocked(). Os padrões são idênticos.

Relacionados

Testando Comportamento Assíncrono -- usando MSW com testes assíncronos
Testando Formulários -- mockando manipuladores de submissão de formulário
Testando Componentes e Ações de Servidor -- mockando banco de dados e serviços externos
Fundamentos da Biblioteca de Testes React -- padrões de teste principais

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

import { vi } from "vitest";
 
// Mock de um módulo
vi.mock("@/lib/analytics", () => ({
  trackEvent: vi.fn(),
}));
 
// Mock de uma função
const onSubmit = vi.fn();
onSubmit.mockResolvedValueOnce({ success: true });
 
// Mock de fetch
vi.stubGlobal("fetch", vi.fn());
vi.mocked(fetch).mockResolvedValue(
  new Response(JSON.stringify({ data: [] }), { status: 200 })
);
 
// Mock de next/navigation
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: vi.fn(), back: vi.fn(), refresh: vi.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams("?tab=settings"),
}));
 
// Mock de next/image
vi.mock("next/image", () => ({
  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
    <img {...props} />
  ),
}));

Quando usar isso: Quando seu componente depende de módulos externos, chamadas de API ou internos do Next.js que você precisa controlar em testes.

Exemplo de Trabalho

// src/components/user-profile.tsx
"use client";
 
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
 
interface User {
  id: number;
  name: string;
  email: string;
}
 
export function UserProfile({ userId }: { userId: number }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);
  const router = useRouter();
 
  useEffect(() => {
    async function loadUser() {
      try {
        const res = await fetch(`/api/users/${userId}`);
        if (!res.ok) throw new Error("Failed to load user");
        setUser(await res.json());
      } catch (err) {
        setError(err instanceof Error ? err.message : "Unknown error");
      } finally {
        setLoading(false);
      }
    }
    loadUser();
  }, [userId]);
 
  if (loading) return <p>Loading...</p>;
  if (error) return <p role="alert">{error}</p>;
  if (!user) return null;
 
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <button onClick={() => router.push(`/users/${userId}/edit`)}>
        Edit Profile
      </button>
    </div>
  );
}

// src/components/user-profile.test.tsx
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { vi, describe, it, expect, beforeEach } from "vitest";
import { UserProfile } from "./user-profile";
 
// Mock de next/navigation
const mockPush = vi.fn();
vi.mock("next/navigation", () => ({
  useRouter: () => ({
    push: mockPush,
    back: vi.fn(),
    refresh: vi.fn(),
  }),
  usePathname: () => "/users/1",
  useSearchParams: () => new URLSearchParams(),
}));
 
describe("UserProfile", () => {
  const user = userEvent.setup();
 
  beforeEach(() => {
    vi.stubGlobal("fetch", vi.fn());
    mockPush.mockClear();
  });
 
  it("shows loading state initially", () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
    expect(screen.getByText("Loading...")).toBeInTheDocument();
  });
 
  it("renders user data on success", async () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
 
    expect(await screen.findByText("Alice")).toBeInTheDocument();
    expect(screen.getByText("alice@test.com")).toBeInTheDocument();
  });
 
  it("shows error on fetch failure", async () => {
    vi.mocked(fetch).mockResolvedValue(new Response(null, { status: 500 }));
    render(<UserProfile userId={1} />);
 
    expect(await screen.findByRole("alert")).toHaveTextContent(
      "Failed to load user"
    );
  });
 
  it("navigates to edit page on button click", async () => {
    vi.mocked(fetch).mockResolvedValue(
      new Response(JSON.stringify({ id: 1, name: "Alice", email: "alice@test.com" }))
    );
    render(<UserProfile userId={1} />);
 
    await screen.findByText("Alice");
    await user.click(screen.getByRole("button", { name: /edit profile/i }));
 
    expect(mockPush).toHaveBeenCalledWith("/users/1/edit");
  });
});

O que isso demonstra:

Mock de nível de módulo para next/navigation
Mocking de fetch com vi.stubGlobal
Extração de mockPush para asserção
Teste de estados de carregamento, sucesso, erro e navegação

Mergulho Profundo

Como Funciona

vi.mock() substitui um módulo inteiro no topo do arquivo -- ele é içado acima das importações pela transformação do Vitest
vi.fn() cria uma função mock que rastreia chamadas, argumentos e valores de retorno
vi.mocked() é um helper de tipo que converte uma função para seu tipo mockado, permitindo autocompletar para métodos mockados
vi.stubGlobal() substitui um global como fetch e o restaura quando você chama vi.restoreAllMocks()
Mocks de módulo persistem para o arquivo de teste inteiro, a menos que você chame vi.resetModules() entre os testes

Variações

MSW (Mock Service Worker) para mocking de API:

npm install -D msw

// src/mocks/handlers.ts
import { http, HttpResponse } from "msw";
 
export const handlers = [
  http.get("/api/users/:id", ({ params }) => {
    return HttpResponse.json({
      id: Number(params.id),
      name: "Alice",
      email: "alice@test.com",
    });
  }),
 
  http.post("/api/users", async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: 99, ...body }, { status: 201 });
  }),
 
  http.get("/api/users/:id", () => {
    return HttpResponse.json(
      { message: "Not found" },
      { status: 404 }
    );
  }),
];

// src/mocks/server.ts
import { setupServer } from "msw/node";
import { handlers } from "./handlers";
 
export const server = setupServer(...handlers);

// vitest.setup.ts
import { server } from "./src/mocks/server";
import { beforeAll, afterAll, afterEach } from "vitest";
 
beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

// Teste usando MSW -- nenhum mock de fetch manual necessário
import { http, HttpResponse } from "msw";
import { server } from "@/mocks/server";
 
it("handles 404", async () => {
  // Sobrescrever para este teste específico
  server.use(
    http.get("/api/users/:id", () => {
      return HttpResponse.json({ message: "Not found" }, { status: 404 });
    })
  );
 
  render(<UserProfile userId={999} />);
  expect(await screen.findByRole("alert")).toBeInTheDocument();
});

Mocking com Jest (mesmos padrões, API diferente):

// Equivalente a jest.mock
jest.mock("next/navigation", () => ({
  useRouter: () => ({ push: jest.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams(),
}));
 
// Equivalente a jest.fn
const handleSubmit = jest.fn();
handleSubmit.mockResolvedValue({ success: true });

Espionar um método sem mockar completamente:

import * as analytics from "@/lib/analytics";
 
it("tracks page view", () => {
  const spy = vi.spyOn(analytics, "trackEvent");
  render(<Dashboard />);
  expect(spy).toHaveBeenCalledWith("page_view", { page: "dashboard" });
  spy.mockRestore();
});

Notas de TypeScript

// vi.mocked fornece segurança de tipo completa
vi.mocked(fetch).mockResolvedValue(
  new Response(JSON.stringify(data)) // TypeScript conhece a assinatura de fetch
);
 
// Tipando implementações de mock
vi.mock("@/lib/db", () => ({
  getUser: vi.fn<[number], Promise<User>>(),
}));
 
// Asserindo chamadas de mock com tipos
const mockFn = vi.fn<[string, number], boolean>();
mockFn("hello", 42);
expect(mockFn).toHaveBeenCalledWith("hello", 42);

Armadilhas

vi.mock não içado corretamente -- Vitest iça vi.mock() para o topo do arquivo, mas variáveis definidas antes dele não estão disponíveis dentro da fábrica. Correção: Use vi.hoisted() para declarar variáveis que precisam estar disponíveis dentro de vi.mock():
```
const \{ mockPush \} = vi.hoisted(() => (\{
  mockPush: vi.fn(),
\}));
 
vi.mock("next/navigation", () => (\{
  useRouter: () => (\{ push: mockPush \}),
\}));
```
Mockando demais -- Mockar cada dependência faz com que os testes passem mesmo quando as integrações estão quebradas. Correção: Use MSW para mocking de API (testa código fetch real) e apenas mock o que é verdadeiramente externo.
Estado do mock vazando entre testes -- Valores de retorno do mock persistem entre testes no mesmo arquivo. Correção: Chame vi.clearAllMocks() ou vi.restoreAllMocks() em beforeEach.
vi.mocked em funções não mockadas -- vi.mocked(fetch) falha em tempo de execução se fetch não foi substituído por vi.fn(). Correção: Sempre vi.stubGlobal("fetch", vi.fn()) antes de usar vi.mocked(fetch).
MSW interceptando todas as requisições -- onUnhandledRequest: "error" lança um erro para requisições não correspondidas. Correção: Forneça handlers para todas as requisições que seus testes fazem, ou use "warn" durante o desenvolvimento.

Alternativas

Alternativa	Use Quando	Não Use Quando
MSW	Você quer mocking de API em nível de rede que funciona em testes e Storybook	Você precisa mockar módulos não HTTP
`vi.mock` / `jest.mock`	Você precisa substituir internos de módulos (hooks, funções utilitárias)	Você só precisa mockar chamadas HTTP (prefira MSW)
`vi.spyOn` / `jest.spyOn`	Você quer observar chamadas sem alterar o comportamento	Você precisa substituir completamente um módulo
Injeção de dependência	A arquitetura suporta passar dependências como props ou configuração	Você precisaria refatorar pesadamente

FAQs

Qual a diferença entre `vi.mock()`, `vi.fn()` e `vi.spyOn()`?

vi.mock() substitui um módulo inteiro no topo do arquivo.
vi.fn() cria uma função mock independente que rastreia chamadas.
vi.spyOn() envolve um método existente para observar chamadas sem substituir completamente o módulo.

Como faço mock de `next/navigation` em um teste?

const mockPush = vi.fn();
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: mockPush, back: vi.fn() }),
  usePathname: () => "/dashboard",
  useSearchParams: () => new URLSearchParams(),
}));

Armadilha: Por que não consigo referenciar variáveis dentro de uma fábrica `vi.mock()`?

vi.mock() é içado acima das importações, então variáveis declaradas antes dele não estão disponíveis dentro da fábrica. Use vi.hoisted():

const { mockPush } = vi.hoisted(() => ({
  mockPush: vi.fn(),
}));
vi.mock("next/navigation", () => ({
  useRouter: () => ({ push: mockPush }),
}));

O que é MSW e quando devo usá-lo em vez de `vi.stubGlobal("fetch")`?

MSW (Mock Service Worker) intercepta fetch no nível da rede.
Use MSW quando você tem muitos endpoints de API ou quer mocks que funcionem tanto em testes quanto no Storybook.
Use vi.stubGlobal("fetch") para mocking rápido e pontual.

Como evito que o estado do mock vaze entre testes?

Chame vi.clearAllMocks() ou vi.restoreAllMocks() em beforeEach. Isso redefine o histórico de chamadas e os valores de retorno entre os testes.

Como faço mock de `next/image` em testes?

vi.mock("next/image", () => ({
  default: (props: React.ImgHTMLAttributes<HTMLImageElement>) => (
    <img {...props} />
  ),
}));

Armadilha: Por que `vi.mocked(fetch)` lança um erro em tempo de execução?

vi.mocked() é apenas um helper de tipo. Se fetch não foi substituído por vi.fn() via vi.stubGlobal("fetch", vi.fn()), chamar métodos mockados nele falhará.

Como tipar parâmetros e valores de retorno de funções mock em TypeScript?

const mockFn = vi.fn<[string, number], boolean>();
vi.mock("@/lib/db", () => ({
  getUser: vi.fn<[number], Promise<User>>(),
}));

Como configurar MSW com Vitest?

Crie handlers em src/mocks/handlers.ts usando http.get(), http.post(), etc.
Crie um servidor em src/mocks/server.ts com setupServer(...handlers).
Em vitest.setup.ts, chame server.listen() em beforeAll, server.resetHandlers() em afterEach, e server.close() em afterAll.

O que `onUnhandledRequest: "error"` faz no MSW?

Como espionar uma função sem alterar seu comportamento?

const spy = vi.spyOn(analytics, "trackEvent");
render(<Dashboard />);
expect(spy).toHaveBeenCalledWith("page_view", { page: "dashboard" });
spy.mockRestore();

Qual é o equivalente em Jest para `vi.mock()`?

jest.mock() funciona da mesma maneira. Substitua vi.fn() por jest.fn() e vi.mocked() por jest.mocked(). Os padrões são idênticos.

Relacionados

Testando Comportamento Assíncrono -- usando MSW com testes assíncronos
Testando Formulários -- mockando manipuladores de submissão de formulário
Testando Componentes e Ações de Servidor -- mockando banco de dados e serviços externos
Fundamentos da Biblioteca de Testes React -- padrões de teste principais

Mocking em Testes

Buscar na documentação

Mocking em Testes