Development & Testing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• TESTING_GUIDE.md
• TEST_FILES_INDEX.md
• SUMMARY.md
• AUDIT_REPORT.md
• COMPREHENSIVE_TEST_SUMMARY.md
• TEST_VALIDATION_COMPREHENSIVE_SUMMARY.md

This guide describes the engineering standards, development workflows, and testing infrastructure for the Financial Asset Relationship Database. The project uses a Python-based backend and a TypeScript/React frontend, supported by an automated CI/CD pipeline and comprehensive validation suites.

Sources: CONTRIBUTING.md:1-10, TESTING_GUIDE.md:1-10, SUMMARY.md:1-10

Development Workflow

The development process follows a branch-based workflow with mandatory local checks and standardized commit practices. Contributors use a Makefile to manage dependencies, formatting, and linting consistently across environments.

Local Environment Setup

To set up the development environment, follow these steps:

1. Create a virtual environment using python -m venv .venv.
2. Activate the environment based on your operating system.
3. Install development dependencies using pip install -r requirements.txt -r requirements-dev.txt or pip install -e ".[dev]".
4. Install pre-commit hooks using make pre-commit.

Sources: CONTRIBUTING.md:30-70, SUMMARY.md:40-60

Feature Branch Lifecycle

Contributors create separate branches for features, bug fixes, or documentation. The project enforces specific branch naming conventions:

• feature/description for new functionality.
• bugfix/description for resolving issues.
• docs/description for documentation updates.

Sources: CONTRIBUTING.md:75-90

The diagram above illustrates the path from task inception to code merge.
Sources: CONTRIBUTING.md:75-150

Coding and Quality Standards

The project implements strict linting and formatting rules to ensure code maintainability. Python code follows PEP 8 standards, while the frontend utilizes TypeScript and ESLint.

Python Standards

• Line Length: 120 characters.
• Formatting: Managed by black.
• Import Sorting: Managed by isort.
• Type Hints: Required for new or modified functions.
• Docstrings: Follow Google or NumPy style.

Sources: CONTRIBUTING.md:160-185, SUMMARY.md:120-135

Automation and Linting Tools

The project uses several tools to enforce quality, configured within pyproject.toml and .flake8.

Tool	Purpose	Configuration Detail
flake8	Linting	Max complexity: 15; Line length: 120
pylint	Static Analysis	Fail threshold: 8.0
mypy	Type Checking	Strict untyped definition checks
black	Formatting	Deterministic code layout
isort	Import Sorting	Black-compatible profile

Sources: SUMMARY.md:120-140, AUDIT_REPORT.md:180-210

Testing Infrastructure

The testing architecture is divided into backend (Python/pytest) and frontend (TypeScript/Jest) suites, achieving over 85% coverage across the codebase.

Backend Testing (Python)

Backend tests reside in tests/unit/ and tests/integration/. They utilize pytest fixtures for asset and graph initialization.

Category	File Example	Focus
Unit	test_financial_models.py	Model validation, decimal precision
Unit	test_asset_graph.py	Relationship logic, graph metrics
Integration	test_api_main.py	FastAPI endpoints, CORS, Concurrency
Integration	test_github_workflows.py	CI/CD YAML and action validation

Sources: TESTING_GUIDE.md:15-60, TEST_FILES_INDEX.md:30-60

Frontend Testing (TypeScript)

Frontend tests use Jest and React Testing Library to validate components and API client interactions.

The diagram shows how various frontend test components contribute to the final coverage report.
Sources: TESTING_GUIDE.md:80-140, COMPREHENSIVE_TEST_SUMMARY.md:40-80

Documentation and Configuration Validation

Specialized test suites validate non-code assets to prevent broken links and malformed configurations.

• test_documentation_files_validation.py: Validates 32 markdown files for heading hierarchy, internal link integrity, and formatting.
• test_modified_config_files_validation.py: Verifies pr-agent-config.yml, GitHub workflows, and requirements-dev.txt structure.

Sources: TEST_FILES_INDEX.md:15-30, TEST_VALIDATION_COMPREHENSIVE_SUMMARY.md:20-60

Continuous Integration (CI/CD)

The CI/CD pipeline, defined in .github/workflows/ci.yml, automatically executes the full test suite and security scans on every push and pull request.

This sequence illustrates the automated checks performed by the CI pipeline before code is eligible for merging.
Sources: SUMMARY.md:145-160, AUDIT_REPORT.md:215-230

Conclusion

The project maintains a high health score by integrating modern linting, strict coding standards, and a multi-layered testing strategy. Developers are empowered by a standardized Makefile interface and automated validation of both source code and documentation.

Sources: SUMMARY.md:250-270, AUDIT_REPORT.md:350-370