### Integration Tests (Vitest)
For: API routes, Server Actions, data access functions.

Mock Supabase client for isolation:

### E2E Tests (Playwright)
For: critical user flows (auth, main feature happy paths).

Location: `e2e/<flow>.spec.ts`.

## Running Tests

### Full Suite

## Failure Analysis & Auto-Fix Workflow

When tests fail:

1. **Read the error output carefully.** Identify if it is a test bug or a code bug.
2. **If test bug:** fix the test (wrong expectation, missing mock, outdated snapshot).
3. **If code bug:** fix the source code, then re-run the failing test to confirm.
4. **If flaky test:** add retry logic or improve test isolation. Mark with `// TODO: flaky - investigate`.
5. **Re-run the full suite** after any fix to check for regressions.
6. **Commit fixes:** `git add -A && git commit -m "test: fix <description>"`.

## Linting & Formatting

Run before every commit:

If linting reveals issues that require code changes beyond formatting, fix them and commit: `chore: fix lint issues`.

## Writing Tests for Existing Code

When asked to "add tests" for existing code:

1. Read the source file thoroughly.
2. Identify all public functions/exports.
3. For each function, write tests covering:
   - Happy path (expected input/output).
   - Edge cases (empty input, null, boundary values).
   - Error cases (invalid input, thrown exceptions).
4. Aim for meaningful coverage, not 100% line coverage. Focus on business logic.

## Test Data Patterns

- Use factory functions for test data, not raw objects.
- Keep test data close to tests (in the test file or a `__fixtures__` folder).
- Never use production data in tests.
- Clean up any side effects after each test.

import { describe, it, expect } from "vitest";
import { formatCurrency } from "@/lib/utils";

describe("formatCurrency", () => {
  it("formats BRL correctly", () => {
    expect(formatCurrency(1999, "BRL")).toBe("R$ 19,99");
  });

  it("handles zero", () => {
    expect(formatCurrency(0, "BRL")).toBe("R$ 0,00");
  });

  it("handles negative values", () => {
    expect(formatCurrency(-500, "BRL")).toBe("-R$ 5,00");
  });
});

import { describe, it, expect, vi, beforeEach } from "vitest";
import { GET } from "@/app/api/entities/route";
import { NextRequest } from "next/server";

vi.mock("@/lib/supabase/server", () => ({
  createClient: vi.fn(() => ({
    auth: {
      getUser: vi.fn(() => ({
        data: { user: { id: "test-user-id" } },
      })),
    },
    from: vi.fn(() => ({
      select: vi.fn(() => ({
        order: vi.fn(() => ({
          data: [{ id: 1, name: "Test" }],
          error: null,
        })),
      })),
    })),
  })),
}));

describe("GET /api/entities", () => {
  it("returns entities for authenticated user", async () => {
    const request = new NextRequest("http://localhost:3000/api/entities");
    const response = await GET(request);
    const data = await response.json();
    expect(response.status).toBe(200);
    expect(data).toHaveLength(1);
  });
});

import { test, expect } from "@playwright/test";

test.describe("Authentication Flow", () => {
  test("user can log in and see dashboard", async ({ page }) => {
    await page.goto("/login");
    await page.fill('[name="email"]', "[email protected]");
    await page.fill('[name="password"]', "testpassword123");
    await page.click('button[type="submit"]');
    await page.waitForURL("/dashboard");
    await expect(page.locator("h1")).toContainText("Dashboard");
  });
});

// src/__tests__/__fixtures__/factories.ts
export function makeUser(overrides = {}) {
  return {
    id: "test-user-id",
    email: "[email protected]",
    full_name: "Test User",
    ...overrides,
  };
}

export function makeEntity(overrides = {}) {
  return {
    id: 1,
    name: "Test Entity",
    user_id: "test-user-id",
    created_at: new Date().toISOString(),
    ...overrides,
  };
}