Testing Reference Documentation

Single Source of Truth: Comprehensive testing guides for Savvi Studio

Quick Start

New to testing? → Getting Started Guide
Writing tests? → Writing Tests Guide
Need Vitest patterns? → Vitest Patterns
Which context? → Test Contexts Guide
Need help? → Troubleshooting Guide

🎯 Core Guides (START HERE)

Essential Reading

Guide	Purpose	When to Read
Writing Tests	Complete test writing guide	First time writing tests
Vitest Patterns	Vitest-specific best practices	Learn test.extend() & fixtures
Test Contexts	Available contexts & when to use	Choosing right context
Getting Started	Quick start guide	Initial setup

Key Concepts

• Vitest test.extend() - Create custom test contexts with shared setup (Guide)
• Parameterized tests - Test multiple scenarios efficiently with test.each() (Guide)
• Test contexts - Hierarchical fixture system (Base → Auth → Custom) (Guide)
• Real database testing - Integration tests use actual PostgreSQL
• Automatic cleanup - Fixtures handle setup/teardown automatically

Overview

This is the single source of truth for testing documentation in Savvi Studio. Our testing approach emphasizes:

• Vitest Patterns - Leverage test.extend() to avoid duplication
• Test Contexts - Hierarchical fixture system for different scenarios
• Real Database Testing - Integration tests use actual PostgreSQL
• Automatic Cleanup - Fixtures handle setup and teardown
• Parameterized Tests - Test multiple scenarios efficiently
• Factory Functions - Reusable test data creation

📚 Guides

Testing Guides

Guide	Description	When to Use
Integration Testing	Complete integration testing guide	Writing integration tests
Unit Testing	Unit test patterns and mocks	Writing unit tests
Database Testing	Database patterns and best practices	Testing database operations
External Services	Mocking WorkOS, AWS, etc.	Testing external integrations
Parameterized Tests	test.each() patterns and examples	Testing multiple scenarios

Support Guides

Document	Description	When to Use
Getting Started	Quick start guide	First time setup
Common Scenarios	23+ practical examples	Finding pattern examples
Troubleshooting	Common issues and solutions	Debugging test failures

📖 API Reference

Test Infrastructure API

Reference	Description	When to Use
Test Contexts API	Complete fixture API signatures	Looking up fixture methods
Fixtures API	Additional fixture APIs	Understanding fixture behavior
Factories API	Factory function signatures	Creating test data
Utilities API	Utility function signatures	Querying and cleanup
Mocks API	Mock factory signatures	Creating mocks

Architecture & Strategy

Document	Description	When to Use
Factories & Utilities	Complete guide with workflows	Understanding patterns
Mock Architecture	Centralized mock system design	Understanding mock organization
Testing Strategy	When to use different approaches	Choosing test strategies

Test Infrastructure

Current Implementation

The test infrastructure is fully implemented and includes:

tests/
├── integration/
│   ├── test.ts                       # 9 base fixtures
│   ├── setup/
│   │   ├── factories/                # 14 factory functions
│   │   └── utilities/                # 15+ query utilities
│   ├── auth/                         # Auth tests (18 files)
│   ├── graph/                        # Graph tests (18 files)
│   └── ...                           # Other domain tests
├── mocks/
│   ├── auth/                         # Auth mocks
│   ├── db/                           # Database mocks
│   └── workos/                       # WorkOS mocks
└── unit/                             # Unit tests

Key Features

1. ✅ Fixture-Based Testing - 9 core fixtures in test.ts
2. ✅ Factory Functions - 14 functions for creating test data
3. ✅ Query Utilities - 15+ functions for database operations
4. ✅ Centralized Mocks - Organized mock library
5. ✅ Domain Organization - Tests grouped by domain
6. ✅ Database Lifecycle - Worker-scoped database management
7. ✅ WorkOS Integration - Event factories and handlers

Common Tasks

Writing Your First Test

→ Getting Started Guide

Using Factories

→ Factories & Utilities Reference

Testing Permissions

→ Common Scenarios

Mocking External Services

→ External Services Guide

Testing Database Operations

→ Database Testing Guide

Debugging Test Failures

→ Troubleshooting Guide

Implementation Tasks

For step-by-step implementation guides and tasks, see:

→ Testing Infrastructure Tasks

Tasks include:

• Setting up testing environment
• Completing mock library
• Migrating remaining tests
• Standardizing organization
• Enhancing reliability
• Expanding coverage
• Documenting patterns

Examples

Working code examples are available in the examples/ directory:

• 01-basic-integration.ts - Simplest possible test
• 02-database-codegen.ts - Database + codegen
• 03-full-stack.ts - Full stack integration
• 04-external-service-mock.ts - Service mocking
• 05-custom-fixtures.ts - Custom fixtures

Testing Philosophy

Our testing philosophy emphasizes:

1. Real Database, Real Tests - Test against actual PostgreSQL
2. Isolation First - Each test gets clean environment
3. Fast Feedback - Tests complete in seconds
4. Self-Documenting - Tests serve as executable documentation
5. Maintainable - Reusable fixtures and clear patterns

Quick Reference

Common Commands

# Run all tests
pnpm test

# Run integration tests
pnpm test tests/integration

# Run specific domain
pnpm test tests/integration/auth

# Watch mode
pnpm test -- --watch

# Coverage
pnpm test -- --coverage

Essential Imports

import test from '../test';
import { generateTestId } from '@/test-utils-integration/utils/graph-fixtures';
import {
  createUserWithOrgSetup,
  createResourceWithPermission
} from '../setup/factories/database-fixtures';
import {
  queryUserAccessCache,
  refreshUserAccessCache
} from '../setup/utilities';

Common Patterns

// Create user with org
const { user, org } = await createUserWithOrgSetup(client);

// Grant permission
const { resourceNodeId } = await createResourceWithPermission(client, {
  userNodeId: user.nodeId,
  permissionLevel: 'write'
});

// Query access
await refreshUserAccessCache(client, user.id);
const access = await queryUserAccessCache(client, user.id);

Contributing

When updating test documentation:

1. Keep reference docs comprehensive
2. Update code examples to match current codebase
3. Cross-reference related documentation
4. Test all code examples
5. Update task documentation if implementation changes

Getting Help

• Documentation issues? → Check Troubleshooting Guide
• Need examples? → See Common Scenarios
• Bug reports? → Use /reportbug command

Related Documentation

• Database Documentation - Database connection and queries
• Auth Documentation - Authentication and authorization
• Graph Documentation - Graph operations and traversal

---

Ready to get started? → Getting Started Guide