docs: add comprehensive test behavior documentation for all pages
Add behavior documentation covering all SSR and legacy SPA pages: - Testing strategy and type definitions (unit/integration/UI) - Dashboard, Invoice, Payment, Transaction, Ledger pages - Company/Settings, POS, Admin, Search, Auth pages - Legacy SPA behavior docs (no UI tests until migrated) - Edge cases, test data requirements, and dependencies per subsystem Total: 3,600+ lines of behavior documentation to guide test authorship.
This commit is contained in:
185
docs/testing/README.md
Normal file
185
docs/testing/README.md
Normal file
@@ -0,0 +1,185 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user