Testing

Overview of the ignitionstack.pro quality gates. Tests are divided into unit, integration, and end-to-end layers so we can validate UI, business rules, and real browser flows without duplicating effort.

Test Stack

The Vitest config (vitest.config.ts) wires absolute imports (@/), loads .env.test, and points to src/app/test/setup.tsx. Playwright uses playwright.config.ts with base URL http://127.0.0.1:3100, per-project auth setup, HTML reports, and the shared output folder playwright-report/.

Test Layers

Unit Tests

• Live under src/app/test/unit/{actions,ai,components,hooks,lib,server,validations}.
• Depend on happy-dom and @testing-library/react through src/app/test/setup.tsx, which mocks next-intl, next/navigation, next/image, and next/link while loading .env.test.
• Use factories from src/app/test/utils/test-factories.ts to avoid hand-written fixtures.
• Prefer render(<Component />) from Testing Library and assert using accessible queries (getByRole, findByText).
• Run specific units with vitest run src/app/test/unit/hooks/use-contact-form.test.ts.

Example snippet

import { render, screen } from '@testing-library/react';
import { PricingCard } from '@/app/components/pricing-card';
 
test('renders CTA label', () => {
  render(<PricingCard plan="pro" />);
  expect(screen.getByRole('button', { name: /buy now/i })).toBeVisible();
});

Integration Tests

• Located in src/app/test/integration/{actions,api,repositories,server,webhooks}.
• Exercise repositories (ProjectRepository, ProductRepository, etc.), server actions, and API routes end-to-end within the app boundary.
• Use Supabase mocks (src/app/test/utils/supabase-mock.ts) plus cache helpers to simulate success/error branches without touching a real DB.
• Factories from test-factories.ts provide rich sample payloads.
• Run targeted suites with vitest run src/app/test/integration/repositories/project-repository.test.ts.
• Keep Arrange/Act/Assert comments when meaningful and cover both success + failure codes (e.g., ActionResult codes like DUPLICATE_SLUG).

End-to-End Tests

• Stored in src/app/test/e2e/tests with Playwright fixtures under src/app/test/e2e/fixtures and page objects inside src/app/test/e2e/pages.
• auth.setup.ts seeds a storage state (e2e/.auth/user.json) when TEST_USER_EMAIL and TEST_USER_PASSWORD are available so authenticated flows can re-use the same session.
• Tests import from ../fixtures/test-fixtures to obtain strongly typed helpers (homePage, blogPage, etc.) and follow a BDD-style test.describe('Feature…') structure.
• Key scripts:
  • npx playwright install --with-deps – install browsers/system deps (run once per machine)
  • npm run dev:e2e – start Next.js locally on 127.0.0.1:3100 (optional when debugging)
  • npm run e2e – headless suite (spawns dev:e2e automatically)
  • npm run e2e:headed – headed mode for debugging
  • npm run e2e:ui – Playwright UI explorer
  • npm run e2e:debug – debug with inspector
  • npm run e2e:report – open the HTML report (playwright-report/)
• The config automatically starts npm run dev:e2e unless PLAYWRIGHT_BASE_URL points to an existing server.
• For authenticated specs, call test.use({ storageState: 'e2e/.auth/user.json' }); once the auth setup has created the file.

E2E Setup Checklist

1. npx playwright install --with-deps (once per machine/CI agent).
2. Ensure .env.local (or the CI env) contains the same keys the app needs in dev.
3. Run npm run e2e to execute the suite. Use npm run dev:e2e separately when you want to keep the dev server alive while iterating with npx playwright test --ui.

Utilities & Helpers

Available Scripts

# Vitest layers
npm test                 # unit + integration
npm run test:watch       # watch mode
npm run test:ui          # Vitest UI
npm run test:coverage    # coverage via v8
 
# Playwright
npm run dev:e2e            # Start the dedicated Next.js server locally
npm run e2e              # headless
npm run e2e:headed       # headed
npm run e2e:ui           # GUI to pick tests
npm run e2e:debug        # debugger
npm run e2e:report       # show last report

Best Practices

• Arrange / Act / Assert – keep sections obvious in longer specs.
• mocks – scope vi.mock to the file or block that really needs it.
• Testing Library – use accessible queries; avoid brittle selectors.
• Snapshots – only for stable markup; otherwise assert explicit output.
• Coverage – maintain >80% on auth, billing, AI chatbot modules.
• Playwright – prefer page objects + fixtures instead of copy/pasting locators.

Pre-PR Checklist

• npm test passes locally (unit + integration)
• No unexpected console.error during runs
• npm run test:coverage updated if relevant
• E2E specs (npm run e2e) pass or are skipped intentionally
• Tests describe behavior, not implementation details

Useful Resources

• Vitest Docs 
• Testing Library 
• Playwright Docs 
• happy-dom 

Keep this page updated whenever you add utilities, commands, or best practices so the team always has a single source of truth.