Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The SoulSeer testing strategy employs a multi-layered approach to ensure the reliability of its mystical guidance platform. This strategy encompasses automated unit and smoke tests for both the frontend and backend, comprehensive schema validation, and specialized scripts for QA environment provisioning. The project utilizes Vitest as its primary test runner across the monorepo, integrated with Testing Library for React components.
Sources: client/package.json:11, server/package.json:12, client/src/test/app.test.tsx:5
Core Test Infrastructure
The infrastructure is built around a monorepo structure where both the client and server directories maintain their own testing configurations and dependencies.
Framework and Configuration
The project uses Vitest for execution and coverage reporting. The server-side testing environment is initialized via a dedicated setup script that configures essential environment variables, ensuring tests do not interfere with production or development databases.
The diagram shows the distribution of testing responsibilities across the client and server modules.
Sources: server/src/test/setup.ts:1-14, server/package.json:12-13, client/package.json:11-12
Environment Variables for Testing
The server test suite requires a specific set of mocked environment variables to prevent accidental side effects on external services like Stripe or Auth0.
| Variable | Test Value |
|---|---|
NODE_ENV | test |
DATABASE_URL | postgresql://test:test@localhost:5432/soulseer_test |
PORT | 5001 |
AGORA_APP_ID | test-agora-app-id |
STRIPE_SECRET_KEY | STRIPE_SECRET_KEY_TEST_PLACEHOLDER |
Sources: server/src/test/setup.ts:7-17, server/src/test/config.test.ts:11-14
Backend Testing
1. Smoke and Configuration Tests
Smoke tests verify that the application's core infrastructure—configuration loading, database schemas, and enum definitions—is correctly initialized. These tests ensure that the config object correctly pulls from environment variables and that the Drizzle ORM schema matches the expected database structure.
- Schema Validation: Verifies existence of columns in tables such as
users,readings, andtransactions. - Enum Verification: Ensures that critical business logic enums (e.g.,
userRoleEnum,readingStatusEnum) contain the correct values.
Sources: server/src/test/config.test.ts:9-35, server/src/test/schema.test.ts:24-95
2. Middleware and Validation Testing
Validation logic is tested extensively to ensure that incoming requests adhere to defined Zod schemas. The validate.test.ts suite covers:
- Standard body validation and field stripping (removing unknown fields).
- Query parameter validation.
- Error response structure (Status 400 with
VALIDATION_ERRORcode).
Sources: server/src/middleware/tests/validate.test.ts:40-100
3. Service Mocking (e.g., Stripe)
Complex external integrations are tested using intensive mocking strategies. For instance, the Stripe service tests use vi.mock to intercept calls to the Stripe SDK and vi.hoisted to create spies before the modules are initialized.
The sequence shows how the system verifies the coordination between external API calls and internal database updates.
Sources: server/src/test/stripe-service.test.ts:48-95
Frontend Testing
The frontend testing strategy focuses on "smoke tests" for React components and structural verification of the API service client.
Component Smoke Tests
Using @testing-library/react, the suite verifies that core layouts and components render without crashing. These tests check for the presence of specific HTML elements (e.g., main with page-wrapper class) and correct text content.
Sources: client/src/test/app.test.tsx:10-25
API Client Validation
The api-service.test.ts ensures that the apiService object exposes the required RESTful methods (get, post, put, patch, delete) and correctly handles access token management.
Sources: client/src/test/api-service.test.ts:16-27
QA Account Provisioning
A specialized script, provision-test-accounts.ts, is used to create a reproducible testing environment. This script is idempotent, allowing developers to reset or update test accounts without duplicates.
| Account Label | Purpose | |
|---|---|---|
admin | emilynnj14@gmail.com | Full platform control testing |
reader | emilynn992@gmail.com | Service provider flow testing |
client | emily81292@gmail.com | Consumer flow / $50 starter balance |
Sources: server/scripts/provision-test-accounts.ts:40-66
Provisioning Flow
The script coordinates between the Auth0 Management API and the internal database:
- Auth0: Creates the user or updates the password if they already exist (Status 409 handling).
- Database: Upserts the user row with metadata, pricing, and initial balances.
Sources: server/scripts/provision-test-accounts.ts:88-154
Conclusion
SoulSeer's testing strategy emphasizes early detection of configuration and schema errors while providing a robust framework for mocking external dependencies. By combining Vitest with specialized provisioning scripts, the project ensures a consistent environment for both automated CI/CD pipelines and manual QA efforts.