Testing Guide

This guide covers the testing infrastructure, commands, and best practices for the Heimdall project.

Philosophy

• Test-driven mindset: Consider tests as part of the feature, not an afterthought
• Coverage over quantity: Focus on meaningful tests that catch real bugs
• Fast feedback: Unit tests should run in seconds, E2E tests in minutes
• Security first: All user inputs and auth flows must have security tests

Test Types

Type	Purpose	Tools	When Required
Unit	Test individual functions/modules in isolation	Cargo test, Vitest	All new functions, services, utilities
Integration	Test component interactions	Cargo test, Vitest	API endpoints, database operations
E2E	Test complete user flows	Playwright	All user-facing features
Security	Test auth, authorization, input validation	All	All auth flows, API endpoints, user inputs

Quick Reference Commands

# Most commonly used
just test           # All unit tests
just test-all       # ALL tests (unit + E2E)
just test-quick     # Fast tests only (Rust + shared libs)
just test-e2e       # All E2E tests
just test-ci        # CI test suite
just test-help      # Show all test commands

Test Structure

Note: platform/api is a thin glue binary with no tests/ dir — Rust test coverage lives in the individual crates/heimdall-* (see below).

platform/
├── discord_bot/tests/          # Discord bot tests
├── youtube_bot/                # YouTube bot
├── backend/
│   ├── tests/                  # Unit tests
│   └── e2e/                    # E2E tests
├── id/
│   ├── tests/                  # Unit tests
│   └── e2e/                    # E2E tests
└── policies/
    ├── tests/                  # Unit tests
    └── e2e/                    # E2E tests

shared/
├── api/tests/                  # API library tests
├── ui/tests/                   # UI component tests
├── cookies-consent/tests/      # Cookie consent library tests
├── player/tests/               # Video player library tests
└── test-utils/                 # Shared test mocks, fixtures, helpers

crates/                         # 13 of the heimdall-* crates ship tests/
├── heimdall-audit/tests/       # Audit crate tests
├── heimdall-auth/tests/        # Auth crate tests (incl. security_test.rs)
├── heimdall-cache/tests/       # Cache crate tests
├── heimdall-common/tests/      # Common utilities tests
├── heimdall-config/tests/      # Config crate tests
├── heimdall-email/tests/       # Email crate tests
├── heimdall-graphql/tests/     # GraphQL crate tests
├── heimdall-integrations/tests/# Integrations crate tests
├── heimdall-proto/tests/       # Proto crate tests
├── heimdall-rest/tests/        # REST handler tests
├── heimdall-scheduler/tests/   # Scheduler crate tests
├── heimdall-storage/tests/     # Storage crate tests
└── heimdall-websocket/tests/   # WebSocket crate tests

New Crate/Library Checklist

When creating a new Rust crate or TypeScript library:

1. Add test infrastructure:

   • Rust: tests/ directory with *_test.rs files
   • TypeScript: tests/ directory with *.test.ts files, vitest config

2. Add test script:

   • Rust: Ensure cargo test works
   • TypeScript: Add "test": "vitest run" to package.json

3. Include security tests: XSS, SQL injection, path traversal (where applicable)

4. Add to justfile: Create just test-<name> command

New App/Bot Checklist

When creating a new webapp or bot:

1. Add test infrastructure:

   • Webapps: tests/ for unit tests (vitest), e2e/ for Playwright tests
   • Bots: tests/ directory with *_test.rs files

2. Add test scripts:

   • Webapps: "test": "vitest run", "test:e2e": "playwright test"
   • Bots: Ensure cargo test works

3. Required tests:

   • Auth/permission checks
   • Input validation & security (XSS, injection)
   • Critical user flows (E2E for webapps)

4. Add to justfile:

   • just test-<name> for unit tests
   • just test-<name>-e2e for E2E tests (webapps)
   • just verify-<name> for full verification

Coverage Requirements

Component	Minimum
Rust services	80%
Rust handlers	70%
TypeScript utilities	90%
React hooks	80%
E2E critical paths	100%
Security tests	All endpoints