integreat/docs/testing/behaviors/outgoing-invoice.md

Outgoing Invoice Behaviors

Overview

The Outgoing Invoice subsystem allows users to create and generate PDF invoices to send to customers. It provides a form-based workflow for specifying the client (sender), recipient details, invoice metadata (date, number, tax rate), and line items. Upon submission, the system calculates subtotals, applies tax, and invokes an AWS Lambda function (genpdf) to generate a downloadable PDF.

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: Form Submission with HTMX

Outgoing invoice forms use HTMX for asynchronous submission and partial page updates:

1. Form fields are rendered server-side with validation state
2. HTMX handles POST submission and swaps the response into the page
3. Success responses trigger modal display with PDF download link
4. Error responses re-render the form with validation errors

Test implications: Unit test validation logic and calculation functions. Integration test the full POST flow. UI test only the happy path.

Pattern: Dynamic Line Items

Line items are added and removed dynamically without page reload:

1. "Add line" button fetches a new row via HTMX
2. Each row has description, quantity, unit price inputs, and a delete button
3. Delete uses Alpine.js to fade out and remove the row
4. Empty line items are filtered out on submission

Test implications: Unit test the filtering and calculation logic. Integration test HTMX endpoints. UI test the add/remove interactions.

---

Create Invoice

Form Display Behaviors

#	Behavior	Test Strategy	Status
1.1	It should render a new invoice form with breadcrumbs: Invoices > Outgoing > New	UI	[ ]
1.2	It should display a client typeahead field labeled "From (client)"	UI	[ ]
1.3	It should display an invoice number input field	UI	[ ]
1.4	It should display a date picker pre-filled with today's date in normal-date format	UI	[ ]
1.5	It should display recipient name "To" field	UI	[ ]
1.6	It should display recipient address fields: street1, street2, city, state, zip	UI	[ ]
1.7	It should display a line items grid with one default empty row	UI	[ ]
1.8	It should display a tax percentage input with default value 10.0	UI	[ ]
1.9	It should display a "Generate" button to submit the form	UI	[ ]
1.10	It should display an "Add line" button to add more line items	UI	[ ]

Form Validation Behaviors

#	Behavior	Test Strategy	Status
2.1	It should require client selection	Integration	[ ]
2.2	It should require invoice date	Integration	[ ]
2.3	It should require recipient name in "To" field	Integration	[ ]
2.4	It should require invoice number	Integration	[ ]
2.5	It should require at least one line item with description, quantity, and unit price	Integration	[ ]
2.6	It should make recipient address street2 optional	Unit	[ ]
2.7	It should strip whitespace from street2 and treat empty as nil	Unit	[ ]
2.8	It should coerce line items from nested form parameters into a vector	Unit	[ ]
2.9	It should display validation errors next to the offending fields	UI	[ ]
2.10	It should redisplay the form with entered data preserved when validation fails	Integration	[ ]

Submission Behaviors

#	Behavior	Test Strategy	Status
3.1	It should filter out line items with empty descriptions before calculation	Unit	[ ]
3.2	It should calculate each line item total as unit-price * quantity	Unit	[ ]
3.3	It should calculate subtotal as the sum of all line item totals	Unit	[ ]
3.4	It should calculate tax as subtotal * (tax-rate / 100)	Unit	[ ]
3.5	It should calculate total as subtotal + tax	Unit	[ ]
3.6	It should format monetary values as $X,XXX.XX strings before sending to Lambda	Unit	[ ]
3.7	It should format the invoice date as normal-date string before sending to Lambda	Unit	[ ]
3.8	It should invoke the genpdf Lambda function with a JSON payload	Integration	[ ]
3.9	It should extract the S3 URL from the Lambda response	Integration	[ ]
3.10	It should display a modal with "Download your invoice" and a link to the S3 URL	UI	[ ]
3.11	Given the Lambda invocation fails, then it should display an error without showing a modal	Integration	[ ]
3.12	Given all line items are empty, then subtotal should be 0.0, tax should be 0.0, and total should be 0.0	Unit	[ ]

---

Line Items

Add Line Item Behaviors

#	Behavior	Test Strategy	Status
4.1	It should fetch a new empty line item row via HTMX when "Add line" is clicked	Integration	[ ]
4.2	It should append the new row to the line items grid	UI	[ ]
4.3	It should render each row with hidden db/id, description input, quantity money-input, unit-price money-input, and delete button	UI	[ ]
4.4	It should allow adding multiple line items	UI	[ ]

Remove Line Item Behaviors

#	Behavior	Test Strategy	Status
5.1	It should fade out a line item row over 500ms when the delete button is clicked	UI	[ ]
5.2	It should remove the line item row from the DOM after the fade animation	UI	[ ]
5.3	It should preserve data in remaining line items after deletion	UI	[ ]
5.4	It should allow deleting all line items, leaving the grid empty	UI	[ ]

Calculation Behaviors

#	Behavior	Test Strategy	Status
6.1	It should handle negative quantities in line item calculations	Unit	[ ]
6.2	It should show $0.00 for line items with zero unit price	Unit	[ ]
6.3	It should format large monetary values with comma separators (e.g., $1,234.56)	Unit	[ ]
6.4	It should format nil monetary values as $0.00	Unit	[ ]

---

PDF Generation

Lambda Integration Behaviors

#	Behavior	Test Strategy	Status
7.1	It should invoke genpdf Lambda with a JSON payload containing invoice data	Integration	[ ]
7.2	It should include formatted monetary strings in the Lambda payload	Unit	[ ]
7.3	It should include the invoice date as a normal-date string in the Lambda payload	Unit	[ ]
7.4	It should extract the S3 URL from a successful Lambda response	Integration	[ ]
7.5	It should present the S3 URL as a clickable download link in the modal	UI	[ ]

Error Handling Behaviors

#	Behavior	Test Strategy	Status
8.1	Given the Lambda returns invalid JSON, then it should propagate an error	Integration	[ ]
8.2	Given the S3 URL is inaccessible, then the link should still be presented but may fail on click	UI	[ ]
8.3	Given a very large invoice payload, then Lambda payload size limits may apply	Integration	[ ]

---

Cross-Cutting Behaviors

Authentication Behaviors

#	Behavior	Test Strategy	Status
9.1	It should redirect unauthenticated users to /login	Integration	[ ]
9.2	It should redirect unauthenticated users back to /outgoing-invoice/new after login	Integration	[ ]
9.3	It should apply wrap-secure middleware to all routes	Integration	[ ]
9.4	It should apply wrap-trim-client-ids middleware to requests	Integration	[ ]

Client Selection Behaviors

#	Behavior	Test Strategy	Status
10.1	It should populate the client typeahead from the :company-search endpoint	Integration	[ ]
10.2	It should only show clients the authenticated user has access to	Integration	[ ]

Tax Behaviors

#	Behavior	Test Strategy	Status
11.1	It should treat a whole number tax (e.g., 10) as 10%	Unit	[ ]
11.2	It should treat a decimal tax (e.g., 8.25) as 8.25%	Unit	[ ]
11.3	It should allow tax rates over 100%	Unit	[ ]
11.4	It should calculate total equal to subtotal when tax is zero	Unit	[ ]

---

Test Data Requirements

Entity	Requirements
Users	Authenticated user with access to at least one client
Clients	Multiple clients with complete profiles including address (name, street, city, state, zip)
Form Data	Valid invoice number strings; valid dates in normal-date format; recipient names and addresses
Line Items	Descriptions, quantities (numeric), unit prices (monetary)
Tax Rates	Percentage values (e.g., 10.0 for 10%)
AWS Lambda	Mock genpdf Lambda returning valid S3 URL; mock genpdf Lambda returning error

Existing Tests to Preserve

• test/clj/auto_ap/ssr/outgoing_invoice_test.clj — Outgoing invoice form rendering, submission, and PDF generation

Dependencies

• Datomic (client lookup for typeahead, address data)
• AWS Lambda (genpdf function generates PDF from invoice data)
• AWS S3 (generated PDFs stored at data.prod.app.integreatconsult.com/<path>)
• HTMX (form submission, line item row fetching)
• Alpine.js (line item row removal animation)
• Form cursor (auto-ap.ssr.form-cursor) — field state management, error binding