Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for the Syllogic personal finance application encompasses a multi-layered approach covering both the frontend Next.js environment and the backend FastAPI service. It includes unit tests for complex logic, integration tests for API endpoints, and validation procedures for deployment and infrastructure. The strategy ensures that core financial functionalities, such as transaction categorization, CSV mapping, and analytical visualizations, maintain high accuracy and reliability.
Sources: backend/tests/README.md:1-25, CLAUDE.md:1-20, frontend/lib/dashboard/sankey.test.ts:1-75
Backend Testing
The backend testing suite focuses on validating the FastAPI API endpoints and the underlying data pipeline logic. These tests are primarily integration-oriented and require a running environment with PostgreSQL and Redis.
Integration Test Categories
The backend employs specific test scripts to validate critical modules:
- Transaction Import: Validates the
/api/transactions/importendpoint and CSV processing. - Categorizer: Tests the AI and deterministic categorization logic for both single and batch transactions.
- Subscription Identifier: Verifies the detection of recurring payments and subscription patterns.
Sources: backend/tests/README.md:19-25
Test Environment Requirements
To execute backend tests locally, the following environment must be configured:
- Services: Active instances of PostgreSQL and Redis.
- Authentication: The
INTERNAL_AUTH_SECRETmust be set to allow tests to generate signed internal auth headers for protected endpoints. - Server: The backend server must be running on
http://localhost:8000.
Sources: backend/tests/README.md:5-17
The diagram shows the interaction between test scripts, internal authentication header generation, and the backend infrastructure.
Sources: backend/tests/README.md:5-17
Frontend Testing
Frontend testing utilizes Vitest for unit testing utility functions and logic-heavy components, such as financial visualization builders.
Unit Testing Logic
Complex data transformations, such as the buildConservativeSankey function used for dashboard visualizations, are protected by unit tests to ensure mathematical accuracy. These tests verify:
- Balance Preservation: Ensuring total income matches total expenses across nodes.
- Synthetic Node Creation: Validating that "Savings" nodes are created when income exceeds expenses and "Funding Gap" nodes appear when expenses exceed income.
- Numeric Integrity: Using finite value checks and
toBeCloseTofor floating-point precision.
Sources: frontend/lib/dashboard/sankey.test.ts:24-73
UI and Action Validation
The frontend relies on manual and automated validation of Server Actions and UI flows. Key areas of focus include:
- CSV Mapping: Validating AI-suggested mappings and manual column matching in
MappingPageContent. - Onboarding Flows: Ensuring progress tracking across steps (e.g., Step 4 Mapping).
Sources: frontend/app/step-4/mapping/page.tsx:35-130
Validation Procedures
Beyond standard code tests, the project defines "Validation Procedures" to ensure infrastructure and deployment stability, particularly for self-hosted and cloud environments.
Deployment & Runtime Validation
The project defines a checklist for validating the application state after deployment:
| Category | Validation Task |
|---|---|
| Volumes | Verify Postgres, Redis, and App uploads are mounted at correct paths. |
| Networking | Confirm internal calls use private domains and public networking is restricted to the App service. |
| Healthchecks | Hardened checks verify DB readiness and write access to /app/public/uploads. |
| Assets | Validate persistence of profile photos and logos across redeploys. |
Sources: deploy/railway/README.md:173-210
CI/CD Integration
Integration tests for the backend are automatically executed within GitHub Actions on every push and pull request to maintain codebase integrity.
Sources: backend/tests/README.md:27-29
This sequence illustrates the automated testing flow within the CI/CD pipeline.
Sources: backend/tests/README.md:5-29
Conclusion
The Syllogic testing strategy combines traditional unit and integration testing with robust infrastructure validation. By focusing on critical financial data paths—categorization, balance verification, and persistence—the strategy ensures the application remains accurate while supporting complex features like AI-powered transaction enrichment.