Testing Strategy

Relevant source files

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

• tests/test_pipeline.py
• tests/test_full_pipeline.py
• tests/test_backend.py
• tests/test_exact_field_mapping.py
• tests/test_taxcalc.py
• tests/test_security.py
• tests/test_frontend_integration.py
• README.md

The testing strategy for the Tax-Processor project is designed to ensure the reliability of a multi-stage AI-powered pipeline that handles sensitive financial data. The suite covers individual component logic, security protocols, end-to-end orchestration, and API integration.

The project utilizes pytest as its primary testing framework, currently maintaining 14 passing tests that validate document classification, field extraction, tax calculation, and PDF generation.

Sources: README.md:23-28, README.md:92-105

Core Testing Categories

The test suite is partitioned into specialized categories to validate specific layers of the application architecture.

Category	Target Component	Description
Unit Testing	taxcalc.py, parsing/	Validates math logic, regex extraction, and validation rules.
Integration Testing	pipeline.py	Ensures data flows correctly from ingestion to PDF generation.
Security Testing	security.py	Validates file type restrictions and PII masking.
API/Frontend Testing	backend.py	Tests Flask endpoints and multipart/form-data uploads.

Sources: README.md:100-108, tests/test_taxcalc.py, tests/test_security.py

Unit Testing: Tax Calculation and Parsing

Unit tests verify the accuracy of the tax engine and the robustness of document parsing. The tax calculation tests verify progressive bracket application and standard deductions for different filing statuses.

The diagram above represents the logic flow validated by unit tests in test_taxcalc.py.
Sources: tests/test_taxcalc.py:4-22, taxcalc.py:73-102

Integration Testing: Processing Pipeline

Integration tests focus on the run_pipeline_on_paths function, which orchestrates the entire lifecycle of a tax document. These tests ensure that a raw file (e.g., sample_w2.txt) can be successfully processed into a structured JSON result and a physical PDF draft.

This sequence demonstrates the orchestration validated by test_full_pipeline.py.
Sources: tests/test_full_pipeline.py:8-18, pipeline.py:42-83

Security and PII Validation

Security tests are critical due to the handling of Social Security Numbers (SSN) and Employer Identification Numbers (EIN). The strategy includes:

1. File Sanitization: Testing the rejection of disallowed extensions (e.g., .exe) via the /upload endpoint.
2. PII Masking: Verifying that sensitive fields like employee_ssn are masked (e.g., XXX-XX-1234) before being returned in API responses.

Sources: tests/test_security.py:7-27, backend.py:92-100

PDF Generation and Field Mapping

Specific tests validate the forms.py module and the auto_mapper.py utility. These tests ensure that extracted values are correctly mapped to PDF AcroForm field names and that currency is formatted according to financial standards.

• Currency Formatting: Validates that numeric inputs are converted to strings like "75,000.00".
• AcroForm Filling: Uses tempfile to generate a PDF and then attempts to extract text back from it to verify content persistence.

Sources: tests/test_exact_field_mapping.py:10-44, tests/test_exact_field_mapping.py:47-55

Backend and Frontend Integration

API testing uses the Flask test_client to simulate real-world usage.

def test_upload_via_frontend_client(tmp_path):
    client = app.test_client()
    sample = os.path.join(os.path.dirname(__file__), '..', 'samples', 'sample_w2.txt')
    with open(sample, 'rb') as f:
        data = {
            'files': (io.BytesIO(f.read()), 'sample_w2.txt'),
            'filing_status': 'single',
            'withholding': '5000'
        }
        resp = client.post('/upload', data=data, content_type='multipart/form-data')
    assert resp.status_code == 200

Sources: tests/test_frontend_integration.py:13-26, tests/test_backend.py:8-18

Summary

The Testing Strategy employs a tiered approach, starting from basic regex and math validation up to complex multi-file orchestration and security masking. By integrating pytest with the Flask test_client and tempfile utilities, the suite provides coverage for the entire data transformation process from raw document upload to final PDF generation.