Pinpoint Testing

PinPoint Testing Guide

When to Use This Skill

Use this skill when:

• Writing new tests (unit, integration, or E2E)
• Debugging test failures
• Setting up test infrastructure
• Understanding test patterns and organization
• User mentions: "test", "testing", "spec", "E2E", "Playwright", "Vitest", "coverage"

Quick Reference

Test Distribution (100-150 tests total)

• 70% Unit (~70-100): Pure functions, utilities, validation
• 25% Integration (~25-35): DB queries with worker-scoped PGlite
• 5% E2E (~5-10): Critical flows (Playwright)

Commands

pnpm run check          # Quick: types + lint + unit (~5s)
pnpm test               # Unit tests only
pnpm test -- path/to/file.test.ts  # Targeted unit test
pnpm run test:integration          # DB integration tests (requires supabase start)
pnpm run smoke                     # E2E smoke tests (Playwright)
pnpm run preflight                 # Full suite (~60s) - run before commit

Which Tests to Run (Decision Tree)

1. Changed pure logic/utils? → pnpm run check (unit tests, ~12s)
2. Changed a single E2E-relevant file? → pnpm exec playwright test e2e/path/to/file.spec.ts --project=chromium (~15-30s)
3. Changed UI components/forms? → pnpm run smoke (~60s)
4. Changed auth/permissions/middleware? → pnpm run smoke + targeted full specs
5. Changed DB schema/migrations? → pnpm run preflight (full suite)
6. NEVER run e2e:full locally unless explicitly asked — that's what CI is for

Key rules for agents:

• Always use --project=chromium for targeted runs (skip Mobile Chrome unless testing responsive)
• Use --headed for debugging visual issues
• pnpm run check catches 90% of issues — E2E is for integration verification, not iteration
• If a test is flaky locally, report it — don't retry in a loop

Critical Rules

1. Worker-scoped PGlite only: Per-test instances cause lockups
2. No testing Server Components directly: Use E2E instead
3. Test behavior, not implementation: Focus on outcomes
4. Integration tests location: src/test/integration/supabase/*.test.ts

Detailed Documentation

Read these files for comprehensive testing guidance:

# Full testing strategy and patterns
cat docs/TESTING_PLAN.md

# E2E-specific patterns with Playwright
cat docs/E2E_BEST_PRACTICES.md

# Testing-related non-negotiables
cat docs/NON_NEGOTIABLES.md | grep -A 10 "## Testing"

Code Examples

Unit Test Pattern

// Pure function testing
import { describe, it, expect } from "vitest";
import { calculateSeverityScore } from "~/lib/utils";

describe("calculateSeverityScore", () => {
  it("returns 10 for unplayable", () => {
    expect(calculateSeverityScore("unplayable")).toBe(10);
  });

  it("returns 5 for playable", () => {
    expect(calculateSeverityScore("playable")).toBe(5);
  });

  it("returns 1 for minor", () => {
    expect(calculateSeverityScore("minor")).toBe(1);
  });
});

Integration Test with PGlite (Worker-Scoped)

import { describe, it, expect, beforeAll } from "vitest";
import { getPGlite } from "~/test/setup/pglite";
import { getIssuesForMachine } from "~/server/data-access/issues";

describe("getIssuesForMachine", () => {
  let db: PGlite;

  beforeAll(async () => {
    db = getPGlite(); // Shared worker instance - CRITICAL!

    // Seed test data
    await db.exec(`
      INSERT INTO machines (id, name) VALUES ('machine-1', 'Test Machine');
      INSERT INTO issues (id, machine_id, title, severity)
      VALUES
        ('issue-1', 'machine-1', 'Broken flipper', 'playable'),
        ('issue-2', 'machine-1', 'Dead display', 'unplayable');
    `);
  });

  it("returns issues for the specified machine", async () => {
    const issues = await getIssuesForMachine("machine-1");
    expect(issues).toHaveLength(2);
    expect(issues[0].title).toBe("Broken flipper");
  });

  it("returns empty array for machine with no issues", async () => {
    const issues = await getIssuesForMachine("machine-2");
    expect(issues).toHaveLength(0);
  });
});

E2E Test with Playwright

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

test.describe("Issue Creation Flow", () => {
  test("user can create a new issue", async ({ page }) => {
    // Navigate to machine page
    await page.goto("/machines/test-machine-id");

    // Click "New Issue" button
    await page.getByRole("button", { name: "New Issue" }).click();

    // Fill out form
    await page.getByLabel("Title").fill("Broken left flipper");
    await page.getByLabel("Description").fill("Not responding to button press");
    await page.getByLabel("Severity").selectOption("playable");

    // Submit form
    await page.getByRole("button", { name: "Create Issue" }).click();

    // Verify success
    await expect(page.getByText("Issue created successfully")).toBeVisible();
    await expect(page).toHaveURL(/\/issues\/[\w-]+/);
  });
});

Testing Patterns from TESTING_PLAN.md

What to Test at Each Level

Unit Tests (70%):

• Pure functions and utilities
• Input validation (Zod schemas)
• Type guards and converters
• Business logic calculations
• Error handling in isolated functions

Integration Tests (25%):

• Database queries (Drizzle with PGlite)
• Server Action data access layers
• Auth flows (Supabase SSR)
• API route handlers
• Multi-step workflows involving DB

E2E Tests (5%):

• Critical user journeys (login, create issue, resolve issue)
• Form submissions with validation
• Navigation and routing
• Auth state persistence
• Mobile responsiveness (if critical)

Test Organization

src/test/
├── unit/                    # Unit tests
│   ├── lib/
│   │   └── utils.test.ts
│   └── validation/
│       └── issue.test.ts
└── integration/
    └── supabase/            # Integration tests requiring Supabase
        ├── issues.test.ts
        └── auth.test.ts

e2e/
├── smoke/                   # Critical E2E flows (run in CI)
│   ├── auth.spec.ts
│   └── issues.spec.ts
└── full/                    # Comprehensive E2E (optional, slower)
    └── advanced-flows.spec.ts

PGlite Best Practices

✅ Correct: Worker-Scoped Instance

import { getPGlite } from "~/test/setup/pglite";

describe("Database operations", () => {
  beforeAll(async () => {
    const db = getPGlite(); // Shared worker instance
    await db.exec("INSERT INTO ...");
  });

  it("query works", async () => {
    const result = await db.query("SELECT * FROM ...");
    expect(result.rows).toHaveLength(1);
  });
});

❌ Wrong: Per-Test Instance (Causes Lockups)

// DON'T DO THIS - causes system lockups!
beforeEach(async () => {
  const db = new PGlite(); // Creates new instance every test
});

E2E Patterns from E2E_BEST_PRACTICES.md

Selector Strategy

1. Prefer: Accessibility roles and labels (getByRole, getByLabel)
2. Fallback: Test IDs (data-testid) when roles aren't sufficient
3. Avoid: CSS selectors, text content that changes

Test Organization

• Smoke tests (e2e/smoke/): Critical flows, run in CI
• Full tests (e2e/full/): Comprehensive coverage, run less frequently
• Keep tests independent (no shared state between tests)

Common Patterns

// Wait for real UI state, not arbitrary timeouts
await expect(page.getByText("Loading...")).toBeHidden();
await expect(page.getByText("Data loaded")).toBeVisible();

// Use locators for better error messages
const submitButton = page.getByRole("button", { name: "Submit" });
await expect(submitButton).toBeEnabled();
await submitButton.click();

// Handle auth state
test.beforeEach(async ({ page }) => {
  // Log in once before each test
  await page.goto("/login");
  await page.getByLabel("Email").fill("test@example.com");
  await page.getByLabel("Password").fill("password");
  await page.getByRole("button", { name: "Log In" }).click();
  await expect(page).toHaveURL("/dashboard");
});

Test Anti-Patterns

❌ Don't Do These

Testing Implementation Details:

// ❌ Bad: Testing internal state
expect(component.state.count).toBe(5);

// ✅ Good: Testing behavior
expect(screen.getByText("Count: 5")).toBeInTheDocument();

Arbitrary Waits:

// ❌ Bad: Arbitrary timeout
await page.waitForTimeout(5000);

// ✅ Good: Wait for real UI state
await expect(page.getByText("Data loaded")).toBeVisible();

Over-Mocking:

// ❌ Bad: Mocking everything (for DB logic)
vi.mock("~/server/db");
vi.mock("drizzle-orm");

// ✅ Good: Use PGlite integration test instead
// Integration tests with PGlite test real DB logic

Testing Server Components Directly:

// ❌ Bad: Unit testing async Server Component
import { render } from "@testing-library/react";
const result = await render(<ServerComponent />); // Doesn't work well

// ✅ Good: E2E test for Server Component behavior
test("page displays issues", async ({ page }) => {
  await page.goto("/issues");
  await expect(page.getByText("Issue #1")).toBeVisible();
});

Testing Checklist

Before committing tests:

• Test files in correct location (unit vs integration vs E2E)
• Integration tests use worker-scoped PGlite (getPGlite())
• No per-test PGlite instances
• E2E tests use roles/labels for selectors
• No arbitrary waitForTimeout() in E2E tests
• Tests are independent (no shared state)
• Testing behavior, not implementation
• pnpm run preflight passes (includes all test suites)

Additional Resources

• Full testing strategy: docs/TESTING_PLAN.md
• E2E best practices: docs/E2E_BEST_PRACTICES.md
• Non-negotiables: docs/NON_NEGOTIABLES.md (CORE-TEST-* rules)
• Playwright docs: Use Context7 MCP for latest patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.