notid/integreat
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
6b5d33a32f20c1c8b935f9ff3e1eb34cac892eae
integreat/docs/testing/behaviors/dashboard.md
Bryce 6b5d33a32f feat(tests): implement integration and unit tests for auth, company, and ledger behaviors 
- Auth: 30 tests (97 assertions) covering OAuth, sessions, JWT, impersonation, roles
- Company: 35 tests (92 assertions) covering profile, 1099, expense reports, permissions
- Ledger: 113 tests (148 assertions) covering grid, journal entries, import, reports
- Fix existing test failures in running_balance, insights, tx, plaid, graphql
- Fix InMemSolrClient to handle Solr query syntax properly
- Update behavior docs: auth (42 done), company (32 done), ledger (120 done)
- All 478 tests pass with 0 failures, 0 errors
2026-05-08 16:12:08 -07:00

12 KiB
Raw Blame History

Dashboard Behaviors

Overview

The Dashboard is an admin-only, SSR-based overview page that displays financial summary cards across selected clients. It provides at-a-glance visibility into bank account balances, outstanding tasks, recent sales trends, expense breakdowns, and profit/loss summaries. Cards are loaded lazily via HTMX for progressive rendering.

Testing Philosophy

  • Prefer unit tests for pure business logic (calculations, formatting, client trimming)
  • Use integration tests for database interactions and cross-system flows (Datomic queries, GraphQL calls)
  • Use UI tests only for end-to-end happy paths and visual states
  • Every behavior must be user-visible; no tests for implementation details

Testing Patterns

Pattern: Progressive Card Loading

Dashboard cards follow a progressive loading pattern:

  1. SSR renders stub cards with loading spinners
  2. Each stub triggers an independent HTMX request on load
  3. Card endpoints return HTML fragments that replace the stub content
  4. Cards load independently without blocking each other

Test implications: Unit test the card query logic. Integration test each card endpoint returns valid HTML. UI test only needs to verify the page loads and cards appear.

Pattern: Client Context Propagation

All dashboard operations depend on selected clients:

  1. Client selection triggers a page-wide refresh via HTMX
  2. wrap-trim-clients middleware limits to 20 clients before queries execute
  3. All card endpoints receive the same trimmed client set

Test implications: Integration test that changing clients updates all cards. Unit test the trimming logic.

Pattern: Admin Permission Gating

The dashboard is restricted to admin users:

  1. wrap-admin middleware checks user role before any data access
  2. Non-admin users are redirected before reaching handlers
  3. Middleware is applied consistently to all card endpoints

Test implications: Integration test each endpoint independently for permission enforcement.

Dashboard Page

Page Loading Behaviors

# Behavior Test Strategy Status
1.1 It should render the main dashboard page with navigation, client selector, and "Dashboard" breadcrumb for admin users UI SKIPPED
1.2 It should display six stub cards with loading spinners for progressive rendering UI SKIPPED
1.3 It should trigger independent HTMX requests to load each card's content on page load Integration SKIPPED
1.4 It should progressively replace stub cards with actual data as responses arrive UI SKIPPED

Bank Accounts Card

Display Behaviors

# Behavior Test Strategy Status
2.1 It should display each client's name, account name, ledger balance, and last sync time UI SKIPPED
2.2 It should exclude bank accounts with cash type from the display Integration [x]
2.3 It should format ledger balances as currency ($X,XXX.XX) Unit + UI SKIPPED
2.4 It should display the last sync timestamp in standard time format when present Unit + UI SKIPPED
2.5 It should display Intuit balance and sync time for Intuit-linked accounts UI SKIPPED
2.6 It should display Yodlee available balance, sync time, and pending balance for Yodlee-linked accounts UI SKIPPED
2.7 It should display Plaid balance and sync time for Plaid-linked accounts UI SKIPPED
2.8 It should display $0.00 for missing or null balances Unit + UI SKIPPED

Sales Card

Display Behaviors

# Behavior Test Strategy Status
3.1 It should display a bar chart of gross sales for the last 14 days UI SKIPPED
3.2 It should render an empty bar chart when no sales orders exist in the date range UI SKIPPED

Data Behaviors

# Behavior Test Strategy Status
3.3 It should query and sum sales order totals by date for the selected clients Integration [x]

Expense Card

Display Behaviors

# Behavior Test Strategy Status
4.1 It should display a pie chart of the top 5 expense accounts for the last month UI SKIPPED
4.2 It should render an empty pie chart when no invoices with expense accounts exist in the date range UI SKIPPED

Data Behaviors

# Behavior Test Strategy Status
4.3 It should sum expense amounts by account name for the selected clients Integration [x]

Profit & Loss Card

Display Behaviors

# Behavior Test Strategy Status
5.1 It should display income and expenses aggregated by category (sales, COGS, payroll, controllable, fixed overhead, ownership controllable) UI SKIPPED
5.2 It should show $0.00 for both income and expenses when no data exists for the period UI SKIPPED

Data Behaviors

# Behavior Test Strategy Status
5.3 It should query P&L data via GraphQL for the selected clients and last month Integration [x]

Tasks Card

Display Behaviors

# Behavior Test Strategy Status
6.1 It should display the count of unpaid invoices when the count is non-zero UI SKIPPED
6.2 It should display the count of uncategorized transactions requiring feedback when the count is non-zero UI SKIPPED
6.3 It should provide a "Pay now" link for unpaid invoices linking to the unpaid invoices page with year date range UI SKIPPED
6.4 It should provide a "Review now" link for uncategorized transactions linking to the requires-feedback page UI SKIPPED
6.5 It should hide task sections entirely when their respective counts are zero Integration [x]

Data Behaviors

# Behavior Test Strategy Status
6.6 It should query Datomic for invoices with unpaid status for the selected clients Integration [x]
6.7 It should query Datomic for transactions with requires-feedback approval status for the selected clients Integration [x]

Expense Breakdown Card

Display Behaviors

# Behavior Test Strategy Status
7.1 It should display a bar chart breaking down expenses by account UI SKIPPED
7.2 It should render an empty chart when no expense data exists UI SKIPPED
7.3 It should provide Vendor and Account typeahead filters UI SKIPPED

Data Behaviors

# Behavior Test Strategy Status
7.4 It should reload the chart with filtered data when filter selections change Integration SKIPPED
7.5 It should update the URL with filter query parameters via hx-push-url Integration SKIPPED
7.6 It should exclude voided invoices from the breakdown Integration [x]

Filtering Behaviors

Expense Breakdown Filters

# Behavior Test Strategy Status
8.1 It should filter the expense breakdown chart by vendor selection Integration SKIPPED
8.2 It should filter the expense breakdown chart by expense account selection Integration SKIPPED
8.3 It should trigger an HTMX request to reload the chart when any filter changes Integration SKIPPED

Client Selection Behaviors

# Behavior Test Strategy Status
9.1 It should update the dashboard content when the user selects different clients from the dropdown UI SKIPPED
9.2 It should trigger a clientSelected event on the body when client selection changes Integration SKIPPED
9.3 It should swap the dashboard content area with fresh content for the newly selected clients Integration SKIPPED
9.4 It should re-fetch all card data with the new client context Integration SKIPPED
9.5 It should limit reports to the first 20 selected clients from the valid set Unit + Integration [x]
9.6 It should display a yellow warning banner when more than 20 clients are selected UI SKIPPED
9.7 It should persist the warning banner across client selection changes until fewer than 21 clients are selected UI SKIPPED
9.8 It should trim the client set before executing any card data queries Integration [x]

Error Handling Behaviors

# Behavior Test Strategy Status
10.1 It should load each card independently via separate HTMX requests Integration [x]
10.2 It should not prevent other cards from loading when one card endpoint fails Integration [x]
10.3 It should display a loading spinner on stub cards until data loads or a timeout occurs UI SKIPPED
10.4 It should return appropriate HTTP status codes for card endpoint errors without breaking the page layout Integration [x]

Cross-Cutting Behaviors

Permission Behaviors

# Behavior Test Strategy Status
11.1 It should allow only admin users to access the dashboard page and card endpoints Integration [x]
11.2 It should redirect non-admin authenticated users to /login with a 302 status Integration [x]
11.3 It should redirect unauthenticated users to /login with a redirect-to parameter Integration [x]
11.4 It should verify admin role via middleware before executing any data queries Integration [x]

Empty State Behaviors

# Behavior Test Strategy Status
12.1 It should render the dashboard page when no clients are selected, with all cards showing empty states UI SKIPPED
12.2 It should display an empty bank accounts list when no clients are selected UI SKIPPED
12.3 It should display an empty sales chart when no clients are selected UI SKIPPED
12.4 It should display an empty expense pie chart when no clients are selected UI SKIPPED
12.5 It should show $0.00 income and expenses in the P&L card when no clients are selected UI SKIPPED
12.6 It should hide all task sections when no clients are selected UI SKIPPED

Test Data Requirements

Entity Requirements
Users Admin user with access to multiple clients; non-admin user for permission denial
Clients Minimum 2, ideally 25+; mix with/without bank accounts
Bank Accounts Various types (checking, savings, cash); some linked to Intuit, Yodlee, Plaid; with/without balances and sync timestamps
Sales Orders Orders within and outside the 14-day window with totals
Invoices With expense accounts and unpaid status; voided invoices to test exclusion
Transactions With requires-feedback approval status
Chart of Accounts Categories: sales, COGS, payroll, controllable, fixed overhead, ownership controllable

Existing Tests to Preserve

  • No existing dashboard-specific tests have been identified in the current test suite. Any tests covering dashboard routes or card handlers should be preserved during refactoring.

Dependencies

  • Datomic (primary data store for all card queries)
  • GraphQL/Lacinia (P&L data via get-profit-and-loss-raw)
  • HTMX (progressive card loading via hx-get/hx-trigger/hx-swap)
  • Chart.js (canvas-based charts)
  • Alpine.js (chart data binding)
Reference in New Issue View Git Blame Copy Permalink