integreat/docs/testing/behaviors/company.md

Company Behaviors

Overview

The Company section provides company-level settings and reporting for Integreat users. It is implemented as SSR pages using HTMX and is accessed via the left navigation sidebar under "My Company". All pages require authentication and enforce client-level access controls. Most pages react to client selection changes by refreshing their content via HTMX.

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: Permission Gates

Every mutating operation checks:

1. assert-can-see-client — user has access to the client
2. can? — user has the specific permission for the activity
3. Admin role checks for destructive operations

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

Pattern: HTMX Refresh on Client Switch

All company pages listen for clientSelected from:body event and refresh #app-contents with a 300ms swap animation.

Test implications: Integration test the event handling and route params. UI test only one page to verify the swap animation.

---

Company Profile

Display Behaviors

#	Behavior	Test Strategy	Status
1.1	It should display a "Please select a company" placeholder card when no client is selected	UI	[ ]
1.2	It should display the company name as a heading when a client is selected	UI	[ ]
1.3	It should display the company address (street, city, state, zip) when address data exists	UI	[ ]
1.4	It should omit missing address fields without showing error placeholders	UI	[ ]
1.5	It should show a "Download vendor list" button	UI	[ ]
1.6	It should download a CSV/Excel export when the download button is clicked	Integration	[ ]

Signature Behaviors

#	Behavior	Test Strategy	Status
2.1	It should show the signature section only when the user has signature edit permission	Integration	[ ]
2.2	It should display the saved signature image when one exists	UI	[ ]
2.3	It should show a "New signature" button that enables drawing mode on a canvas	UI	[ ]
2.4	It should show a "Clear" button that clears the canvas while in drawing mode	UI	[ ]
2.5	It should show an "Accept" button that submits the drawn signature	UI	[ ]
2.6	It should reject invalid signature image data with a validation error	Unit + Integration	[ ]
2.7	It should provide a drag-and-drop zone for uploading JPEG signature files	UI	[ ]
2.8	It should change the drop zone background color on hover	UI	[ ]
2.9	It should refresh the signature section with the uploaded image on successful upload	Integration	[ ]

---

1099 Reports

Display Behaviors

#	Behavior	Test Strategy	Status
3.1	It should display vendors who received $600 or more in check payments during the current tax year	Integration	[ ]
3.2	It should show grid columns: Client, Vendor Name, TIN, Expense Account, Address, Paid	UI	[ ]
3.3	It should display the vendor's legal entity name as a subtitle under the vendor name	UI	[ ]
3.4	It should show a 1099 type pill badge when a 1099 type is set	UI	[ ]
3.5	It should display the TIN with a TIN type pill (EIN or SSN)	UI	[ ]
3.6	It should show "No address" placeholder when the vendor has no address	UI	[ ]
3.7	It should display the total paid amount as a pill badge rounded to the nearest dollar	UI	[ ]
3.8	It should show an edit icon button on each row	UI	[ ]
3.9	It should show vendors shared across multiple clients in each client's context	Integration	[ ]
3.10	It should show an empty grid when no vendors received $600+ in checks during the tax year	UI	[ ]

Filtering & Sorting Behaviors

#	Behavior	Test Strategy	Status
4.1	It should support standard grid query params (sort, pagination, search)	Integration	[ ]
4.2	It should default sort by client code then amount	Integration	[ ]

Edit Behaviors

#	Behavior	Test Strategy	Status
5.1	It should open a vendor edit dialog in a modal when the edit icon is clicked	UI	[ ]
5.2	It should display address fields (Street 1, Street 2, City, State, ZIP) in the dialog	UI	[ ]
5.3	It should validate the ZIP code as 5 digits or empty	Unit + Integration	[ ]
5.4	It should allow entering either a legal entity name or first/middle/last name	UI	[ ]
5.5	It should allow entering a TIN and selecting TIN type (EIN or SSN)	UI	[ ]
5.6	It should allow selecting a 1099 type from a dropdown	UI	[ ]
5.7	It should close the modal and refresh the row with a flash highlight on successful save	Integration	[ ]
5.8	It should null the address if all address fields are empty and no existing address	Integration	[ ]

---

Expense Reports

Chart Behaviors

#	Behavior	Test Strategy	Status
6.1	It should display a bar chart of expenses grouped by top 20 expense accounts over the last 8 weeks	UI	[ ]
6.2	It should show week ranges (Monday-Sunday) formatted as dates on the X-axis	UI	[ ]
6.3	It should provide a vendor typeahead to filter expenses to a specific vendor	Integration	[ ]
6.4	It should provide an expense account typeahead to filter to a specific account	Integration	[ ]
6.5	It should refresh the chart when filters change	Integration	[ ]
6.6	It should default to last 65 days of data but display last 8 weeks	Integration	[ ]

Invoice Totals Behaviors

#	Behavior	Test Strategy	Status
7.1	It should display a grid of total invoice amounts per vendor per company	UI	[ ]
7.2	It should provide start and end date range filters	UI	[ ]
7.3	It should default the date range to the last 30 days	Integration	[ ]
7.4	It should show the vendor name in a sticky left column	UI	[ ]
7.5	It should show "-" for zero amounts	UI	[ ]
7.6	It should push filter changes to browser history	Integration	[ ]

---

Reconciliation Reports

Access Behaviors

#	Behavior	Test Strategy	Status
8.1	It should show the reconciliation navigation link only when the user has reconciliation report permission	Integration	[ ]
8.2	It should require start and end dates to be submitted via a "Run" button	UI	[ ]
8.3	It should show a "Please choose a time range to run the report" message when no dates are selected	UI	[ ]

Display Behaviors

#	Behavior	Test Strategy	Status
8.4	It should display a grid with columns: Bank Account, Source Count, Synced Count, Approved, Unapproved, Requires Feedback, Missing	UI	[ ]
8.5	It should highlight rows with green background when external count equals synced count	UI	[ ]
8.6	It should highlight rows with red background when counts mismatch	UI	[ ]
8.7	It should display a missing transactions count with a tooltip button	UI	[ ]
8.8	It should show a popup table of missing transaction dates and amounts when the tooltip is clicked	UI	[ ]
8.9	It should hide the missing transactions tooltip when the count is zero	UI	[ ]

---

Plaid Bank Linking

Account Grid Behaviors

#	Behavior	Test Strategy	Status
9.1	It should display a grid of Plaid-linked accounts with columns: Plaid Item, Integreat Status, Plaid Bank Status, Accounts	UI	[ ]
9.2	It should show a red pill with error message tooltip when any linked bank account has failed or unauthorized status	UI	[ ]
9.3	It should show a green "Success" pill when all accounts are healthy	UI	[ ]
9.4	It should display linked accounts with name, masked number, last synced date, and identicon	UI	[ ]
9.5	It should support sorting by external ID and Plaid bank status	Integration	[ ]
9.6	It should show an empty grid when no bank accounts are linked	UI	[ ]

Link Behaviors

#	Behavior	Test Strategy	Status
10.1	It should show a "Link account" button when a client is selected	UI	[ ]
10.2	It should hide the link button when no client is selected	UI	[ ]
10.3	It should open a Plaid Link modal when the link button is clicked	UI	[ ]
10.4	It should create the Plaid item and accounts in the system after successful linking	Integration	[ ]
10.5	It should redirect back to the Plaid page after successful account linking	Integration	[ ]

Re-authenticate Behaviors

#	Behavior	Test Strategy	Status
11.1	It should show a "Reauthenticate" button on each row	UI	[ ]
11.2	It should open Plaid Link in update mode when reauthenticate is clicked	UI	[ ]
11.3	It should refresh the row after successful reauthentication	Integration	[ ]

---

Yodlee Bank Linking

Account Grid Behaviors

#	Behavior	Test Strategy	Status
12.1	It should display a grid of Yodlee provider accounts with columns: Client, Provider Account, Status, Detailed Status, Last Updated, Accounts	UI	[ ]
12.2	It should hide the Client column when the user has only one client	UI	[ ]
12.3	It should show a green pill for success status and a yellow pill for other statuses	UI	[ ]
12.4	It should display linked accounts with name and number	UI	[ ]
12.5	It should support sorting by status, client, provider account, and last updated	Integration	[ ]
12.6	It should show an empty grid when no bank accounts are linked	UI	[ ]

Link Behaviors

#	Behavior	Test Strategy	Status
13.1	It should show a "Link new account" button	UI	[ ]
13.2	It should disable the link button and show helper text when no client is selected	UI	[ ]
13.3	It should open a Yodlee Fastlink modal when the link button is clicked	UI	[ ]
13.4	It should display an error notification and close the modal after 3 seconds when Yodlee returns an error	Integration	[ ]

Re-authenticate Behaviors

#	Behavior	Test Strategy	Status
14.1	It should show a "Reauthenticate" button per row	UI	[ ]
14.2	It should open Fastlink in edit mode when reauthenticate is clicked	UI	[ ]
14.3	It should refresh the row after successful reauthentication	Integration	[ ]

Admin Behaviors

#	Behavior	Test Strategy	Status
15.1	It should show a refresh button on each row for admin users	Integration	[ ]
15.2	It should trigger a Yodlee account refresh when the refresh button is clicked	Integration	[ ]
15.3	It should refresh the row after successful Yodlee refresh	Integration	[ ]

---

Generated Reports List

Display Behaviors

#	Behavior	Test Strategy	Status
16.1	It should display a grid of previously generated reports with columns: Name, Created by, Created	UI	[ ]
16.2	It should show the creator name as a pill badge	UI	[ ]
16.3	It should show an empty grid when no reports have been generated	UI	[ ]

Row Action Behaviors

#	Behavior	Test Strategy	Status
17.1	It should provide a download link to the report file on each row	UI	[ ]
17.2	It should show a delete button on each row for admin users	Integration	[ ]
17.3	It should delete the report and its file when the delete button is clicked	Integration	[ ]

Filtering & Sorting Behaviors

#	Behavior	Test Strategy	Status
18.1	It should support filtering by date range and client	Integration	[ ]
18.2	It should support sorting by client, created date, creator, and name	Integration	[ ]

---

Cross-Cutting Behaviors

Client Switching Behaviors

#	Behavior	Test Strategy	Status
19.1	It should refresh page content with a 300ms swap animation when the user switches clients	Integration	[ ]
19.2	It should show appropriate placeholder states when no client is selected on pages that require one	UI	[ ]
19.3	It should operate 1099 and reports grids across all visible clients when no single client is selected	Integration	[ ]

Permission Behaviors

#	Behavior	Test Strategy	Status
20.1	It should block access to company pages for unauthenticated users	Integration	[ ]
20.2	It should block access to company pages for users without client access	Integration	[ ]
20.3	It should hide the signature section from users without signature edit permission	Integration	[ ]
20.4	It should hide the reconciliation report navigation link from users without reconciliation report permission	Integration	[ ]
20.5	It should hide the delete report button from non-admin users	Integration	[ ]
20.6	It should hide the Yodlee refresh button from non-admin users	Integration	[ ]

Bank Account Search Behaviors

#	Behavior	Test Strategy	Status
21.1	It should provide a bank account typeahead for searching accounts belonging to a specific client	Integration	[ ]
21.2	It should show "Please select a client" message when no client is selected in the bank account typeahead	UI	[ ]

---

Test Data Requirements

Entity	Requirements
Clients	Multiple clients with different codes, names, and addresses; one with complete address, one with no address; one with existing signature file, one without
Vendors	With 1099 data (legal entity name, TIN, TIN type, 1099 type, address); with and without addresses; who received $600+ in check payments in 2025; who received less than $600; shared across multiple clients
Payments	Check payments dated within 2025 for 1099 testing; payments of different types (check, ACH) — only checks count toward 1099; payments to vendors across multiple clients
Invoices	Non-voided invoices with expense account allocations for expense report testing; with different vendors and expense accounts; dated across multiple weeks for 8-week breakdown
Bank Accounts	Plaid-linked accounts with various statuses (success, error, unauthorized); Yodlee-linked accounts with various statuses
Reports	At least one generated report with name, creator, created date, and file URL; reports belonging to different clients
Users	Admin user (full access); user with signature edit permission; user with reconciliation report permission; user with single client access; user with multiple client access; read-only user (should not see company nav)

Existing Tests to Preserve

• No existing company-specific behavior tests were identified at the time of writing.
• Any future company behavior tests should be added under test/clj/auto_ap/company/ or similar.

Dependencies

• Datomic (primary store for all entities and queries)
• Amazonica S3 (signature image storage and report file storage)
• Plaid API (bank account linking)
• Yodlee API (bank account linking)
• Intuit/QuickBooks API (reconciliation report data)
• Solr (client name search)
• HTMX (server-rendered interactions)
• Alpine.js (signature canvas state, drag-and-drop, modal state, chart initialization)
• Chart.js (expense breakdown bar chart)
• SignaturePad library (canvas signature drawing)
• Plaid Link SDK (Plaid account linking)
• Yodlee Fastlink SDK (Yodlee account linking)
• Jdenticon (account identicons in Plaid grid)