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:

```markdown
# <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

```bash
# All tests
lein test

# Integration tests only
lein test :integration

# Functional tests only
lein test :functional
```

## Files

- [Dashboard Behaviors](behaviors/dashboard.md)
- [Invoice Behaviors](behaviors/invoice.md)
- [Payment Behaviors](behaviors/payment.md)
- [Transaction Behaviors](behaviors/transaction.md)
- [Ledger Behaviors](behaviors/ledger.md)
- [Company Behaviors](behaviors/company.md)
- [POS Behaviors](behaviors/pos.md)
- [Outgoing Invoice Behaviors](behaviors/outgoing-invoice.md)
- [Admin Behaviors](behaviors/admin.md)
- [Search & Indicators Behaviors](behaviors/search-indicators.md)
- [Auth Behaviors](behaviors/auth.md)
- [Legacy SPA Behaviors](behaviors/legacy-spa.md)