integreat/docs/testing/behaviors/legacy-spa.md

Legacy SPA Behaviors

Overview

These pages are rendered client-side via Reagent/Re-frame and use GraphQL for data fetching. They are being migrated to HTMX SSR. No UI tests should be written for these pages until migrated.

Testing Philosophy

• Prefer unit tests for pure business logic (calculations, validations, transformations)
• Use integration tests for GraphQL queries, mutations, and data flows
• Use UI tests only after migration to SSR; until then, mark as "UI (when migrated)"
• Every behavior must be user-visible; no tests for implementation details

---

Testing Patterns

Pattern: GraphQL Data Fetching

All data fetching uses re-frame graphql effect with JWT token from :user in app-db:

1. Queries use owns-state to track loading status per page
2. Results flow through ::data-page/received event which stores data and syncs URL query params
3. Filter changes are debounced (800ms) via dispatch-debounce

Test implications: Integration test the GraphQL query resolution and response shape. Do not test the re-frame effect machinery.

Pattern: Re-frame State Management

• Data pages: data-page namespace provides reusable pagination/filtering state
  • ::data-page/params — merged filters + table params + query params
  • ::data-page/data — GraphQL response data
  • ::data-page/checked — selected rows for bulk operations
• Forms: forms namespace manages edit dialogs with start-form, change-handler, save-succeeded
• Status: status namespace tracks async operation states (:loading, :complete, :error)

Test implications: Test via integration tests that verify the correct data appears after state transitions. Do not test subscription internals.

Pattern: Client-Side Routing

• Navbar uses Bidi path-for with routes/routes for legacy SPA links
• Some navbar items (Payments, POS, Invoices) now link to ssr-routes/only-routes instead
• Page components dispatch ::mounted on mount and ::unmounted on unmount

Test implications: After migration, integration test route redirects from old SPA routes to new SSR routes.

---

Home

Dashboard Display

#	Behavior	Test Strategy	Status
1.1	It should display a dashboard with three chart sections: top expense categories, upcoming bills, and cash flow projection	UI (when migrated)	[ ]
1.2	It should load data for the currently selected client on page load	Integration	[ ]
1.3	It should display a note: "these reports are for [client]. Please choose a specific customer for their report." when the user has access to multiple clients and has not selected a specific one	UI (when migrated)	[ ]
1.4	It should display an interactive bar chart for cash flow projection	UI (when migrated)	[ ]
1.5	It should display a table below the cash flow chart showing invoices, upcoming debits, and upcoming credits with days-until due	UI (when migrated)	[ ]
1.6	It should allow switching the cash flow range between 7, 30, 60, 90, 120, 150, and 180 days	UI (when migrated)	[ ]
1.7	Given the user switches the cash flow range, then the chart and table should update to reflect the selected range	Integration	[ ]
1.8	Given the user clicks a cash flow bar, then it should redirect to the unpaid invoices page for that date	UI (when migrated)	[ ]
1.9	It should show empty charts gracefully when there is no data for the selected client	UI (when migrated)	[ ]
1.10	It should show a loading state while GraphQL data is being fetched	UI (when migrated)	[ ]
1.11	It should handle GraphQL errors by showing the loading state appropriately	UI (when migrated)	[ ]

---

Login

Authentication

#	Behavior	Test Strategy	Status
2.1	It should display a "Login with Google" button on the login page	UI (when migrated)	[ ]
2.2	It should link the login button to Google OAuth	UI (when migrated)	[ ]
2.3	It should preserve the redirect-to query parameter in the Google OAuth URL	Integration	[ ]
2.4	It should display a warning notification with the logout reason when the logout-reason query parameter is set	UI (when migrated)	[ ]
2.5	It should redirect an already authenticated user away from the login page	Integration	[ ]

Needs Activation

#	Behavior	Test Strategy	Status
2.6	It should display the message: "Sorry, your user is not activated yet. Please have Ben Skinner enable your account." when the user's account is inactive	UI (when migrated)	[ ]
2.7	It should provide a "here" link that clears user state and redirects to the login page	Integration	[ ]

---

Transactions

List Display

#	Behavior	Test Strategy	Status
3.1	It should display a table of transactions with columns for amount, memo, location, approval status, vendor, accounts, date, and description	UI (when migrated)	[ ]
3.2	It should load the transaction list with a default date filter of the last 1 month	Integration	[ ]
3.3	It should allow filtering by vendor, account, bank account, date range, amount range, location, import batch, description, and linked status via a sidebar	UI (when migrated)	[ ]
3.4	It should debounce sidebar filter changes by 800ms before refreshing data	Integration	[ ]
3.5	It should support pagination with start and per-page parameters	Integration	[ ]
3.6	It should display checkboxes for row selection when the user is an admin	UI (when migrated)	[ ]
3.7	It should not display checkboxes or bulk action buttons for non-admin users	UI (when migrated)	[ ]

Transaction Edit

#	Behavior	Test Strategy	Status
3.8	It should open an edit sidebar when the user clicks a transaction row	UI (when migrated)	[ ]
3.9	It should allow updating the vendor, approval status, memo, and expense accounts	UI (when migrated)	[ ]
3.10	It should validate that the sum of expense account amounts equals the transaction amount	Unit + Integration	[ ]
3.11	It should validate that locations are valid for the selected accounts	Unit + Integration	[ ]
3.12	It should block editing locked transactions	Integration	[ ]
3.13	It should display validation errors inline in the edit form	UI (when migrated)	[ ]

Bulk Operations (Admin)

#	Behavior	Test Strategy	Status
3.14	It should allow deleting selected transactions or all visible transactions	Integration	[ ]
3.15	It should allow suppressing selected transactions instead of deleting them	Integration	[ ]
3.16	It should allow bulk coding by applying vendor, account, approval status, and account rules to multiple transactions	Integration	[ ]
3.17	It should allow importing transactions via a manual Yodlee import dialog	Integration	[ ]

Route Variants

#	Behavior	Test Strategy	Status
3.18	It should apply the correct default approval status filter for each route variant: all, unapproved, approved, requires-feedback, excluded	Integration	[ ]

---

Ledger

General Ledger

#	Behavior	Test Strategy	Status
4.1	It should display a table of journal entries with expandable line items	UI (when migrated)	[ ]
4.2	It should load the ledger with a default date filter of the last 1 month	Integration	[ ]
4.3	It should allow filtering by vendor, account, bank account, date range, amount range, and location via a sidebar	UI (when migrated)	[ ]
4.4	It should support virtual pagination controls	Integration	[ ]
4.5	It should allow admin users to export filtered results as a CSV download	Integration	[ ]
4.6	It should display "Not authorized" for users with the manager role	UI (when migrated)	[ ]

Profit and Loss

#	Behavior	Test Strategy	Status
4.7	It should generate a profit and loss report for a single client with a default period	Integration	[ ]
4.8	It should allow selecting multiple companies via a multi-select typeahead and generating a combined report	UI (when migrated)	[ ]
4.9	It should provide period preset buttons: 13 periods, 12 months, last week, week-to-date, last month, month-to-date, year-to-date, last calendar year, and full year	UI (when migrated)	[ ]
4.10	It should populate the correct date ranges when a period preset is selected	Unit	[ ]
4.11	It should allow custom period selection via start and end date pickers in advanced mode	UI (when migrated)	[ ]
4.12	It should optionally include period-over-period deltas	UI (when migrated)	[ ]
4.13	It should optionally break out the report by location, which is mutually exclusive with including deltas	Integration	[ ]
4.14	It should allow admin users to generate and download a PDF export	Integration	[ ]
4.15	It should provide an email composition link for single-client PDF exports	UI (when migrated)	[ ]
4.16	It should open a ledger detail sidebar when the user clicks a report cell	UI (when migrated)	[ ]
4.17	It should display "Not authorized" for users with the manager role	UI (when migrated)	[ ]

Cash Flows

#	Behavior	Test Strategy	Status
4.18	It should generate a cash flows statement report	Integration	[ ]
4.19	It should use the same company, period, delta, and location column controls as the profit and loss report	Integration	[ ]
4.20	It should allow admin users to export the report to PDF	Integration	[ ]
4.21	It should open a ledger detail sidebar when the user clicks a report cell	UI (when migrated)	[ ]
4.22	It should display "Not authorized" for users with the manager role	UI (when migrated)	[ ]

Profit and Loss Detail

#	Behavior	Test Strategy	Status
4.23	It should generate a detailed journal entry report with a default 2-week date range	Integration	[ ]
4.24	It should group journal entries by category: sales, COGS, payroll, controllable, fixed overhead, and ownership controllable	Integration	[ ]
4.25	It should display Gross Profit, Overhead, and Net Profit summaries	UI (when migrated)	[ ]
4.26	It should filter journal entries by the selected start and end dates	Integration	[ ]
4.27	It should allow admin users to export the report to PDF with an email link for single client	Integration	[ ]
4.28	It should display "Not authorized" for users with the manager role	UI (when migrated)	[ ]

Balance Sheet

#	Behavior	Test Strategy	Status
4.29	It should generate a balance sheet report as of a specific date	Integration	[ ]
4.30	It should allow selecting multiple companies and combining them into a single report	Integration	[ ]
4.31	It should optionally include a prior-year comparison with a side-by-side view	UI (when migrated)	[ ]
4.32	It should allow admin users to export the report to PDF with an email composition link for single client	Integration	[ ]
4.33	It should open ledger entries filtered by account and date range when the user clicks a cell	UI (when migrated)	[ ]
4.34	It should display "Not authorized" for users with the manager role	UI (when migrated)	[ ]

External Ledger

#	Behavior	Test Strategy	Status
4.35	It should display only externally-imported journal entries with an external_id	Integration	[ ]
4.36	It should allow admin users to delete selected entries, with a maximum of 1000 at once	Integration	[ ]
4.37	It should allow admin users to export to CSV	Integration	[ ]
4.38	It should display "Not authorized" for non-admin users	UI (when migrated)	[ ]

External Import

#	Behavior	Test Strategy	Status
4.39	It should allow admin users to paste tab-separated data into a textarea	UI (when migrated)	[ ]
4.40	It should provide a checkbox to indicate whether the first row is a header	UI (when migrated)	[ ]
4.41	It should parse the pasted data into a table with columns: Id, Client, Source, Vendor, Date, Account, Location, Debit, Credit, Note, and Cleared against	Integration	[ ]
4.42	It should validate that the client code exists	Unit + Integration	[ ]
4.43	It should validate that the vendor exists	Unit + Integration	[ ]
4.44	It should validate that the date is in MM/dd/yyyy format	Unit + Integration	[ ]
4.45	It should validate that total debits equal total credits	Unit + Integration	[ ]
4.46	It should validate that all amounts are greater than 0	Unit + Integration	[ ]
4.47	It should validate that entries are dated after the client's locked-until date	Integration	[ ]
4.48	It should validate that the location belongs to the client or is "A"	Unit + Integration	[ ]
4.49	It should validate that the account exists and the location matches the account's required location	Unit + Integration	[ ]
4.50	It should display errors per row with a dropdown explanation	UI (when migrated)	[ ]
4.51	It should show status icons indicating success, ignored, or existing per row after import	UI (when migrated)	[ ]
4.52	It should display the total success count, ignored count, and error count after import	UI (when migrated)	[ ]
4.53	It should provide an "Only show errors" filter	UI (when migrated)	[ ]
4.54	It should display "Not authorized" for non-admin users	UI (when migrated)	[ ]

---

Payments

#	Behavior	Test Strategy	Status
5.1	It should be fully migrated to SSR at /payment/; the legacy client route exists only for navbar highlighting	N/A	[x]

---

Reports

#	Behavior	Test Strategy	Status
6.1	It should be fully migrated to SSR at /company/reports; the legacy client route exists only for navbar highlighting	N/A	[x]

---

Vendors

Admin Vendor Management

#	Behavior	Test Strategy	Status
7.1	It should be fully migrated to SSR at /admin/vendor; the legacy client route exists only for navbar highlighting	N/A	[x]

New Vendor Dialog

#	Behavior	Test Strategy	Status
7.2	It should load the home dashboard with the vendor creation dialog pre-opened when navigating to /vendor/new	UI (when migrated)	[ ]
7.3	It should only open the vendor dialog if the user has :vendor :create permission	Integration	[ ]
7.4	It should allow creating a new vendor with name, terms, address, contacts, and default account	UI (when migrated)	[ ]
7.5	It should validate that only one terms override exists per client	Unit + Integration	[ ]
7.6	It should validate that only one schedule payment DOM override exists per client	Unit + Integration	[ ]
7.7	It should validate that only one account override exists per client	Unit + Integration	[ ]

---

Cross-Cutting Behaviors

GraphQL Query Patterns

#	Behavior	Test Strategy	Status
8.1	It should include the JWT token from the :user app-db state in all GraphQL requests	Integration	[ ]
8.2	It should track loading status per page using owns-state	Integration	[ ]
8.3	It should store GraphQL response data and sync URL query params via the ::data-page/received event	Integration	[ ]
8.4	It should debounce filter changes by 800ms before dispatching GraphQL requests	Integration	[ ]

Re-frame State Management

#	Behavior	Test Strategy	Status
8.5	It should merge filters, table params, and query params into ::data-page/params	Integration	[ ]
8.6	It should store GraphQL response data in ::data-page/data	Integration	[ ]
8.7	It should track selected rows for bulk operations in ::data-page/checked	Integration	[ ]
8.8	It should manage edit dialog state with start-form, change-handler, and save-succeeded events	Integration	[ ]
8.9	It should track async operation states as :loading, :complete, or :error	Integration	[ ]

Navigation

#	Behavior	Test Strategy	Status
8.10	It should redirect old SPA routes to new SSR routes after migration	Integration	[ ]
8.11	It should set up data subscriptions, forward event listeners, and parameter change watchers on page mount	Integration	[ ]
8.12	It should tear down data subscriptions, forward event listeners, and parameter change watchers on page unmount	Integration	[ ]

---

Test Data Requirements

Entity	Requirements
Users	Admin, power-user, manager, user, and read-only roles
Clients	Multiple clients with different locations; some with locked-until dates
Vendors	With/without default accounts, terms, and autopay settings
Accounts	Expense accounts with/without invoice allowance; different locations
Bank Accounts	Check, cash, and credit types
Transactions	Various approval statuses, dates, amounts, locked/unlocked states
Journal Entries	With/without external_id; various categories and accounts
Invoices	Various statuses and due dates for cash flow projections

Existing Tests to Preserve

• Test GraphQL query resolution for HomeDashboard, TransactionPage, LedgerPage, ProfitAndLoss, CashFlows, JournalDetailReport, BalanceSheet, and ExternalLedger
• Test re-frame event handlers for data page state transitions
• Test form validation logic for transaction editing and external ledger import

Dependencies

• GraphQL API (data fetching)
• Re-frame/Reagent (client-side state and rendering)
• Bidi (client-side routing)
• Recharts (chart rendering on Home page)
• Server-side PDF generation (P&L, Cash Flows, Balance Sheet, P&L Detail)

Migration Notes

Already Migrated to SSR

• Payments (/payments/) - Fully migrated to /payment/ SSR routes
• Reports (/reports/) - Fully migrated to /company/reports SSR routes
• Admin Vendors (/admin/vendors) - Fully migrated to /admin/vendor SSR routes

Still Legacy SPA (prioritized by complexity)

1. Transactions - High complexity (filters, edit form, bulk operations, manual import)
2. Home/Dashboard - Medium complexity (charts, cash flow calculations)
3. Ledger - Medium complexity (filters, CSV export)
4. External Ledger - Low-medium complexity (subset of ledger + delete)
5. External Import - Medium complexity (TSV parsing, validation, batch import)
6. Profit and Loss - High complexity (multi-company, periods, PDF export)
7. Cash Flows - High complexity (shares P&L infrastructure)
8. Profit and Loss Detail - Medium complexity (category filtering, running balances)
9. Balance Sheet - Medium complexity (comparison mode, drill-down)
10. Login - Low complexity (static page)
11. Needs Activation - Low complexity (static page)
12. New Vendor - Low complexity (dialog on home page)

Migration Risks

• Chart libraries: Home page uses Recharts (React). Replacement needed for SSR.
• PDF generation: P&L, Cash Flows, Balance Sheet, P&L Detail all support PDF export via server-side generation.
• Bulk operations: Transactions page has complex bulk coding/deletion with validation.
• External import: TSV parsing and validation logic lives entirely in SPA; server-side equivalent needed.