integreat/docs/testing/README.md

Integreat Test Strategy & Behavior Documentation

Last Updated: 2026-05-04

Purpose

This document defines the comprehensive testing strategy for Integreat. The goal is to cover all user-visible behaviors with tests that provide confidence in the system's correctness. We are preserving valuable existing tests and filling gaps with new behavior documentation.

Test Types

1. Unit Tests

• Scope: Pure functions, transformations, validations, business logic
• Characteristics: No database, no external services, deterministic
• Location: test/clj/auto_ap/<namespace>_test.clj
• Examples: new_invoice_wizard_test.clj (location spreading logic)

2. Integration Tests

• Scope: Database interactions, GraphQL resolvers, route handlers, cross-system behavior
• Characteristics: Uses Datomic in-memory database (datomic:mem://test), schema created per test, data cleaned up after
• Location: test/clj/auto_ap/integration/
• Fixtures: wrap-setup creates schema + functions, runs test, deletes DB
• Helpers: test/clj/auto_ap/integration/util.clj provides entity creation helpers

3. UI / Functional Tests (Playwright)

• Scope: End-to-end user flows, page navigation, form interactions, HTMX behaviors
• Characteristics: Runs against running application, exercises real HTTP routes
• Location: TBD (likely test/functional/ or similar)
• Scope Limitation: Only SSR pages (HTMX-based) get UI tests. Legacy SPA pages get behavior docs only.

Existing Test Inventory

Unit Tests

File	Coverage	Status
auto_ap/ezcater_test.clj	EzCater integration logic	Keep
auto_ap/import/plaid_test.clj	Plaid import	Keep
auto_ap/import/transactions_test.clj	Transaction import	Keep
auto_ap/import/yodlee_test.clj	Yodlee import	Keep
auto_ap/import/manual_test.clj	Manual import	Keep
auto_ap/ledger_test.clj	Ledger calculations	Keep
auto_ap/parse/templates_test.clj	PDF template parsing	Keep
auto_ap/ssr/invoice/new_invoice_wizard_test.clj	Location spreading logic	Keep

Integration Tests

File	Coverage	Status
auto_ap/integration/graphql.clj	Transaction page, invoice page, ledger page, vendors, transaction rules	Keep
auto_ap/integration/graphql/accounts.clj	Account GraphQL	Keep
auto_ap/integration/graphql/checks.clj	Check GraphQL	Keep
auto_ap/integration/graphql/invoices.clj	Invoice GraphQL	Keep
auto_ap/integration/graphql/ledger/running_balance.clj	Ledger balance	Keep
auto_ap/integration/graphql/transaction_rules.clj	Transaction rules	Keep
auto_ap/integration/graphql/transactions.clj	Transaction GraphQL	Keep
auto_ap/integration/graphql/users.clj	User GraphQL	Keep
auto_ap/integration/graphql/vendors.clj	Vendor GraphQL	Keep
auto_ap/integration/routes/invoice_test.clj	Invoice import routes	Keep
auto_ap/integration/routes/ezcater_xls.clj	EzCater XLS routes	Keep
auto_ap/integration/rule_matching.clj	Rule matching logic	Keep
auto_ap/integration/jobs/ntg.clj	NTG background job	Keep

Page/Subsystem Coverage Map

SSR Pages (HTMX - Eligible for UI Tests)

1. Dashboard - Main dashboard with cards (expenses, tasks, bank accounts, sales, P&L)
2. Invoices - List, detail, new wizard, pay wizard, bulk edit, bulk delete, import, glimpse (OCR)
3. Payments - List, detail, bulk operations
4. Transactions - List, detail, new, external import, coding workflow
5. Ledger - Entries, P&L, Balance Sheet, Cash Flows, investigation
6. Company - Profile, signature, 1099s, reports, bank accounts, Plaid/Yodlee linking
7. POS - Sales, expected deposits, tenders, refunds, cash drawer shifts
8. Outgoing Invoices - Create outgoing invoices
9. Admin - Clients, accounts, vendors, transaction rules, background jobs, history, import batches, Excel invoices, sales summaries
10. Search - Global search dialog
11. Indicators - Business indicators

Legacy SPA Pages (Behavior Docs Only)

1. Home - Legacy dashboard
2. Login - Authentication
3. Transactions - Unapproved, approved, requires feedback, excluded
4. Ledger - P&L, Balance Sheet, Cash Flows, external, external import
5. Payments - Legacy payments list
6. Reports - Reports page
7. Admin Vendors - Vendor management (legacy)
8. New Vendor - Vendor creation

Behavior Documentation Structure

Each subsystem gets a markdown file in docs/testing/behaviors/ with the following structure:

# <Subsystem> Behaviors

## Overview
Brief description of what this subsystem does and its user-visible purpose.

## Pages / Routes
List of all routes and their purposes.

## Behaviors by Type

### Unit Test Behaviors
- Pure function behaviors, edge cases

### Integration Test Behaviors
- Database interactions, API behaviors, cross-system flows

### UI Test Behaviors (SSR only)
- End-to-end happy paths
- User interaction flows
- Navigation between pages

## Edge Cases
- Error states
- Empty states
- Permission boundaries
- Concurrent operations
- Large data volumes

## Test Data Requirements
What entities need to exist for meaningful tests.

## Dependencies
What other subsystems this depends on.

Test Data Patterns

The integration test utilities in test/clj/auto_ap/integration/util.clj provide:

• test-client - Creates a test client entity
• test-vendor - Creates a test vendor entity
• test-bank-account - Creates a test bank account
• test-transaction - Creates a test transaction
• test-payment - Creates a test payment
• test-invoice - Creates a test invoice
• test-account - Creates a test GL account
• test-transaction-rule - Creates a test transaction rule
• setup-test-data - Convenience function to create standard test data set
• admin-token / user-token - JWT identity helpers

Mocks & External Services

• Solr: Mocked for search functionality
• AWS Services: (Textract, S3, SES, SQS) - Should be mocked in tests
• Plaid/Yodlee/Intuit: External financial APIs - Mocked
• Square/EzCater: POS integrations - Mocked

Priorities

1. Critical: Invoice pages (core business function)
2. Critical: Payment pages (money movement)
3. High: Dashboard (first thing users see)
4. High: Transaction pages (data entry/coding)
5. High: Ledger reports (financial reporting)
6. Medium: Admin pages (operations)
7. Medium: Company settings (configuration)
8. Low: POS pages (ancillary)
9. Low: Legacy SPA pages (behavior docs only, no UI tests)

Running Tests

# All tests
lein test

# Integration tests only
lein test :integration

# Functional tests only
lein test :functional

Files

• Dashboard Behaviors
• Invoice Behaviors
• Payment Behaviors
• Transaction Behaviors
• Ledger Behaviors
• Company Behaviors
• POS Behaviors
• Outgoing Invoice Behaviors
• Admin Behaviors
• Search & Indicators Behaviors
• Auth Behaviors
• Legacy SPA Behaviors