Testing Strategy

Relevant source files

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

• lexwebapp/TEST_INSTRUCTIONS.md
• lexwebapp/TESTING_READY.md
• deployment/TESTING.md
• PHASE1_TESTING.md
• mcp_backend/src/api/tests/document-analysis-e2e.test.ts
• lexwebapp/src/tests/README.md
• lexwebapp/verify-setup.sh

The SecondLayer project employs a multi-layered testing strategy designed to ensure the reliability of its legal tech infrastructure, ranging from frontend component validation to complex backend Model Context Protocol (MCP) tool orchestration. The strategy encompasses unit testing, integration testing, end-to-end (E2E) workflows, and specialized legal data validation.

Sources: lexwebapp/TEST_INSTRUCTIONS.md, deployment/TESTING.md, lexwebapp/src/tests/README.md

1. Frontend Testing Architecture

The frontend testing environment is built on Vitest, utilizing React Testing Library for component interactions and jsdom for environment simulation. The focus is on verifying state management, asynchronous streaming through Server-Sent Events (SSE), and hook-based logic.

1.1 Core Frontend Testing Modules

The frontend testing suite is divided into three primary categories:

• Services: Validation of SSEClient (connection logic, retry mechanisms) and MCPService (tool execution, response transformation).
• Hooks: Verification of useMCPTool which handles tool execution states, message management, and streaming callbacks.
• Stores: Testing the chatStore (Zustand) for message CRUD operations, streaming state, and "thinking steps" persistence.

Sources: lexwebapp/TEST_INSTRUCTIONS.md:32-55, lexwebapp/src/tests/README.md:9-35

1.2 Frontend Test Workflow

The following diagram illustrates the execution flow for frontend unit and integration tests.

The automated test runner script ensures a consistent environment by performing dependency installation and type checking before executing the 55 core unit tests.
Sources: lexwebapp/TEST_INSTRUCTIONS.md:5-18, lexwebapp/TESTING_READY.md:100-140

2. Backend and Integration Testing

Backend testing focuses on the Unified Gateway, verifying 45+ MCP tools across different environments (local, staging, production). Testing is primarily conducted using Jest for integration and E2E suites.

2.1 Backend Test Categories

Suite Type	File Reference	Scope
Smoke Tests	smoke-test-all-tools.test.ts	Health checks, tool listing, and basic authentication.
Integration	all-tools-integration.test.ts	End-to-end tool calls with real API and database integration.
Document E2E	document-analysis-e2e.test.ts	OCR, PDF/DOCX parsing, and clause extraction.
Specialized	due-diligence-tools.test.ts	Risk scoring algorithms and findings table generation.

Sources: deployment/TESTING.md:46-85, mcp_backend/src/api/tests/document-analysis-e2e.test.ts:1-20

2.2 Document Analysis E2E Workflow

The document analysis testing validates the transformation of raw legal files into structured data.

This sequence ensures that document metadata, page counts, and MIME types are correctly handled across HTML, PDF, and DOCX formats.
Sources: mcp_backend/src/api/tests/document-analysis-e2e.test.ts:114-160, mcp_backend/src/api/tests/document-analysis-e2e.test.ts:250-285

3. Feature-Specific Testing (Phase 1: Billing & Time)

Specific feature modules, such as "Time Tracking & Billing," undergo isolated functional testing to verify database triggers, audit logs, and PDF generation.

3.1 Verification Checklist

• Timer Persistence: Verifying that active timers survive page refreshes and browser tab closures by checking the active_timers database table.
• Invoice Lifecycle: Testing the transition of time entries through states: Draft → Submitted → Approved → Invoiced.
• Integrity Checks: Running validate_audit_chain() and verifying that invoice subtotals match the sum of line items.

Sources: PHASE1_TESTING.md:40-100, PHASE1_TESTING.md:270-300

4. Test Configuration and Environment

4.1 Environment Variable Requirements

Testing requires specific keys to be configured in .env.local or .env.staging to prevent failure in external service dependencies.

Variable	Usage
TEST_API_KEY	Authenticates backend tool calls (default: test-key-123).
OPENAI_API_KEY	Required for semantic analysis and summarization tests.
VISION_CREDENTIALS_PATH	Path to Google Cloud Vision JSON for OCR testing.
DATABASE_URL	PostgreSQL connection string for direct integrity tests.

Sources: deployment/TESTING.md:133-145, mcp_backend/src/api/tests/document-analysis-e2e.test.ts:38-45

4.2 Automation Scripts

The project includes several shell scripts to standardize the testing process:

• ./run-tests.sh: Frontend Vitest execution.
• ./verify-setup.sh: Validates presence of core configuration files and directories.
• ./run-local-tests.sh: Backend integration runner with --quick and --verbose flags.

Sources: lexwebapp/verify-setup.sh:15-50, deployment/TESTING.md:12-30

Summary

The SecondLayer Testing Strategy integrates frontend state validation with backend data integrity checks. By utilizing automated verification scripts and specialized E2E suites for document analysis, the project ensures that legal data transformations remain accurate and that critical workflows, such as billing and court research, function correctly across different deployment environments.