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

platform/
├── api/tests/                  # Rust API tests
├── discord_bot/tests/          # Discord bot tests
├── twitch_bot/tests/           # Twitch bot tests
├── backend/
│   ├── tests/                  # Unit tests
│   └── e2e/                    # E2E tests
├── id/
│   ├── tests/                  # Unit tests
│   └── e2e/                    # E2E tests
└── policies/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

crates/
├── audit/tests/                # Audit crate tests
├── storage/tests/              # Storage crate tests
└── proto/tests/                # Proto 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