notid/integreat
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases Wiki Activity
Files
test-plan-docs
integreat/docs/testing/behaviors/pos.md
Bryce d627e3c5d0 refactor(all): rewrite all behavior docs in table format with checkboxes 
Rewrite all 11 remaining behavior documents to match the streamlined
invoice.md format:

- dashboard.md: 250 lines, 62 behaviors
- payment.md: 260 lines, behaviors for list, void, check printing, ACH
- transaction.md: 310 lines, list, import, admin insights
- ledger.md: 519 lines, entries, P&L, balance sheet, cash flows
- company.md: 320 lines, profile, 1099s, Plaid/Yodlee, reports
- admin.md: 494 lines, clients, accounts, vendors, rules, jobs, history
- pos.md: 405 lines, sales, deposits, tenders, refunds, shifts
- search-indicators.md: 167 lines, search modal, indicators
- auth.md: 184 lines, login, logout, impersonation, sessions
- outgoing-invoice.md: 192 lines, create, line items, PDF
- legacy-spa.md: 340 lines, all legacy pages (docs only)

All documents now use:
- Testing Patterns section with reusable abstractions
- Numbered tables: # | Behavior | Test Strategy | Status
- It should... behavior descriptions
- Checkboxes [ ]/[x] for tracking implementation
- Cross-Cutting Behaviors for permissions, lock dates, etc.
- Test Data Requirements tables
- Existing Tests to Preserve sections

Total: 3,844 lines of behavior documentation across 12 subsystem docs.
2026-05-04 13:48:51 -07:00

21 KiB
Raw Permalink Blame History

POS Behaviors

Overview

The POS (Point of Sale) module provides SSR (HTMX-driven) grid pages for viewing sales data imported from payment processors. All pages share a common grid layout with filters, sortable columns, and pagination. Data is read-only except for the admin Sales Summaries edit wizard.

Testing Philosophy

  • Prefer unit tests for pure business logic (calculations, validations, transformations)
  • Use integration tests for database interactions and cross-system flows
  • Use UI tests only for end-to-end happy paths that touch multiple pages
  • Every behavior must be user-visible; no tests for implementation details

Testing Patterns

Pattern: Grid Page Behaviors

Most list pages in Integreat follow the same pattern:

  1. Fetch IDs via Datomic query with filters
  2. Hydrate results via pull-many
  3. Render table with sortable columns
  4. Support selection (individual / all / all-filtered)
  5. Action buttons appear conditionally based on permissions and selection state

Test implications: Validate the query generation, not the rendering. UI tests only need to verify one filter and one sort work end-to-end.

Pattern: Wizard Behaviors

Wizards are multi-step forms with HTMX-driven navigation:

  1. Each step is a GET that renders a form fragment
  2. Form submissions are POST/PUT with validation
  3. Navigation between steps updates the wizard state
  4. Final submit creates/updates the entity

Test implications: Unit test validation logic and state transitions. Integration test the full wizard flow once. UI test only the happy path.

Pattern: Permission Gates

Every mutating operation checks:

  1. assert-can-see-client — user has access to the client
  2. assert-not-locked — invoice date >= client locked-until
  3. can? — user has the specific permission for the activity

Test implications: Integration test each gate independently. UI tests only verify the happy path with a permitted user.

Sales Orders

Display Behaviors

# Behavior Test Strategy Status
1.1 It should display a table with columns: Client, Date, Source, Total, Tax, Tip, Payment Methods UI [ ]
1.2 It should show the Client column only when multiple clients are in scope Integration [ ]
1.3 It should render the Source column as a pill badge UI [ ]
1.4 It should render each unique payment method as a pill in the Payment Methods column (cash, card, gift card, other) UI [ ]
1.5 It should display action buttons above the grid showing Total and Tax pills summarizing the currently filtered result set UI [ ]
1.6 It should show an external link icon row button when the sales order has a reference link UI [ ]

Filtering Behaviors

# Behavior Test Strategy Status
2.1 It should filter sales orders by date range (start date / end date) Integration [ ]
2.2 It should filter sales orders by total amount range (min / max) Integration [ ]
2.3 It should filter sales orders by payment method via radio cards: All, Cash, Card, Gift Card, Other Integration [ ]
2.4 It should filter sales orders by processor via radio cards: All, Square, Doordash, Uber Eats, Grubhub, Koala, EZCater, No Processor Integration [ ]
2.5 It should filter sales orders by category text input matching order line item category Integration [ ]
2.6 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
3.1 It should sort by client name ascending/descending Integration [ ]
3.2 It should sort by date ascending/descending Integration [ ]
3.3 It should sort by total amount ascending/descending Integration [ ]
3.4 It should sort by tax amount ascending/descending Integration [ ]
3.5 It should sort by tip amount ascending/descending Integration [ ]
3.6 It should sort by source ascending/descending Integration [ ]
3.7 It should sort by processor ascending/descending Integration [ ]
3.8 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
4.1 It should display 25 sales orders per page by default Integration [ ]
4.2 It should allow changing the per-page count Integration [ ]
4.3 It should calculate the total amount and tax across ALL matching sales orders, not just the current page Unit [ ]

Expected Deposits

Display Behaviors

# Behavior Test Strategy Status
5.1 It should display a table with columns: Client, Date, Sales Date, Total, Fee UI [ ]
5.2 It should show the Client column only when multiple clients are in scope Integration [ ]
5.3 It should show a totals breakdown per expected deposit, aggregating charges by sales date with count and amount UI [ ]
5.4 It should show an external link icon row button when the expected deposit has a reference link UI [ ]
5.5 It should show a "Transaction" button linking to the associated transaction when one exists UI [ ]

Filtering Behaviors

# Behavior Test Strategy Status
6.1 It should filter expected deposits by date range Integration [ ]
6.2 It should support exact match ID to jump to a specific record, showing a removable pill when active Integration [ ]
6.3 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
7.1 It should sort by client name ascending/descending Integration [ ]
7.2 It should sort by location ascending/descending Integration [ ]
7.3 It should sort by date ascending/descending Integration [ ]
7.4 It should sort by total amount ascending/descending Integration [ ]
7.5 It should sort by fee amount ascending/descending Integration [ ]
7.6 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
8.1 It should display 25 expected deposits per page by default Integration [ ]
8.2 It should allow changing the per-page count Integration [ ]

Tenders

Display Behaviors

# Behavior Test Strategy Status
9.1 It should display a table with columns: Client, Date, Total, Processor, Tip, Links UI [ ]
9.2 It should show the Client column only when multiple clients are in scope Integration [ ]
9.3 It should render the Processor column as a pill badge UI [ ]
9.4 It should show an external link icon row button when the tender has a reference link UI [ ]
9.5 It should show an "expected deposit" pill in the Links column when an associated expected deposit exists UI [ ]

Filtering Behaviors

# Behavior Test Strategy Status
10.1 It should filter tenders by date range Integration [ ]
10.2 It should filter tenders by processor via radio cards: All, Square, Doordash, Uber Eats, Grubhub, Koala, EZCater, No Processor Integration [ ]
10.3 It should filter tenders by total amount range (min / max) Integration [ ]
10.4 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
11.1 It should sort by client name ascending/descending Integration [ ]
11.2 It should sort by date ascending/descending Integration [ ]
11.3 It should sort by total amount ascending/descending Integration [ ]
11.4 It should sort by tip amount ascending/descending Integration [ ]
11.5 It should sort by processor ascending/descending Integration [ ]
11.6 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
12.1 It should display 25 tenders per page by default Integration [ ]
12.2 It should allow changing the per-page count Integration [ ]

Refunds

Display Behaviors

# Behavior Test Strategy Status
13.1 It should display a table with columns: Client, Date, Total, Type, Fee UI [ ]
13.2 It should show the Client column only when multiple clients are in scope Integration [ ]

Filtering Behaviors

# Behavior Test Strategy Status
14.1 It should filter refunds by date range Integration [ ]
14.2 It should filter refunds by total amount range (min / max) Integration [ ]
14.3 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
15.1 It should sort by client name ascending/descending Integration [ ]
15.2 It should sort by date ascending/descending Integration [ ]
15.3 It should sort by total amount ascending/descending Integration [ ]
15.4 It should sort by fee amount ascending/descending Integration [ ]
15.5 It should sort by type ascending/descending Integration [ ]
15.6 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
16.1 It should display 25 refunds per page by default Integration [ ]
16.2 It should allow changing the per-page count Integration [ ]

Cash Drawer Shifts

Display Behaviors

# Behavior Test Strategy Status
17.1 It should display a table with columns: Client, Date, Paid in, Paid out, Expected cash, Opened cash UI [ ]
17.2 It should show the Client column only when multiple clients are in scope Integration [ ]

Filtering Behaviors

# Behavior Test Strategy Status
18.1 It should filter cash drawer shifts by date range Integration [ ]
18.2 It should filter cash drawer shifts by total amount range (min / max) Integration [ ]
18.3 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
19.1 It should sort by client name ascending/descending Integration [ ]
19.2 It should sort by date ascending/descending Integration [ ]
19.3 It should sort by paid-in amount ascending/descending Integration [ ]
19.4 It should sort by paid-out amount ascending/descending Integration [ ]
19.5 It should sort by expected-cash amount ascending/descending Integration [ ]
19.6 It should sort by opened-cash amount ascending/descending Integration [ ]
19.7 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
20.1 It should display 25 cash drawer shifts per page by default Integration [ ]
20.2 It should allow changing the per-page count Integration [ ]

Sales Summaries

Display Behaviors

# Behavior Test Strategy Status
21.1 It should display a table with columns: Client, Date, Debits, Credits UI [ ]
21.2 It should show the Client column only when multiple clients are in scope Integration [ ]
21.3 It should display debit-line items with category and amount UI [ ]
21.4 It should display credit-line items with category and amount UI [ ]
21.5 It should show a red "missing account" warning pill for unmapped items UI [ ]
21.6 It should show a green "Total" pill for balanced summaries (debits equal credits) UI [ ]
21.7 It should show a red "Total" pill for unbalanced summaries (debits do not equal credits) UI [ ]
21.8 It should show an edit (pencil) icon row button opening the edit wizard modal UI [ ]

Filtering Behaviors

# Behavior Test Strategy Status
22.1 It should filter sales summaries by date range Integration [ ]
22.2 Given multiple filters are applied, when the user changes one filter, then the table should refresh with the combined filter set Integration [ ]

Sorting Behaviors

# Behavior Test Strategy Status
23.1 It should sort by client name ascending/descending Integration [ ]
23.2 It should sort by date ascending/descending Integration [ ]
23.3 It should sort by debits ascending/descending Integration [ ]
23.4 It should sort by credits ascending/descending Integration [ ]
23.5 Given the user clicks a column header twice, then the sort direction should toggle Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
24.1 It should display 25 sales summaries per page by default Integration [ ]
24.2 It should allow changing the per-page count Integration [ ]

Edit Wizard Behaviors

# Behavior Test Strategy Status
25.1 It should open a modal dialog when the edit button is clicked UI [ ]
25.2 It should display a data grid of summary items with columns: Category, Account, Debits, Credits UI [ ]
25.3 It should render auto items (non-manual) with read-only Category and amount, editable Account via typeahead UI [ ]
25.4 It should render manual items with editable Category (text input), Account (typeahead), Debit amount, and Credit amount UI [ ]
25.5 It should allow adding new manual items via a "New Summary Item" row UI [ ]
25.6 It should allow removing manual items via an X button UI [ ]
25.7 It should validate that an item cannot have both credit and debit amounts Unit + Integration [ ]
25.8 It should display a total row with running totals for debits and credits UI [ ]
25.9 It should display an unbalanced row showing the difference when debits do not equal credits UI [ ]
25.10 It should search accounts scoped to the client with purpose "invoice" in the account typeahead Integration [ ]
25.11 It should flash the row and close the modal after successful save UI [ ]

Cross-Cutting Behaviors

HTMX Live Filtering Behaviors

# Behavior Test Strategy Status
26.1 It should trigger table refresh on filter form change with a 500ms debounce Integration [ ]
26.2 It should trigger table refresh on hot-filter keyup with a 1000ms debounce Integration [ ]
26.3 It should POST to the table route and swap the grid contents Integration [ ]
26.4 It should update the browser URL via hx-push-url when filters change Integration [ ]

Date Range Behaviors

# Behavior Test Strategy Status
27.1 It should support start-date and end-date query params on all pages Integration [ ]
27.2 It should render the date range filter consistently across all pages UI [ ]
27.3 Given a date range with no start or end date, then the query should use scan functions with nil boundaries Integration [ ]

Total Range Behaviors

# Behavior Test Strategy Status
28.1 It should support total-gte and total-lte query params on pages with amount filters Integration [ ]
28.2 It should render money inputs for the total range filter UI [ ]

Exact Match ID Behaviors

# Behavior Test Strategy Status
29.1 It should support exact-match-id to jump to a specific record on applicable pages Integration [ ]
29.2 It should show a removable pill when exact-match-id is active UI [ ]

Sorting Behaviors

# Behavior Test Strategy Status
30.1 It should toggle ascending/descending sort when a sortable column header is clicked Integration [ ]
30.2 It should support multi-sort with active sorts appearing as removable pills above the grid Integration [ ]
30.3 It should remove a sort when the X on its pill is clicked Integration [ ]
30.4 It should default to sort by date descending for most pages Integration [ ]

Pagination Behaviors

# Behavior Test Strategy Status
31.1 It should display first/previous/next/last pagination controls UI [ ]
31.2 It should display the total count above the grid UI [ ]

Client Scoping Behaviors

# Behavior Test Strategy Status
32.1 It should scope all queries to the user's accessible clients (trimmed to max 20) Integration [ ]
32.2 It should hide the Client column when only one client is in scope Integration [ ]
32.3 It should support client-id and client-code URL params Integration [ ]

Permission Behaviors

# Behavior Test Strategy Status
33.1 It should require (can? identity {:subject :sales :activity :read}) to access POS pages Integration [ ]
33.2 It should require admin access (wrap-admin) to access Sales Summaries Integration [ ]
33.3 It should redirect unauthenticated users Integration [ ]

Test Data Requirements

Entity Requirements
Clients Multiple clients with db/id, client/name, client/code; some with locked-until dates
Sales Orders With :sales-order/date, :sales-order/total, :sales-order/tax, :sales-order/tip, :sales-order/source, :sales-order/charges (with charge/type-name, charge/processor), :sales-order/line-items (with order-line-item/category)
Expected Deposits With :expected-deposit/date, :expected-deposit/total, :expected-deposit/fee, :expected-deposit/client, optional transaction/_expected-deposit
Tenders (Charges) With :charge/date, :charge/total, :charge/tip, :charge/processor, optional expected-deposit/_charges
Refunds With :sales-refund/date, :sales-refund/total, :sales-refund/fee, :sales-refund/type
Cash Drawer Shifts With :cash-drawer-shift/date, :cash-drawer-shift/paid-in, :cash-drawer-shift/paid-out, :cash-drawer-shift/expected-cash, :cash-drawer-shift/opened-cash
Sales Summaries With :sales-summary/date, :sales-summary/client, :sales-summary/items (with ledger-mapped/ledger-side, ledger-mapped/amount, sales-summary-item/category, optional ledger-mapped/account)
Accounts With purpose "invoice", scoped to clients, for Sales Summaries edit wizard

Existing Tests to Preserve

  • test/clj/auto_ap/ssr/pos/sales_orders_test.clj — Sales orders grid behaviors
  • test/clj/auto_ap/ssr/pos/expected_deposits_test.clj — Expected deposits grid behaviors
  • test/clj/auto_ap/ssr/pos/tenders_test.clj — Tenders grid behaviors
  • test/clj/auto_ap/ssr/pos/refunds_test.clj — Refunds grid behaviors
  • test/clj/auto_ap/ssr/pos/cash_drawer_shifts_test.clj — Cash drawer shifts grid behaviors
  • test/clj/auto_ap/ssr/admin/sales_summaries_test.clj — Sales summaries admin behaviors

Dependencies

  • Datomic (primary store)
  • HTMX/Alpine.js (frontend interactivity)
  • Grid system: auto-ap.ssr.grid-page-helper provides build, page-route, table-route, row*, table*
  • Components: auto-ap.ssr.components for data grids, pills, buttons, inputs
  • Querying: auto-ap.datomic for query2, pull-many, apply-pagination, apply-sort-3
  • Ions: iol-ion.query/scan-sales-orders, scan-expected-deposits, scan-charges, scan-sales-refunds, scan-cash-drawer-shifts
  • Permissions: auto-ap.permissions/can?
  • Time: auto-ap.time for date formatting and localization
  • Schema validation: Malli schemas enforce query params on every request
Reference in New Issue View Git Blame Copy Permalink