API Mocks

Helpers reutilizáveis para mockar APIs nos testes Playwright. Use sempre esses helpers em vez de criar mocks manualmente.

Ver também: Arquitetura de Testes | Guia E2E

Objetivo

• ✅ Consistência: Todos os testes usam os mesmos mocks
• ✅ Manutenibilidade: Mocks centralizados em um único lugar
• ✅ Produtividade: Setup rápido com funções pré-configuradas
• ✅ Redução de código: Menos boilerplate nos testes

Uso Rápido

Setup Completo (Fluxo de Template)

import { setupTemplateFlowMocks } from "../helpers";

test.beforeEach(async ({ page }) => {
  await setupTemplateFlowMocks(page, {
    templateId: "template-123",
    templateSlug: "test-template",
    templateName: "My Template",
    planId: null, // FREE ou 'plan-id' para PAID
  });
});

Setup Modular

import {
  setupCommonApiMocks,
  setupAuthMocks,
  setupTemplateMocks,
} from "../helpers";

test.beforeEach(async ({ page }) => {
  await setupCommonApiMocks(page);
  await setupAuthMocks(page);
  await setupTemplateMocks(page, { templateId: "my-template" });
});

Helpers Disponíveis

setupCommonApiMocks(page)

Mocks básicos necessários para páginas autenticadas:

• ✅ Current user
• ✅ Connections
• ✅ Subscription status
• ✅ Account info
• ✅ Catch-all para endpoints não mockados

Quando usar: Em praticamente todos os testes.

---

setupAuthMocks(page, options?)

Mocks de autenticação:

• ✅ Login (/api/console/login)
• ✅ Sign-in (/api/console/sign-in)
• ✅ Sign-up (/api/console/sign-up)
• ✅ Email verification

Opções:

{
  invalidCredentials?: string[],  // Emails com credenciais inválidas
  existingEmails?: string[],      // Emails já cadastrados
  unverifiedEmails?: string[]     // Emails não verificados
}

Exemplo:

await setupAuthMocks(page, {
  invalidCredentials: ["wrong@example.com"],
  existingEmails: ["existing@example.com"],
});

---

setupProfileMocks(page)

Mocks de atualização de perfil:

• ✅ Contact info (/api/console/profile/contact-info)
• ✅ Account metadata (/api/console/account/metadata)
• ✅ Update user (/api/console/update-user)

Quando usar: Testes que envolvem edição de perfil ou wizard.

---

setupTemplateMocks(page, options?)

Mocks relacionados a templates:

• ✅ Template details (public)
• ✅ Template installation
• ✅ Template list

Opções:

{
  templateId?: string,
  templateSlug?: string,
  templateName?: string,
  planId?: string | null,      // null = FREE, string = PAID
  planPrice?: number | null,
  couponId?: string | null,
  isInstalled?: boolean
}

Exemplo - Template FREE:

await setupTemplateMocks(page, {
  templateSlug: "free-template",
  planId: null,
});

Exemplo - Template PAID:

await setupTemplateMocks(page, {
  templateSlug: "premium-template",
  planId: "plan-premium",
  planPrice: 9900,
  couponId: "WELCOME50",
});

---

setupPaymentMocks(page, options?)

Mocks de pagamento (Stripe):

• ✅ Setup intent
• ✅ Payment method attach
• ✅ Create subscription

Opções:

{
  setupIntentSecret?: string,
  paymentMethodId?: string,
  subscriptionId?: string,
  shouldFailPayment?: boolean  // Simular erro de pagamento
}

Exemplo - Pagamento com sucesso:

await setupPaymentMocks(page);

Exemplo - Simular falha:

await setupPaymentMocks(page, {
  shouldFailPayment: true,
});

---

setupTrackingMocks(page)

Mocks de analytics/tracking:

• ✅ Track events (/api/*/track)
• ✅ Identify (/api/*/identify)

Quando usar: Sempre (já incluído em setupTemplateFlowMocks).

---

setupTemplateFlowMocks(page, options?)

Helper all-in-one que combina todos os mocks acima. Use este para testes de template.

Inclui:

• ✅ Common API mocks
• ✅ Auth mocks
• ✅ Profile mocks
• ✅ Template mocks
• ✅ Payment mocks
• ✅ Tracking mocks

Opções: Mesmas de setupTemplateMocks().

Exemplo:

test.beforeEach(async ({ page }) => {
  await setupTemplateFlowMocks(page, {
    templateSlug: "my-template",
    planId: "plan-123",
  });
});

Exemplos Práticos

Teste de Template Gratuito

import { setupTemplateFlowMocks } from "../helpers";

test.describe("Free Template Flow", () => {
  test.beforeEach(async ({ page }) => {
    await setupTemplateFlowMocks(page, {
      templateId: "free-123",
      templateSlug: "free-template",
      planId: null, // FREE
    });
  });

  test("should install free template", async ({ page }) => {
    // Teste aqui...
  });
});

Teste de Template Pago

import { setupTemplateFlowMocks } from "../helpers";

test.describe("Paid Template Flow", () => {
  test.beforeEach(async ({ page }) => {
    await setupTemplateFlowMocks(page, {
      templateId: "paid-123",
      templateSlug: "premium-template",
      planId: "plan-premium",
      planPrice: 9900,
    });
  });

  test("should show checkout", async ({ page }) => {
    // Teste aqui...
  });
});

Teste com Erro de Login

import { setupCommonApiMocks, setupAuthMocks } from "../helpers";

test.describe("Login Errors", () => {
  test.beforeEach(async ({ page }) => {
    await setupCommonApiMocks(page);
    await setupAuthMocks(page, {
      invalidCredentials: ["wrong@example.com"],
    });
  });

  test("should show error for invalid credentials", async ({ page }) => {
    // Teste aqui...
  });
});

Customizando Tracking

import { setupTemplateFlowMocks } from "../helpers";

test.beforeEach(async ({ page }) => {
  const trackedEvents: any[] = [];

  await setupTemplateFlowMocks(page, {
    templateSlug: "test-template",
  });

  // Override tracking para capturar eventos
  await page.route("**/api/*/track", async (route) => {
    const data = route.request().postDataJSON();
    trackedEvents.push(data);
    await route.fulfill({ status: 200, body: "{}" });
  });
});

Boas Práticas

✅ Fazer

// ✅ Usar helpers pré-configurados
await setupTemplateFlowMocks(page, { templateSlug: "test" });

// ✅ Customizar apenas o necessário
await setupAuthMocks(page, { invalidCredentials: ["bad@test.com"] });

// ✅ Setup modular quando não precisa de tudo
await setupCommonApiMocks(page);
await setupAuthMocks(page);

❌ Evitar

// ❌ Não criar mocks manualmente
await page.route('**/api/console/login', async (route) => {
  await route.fulfill({ ... }); // Use setupAuthMocks() em vez disso
});

// ❌ Não duplicar código entre testes
test.beforeEach(async ({ page }) => {
  // 50 linhas de mocks manuais... ❌
});

Estendendo os Helpers

Se precisar de novos mocks, adicione no arquivo api-mocks.ts:

export const setupMyNewMocks = async (page: Page) => {
  await page.route("**/api/my-endpoint", async (route) => {
    await createJsonResponse(route, { data: "test" });
  });
};

Referências

• Playwright Route Mocking
• Utilitários Compartilhados - Fixtures compartilhadas