Skip to main content

FAF High-Level Test Plan

Feature: Fuel Adjustment Factor (FAF)
Reference: TC-001-Fuel-Adjustment-Factor.md | ADR-001-Fuel-Adjustment-Factor.md
Scope: End-to-end testing strategy for FAF implementation

1. Testing Objectives​

Primary Goals​

  • Verify FAF configuration flows correctly from Partner settings to invoices
  • Ensure FAF applies only to non-rental orders across all entry points
  • Confirm historical invoice integrity through immutable FAF snapshots
  • Validate Xero integration maintains accounting consistency

Success Criteria​

  • All order creation paths (admin, web, change-over) handle FAF consistently
  • Invoice generation produces accurate totals with FAF as separate line item
  • No regression in existing order/invoice workflows
  • Admin can configure but cannot override FAF per order (view-only)

2. Test Scenarios by User Journey​

Scenario A: Admin Configuration Flow​

Actor: System Administrator
Goal: Configure FAF as general Partner setting

[Admin Login] → [Bin Hire Page] → [FAF Configuration Card]
                                      ↓
                        [Enable/Disable Toggle]
                                      ↓
                        [Select Type: % or Fixed $]
                                      ↓
                        [Enter FAF Value]
                                      ↓
                        [AJAX Save with Validation]
                                      ↓
                        [SweetAlert2 Confirmation]

Key Test Points:

  • Configuration persists across sessions
  • Type selection changes UI prefix dynamically
  • Validation rejects negative values and non-numeric input
  • Save button state indicates processing

Scenario B: Admin Order Creation with FAF​

Actor: System Administrator
Goal: Create non-rental order with automatic FAF application

[Order Creation Page] → [Fill Order Details (Non-Rental)]
                                   ↓
                        [System Calculates FAF from Partner Config]
                                   ↓
                        [Display FAF: View-Only, No Edit Controls]
                                   ↓
                        [Complete Order → FAF Snapshot Saved]
                                   ↓
                        [Generate Invoice → FAF Line Item Added]

Key Test Points:

  • FAF calculates correctly for percentage and fixed types
  • Rental orders exclude FAF entirely
  • FAF snapshot immutable after order creation
  • Invoice includes FAF as separate line item using OrderInvoiceExtra

Scenario C: Web Order Customer Journey​

Actor: Customer (Self-Service)
Goal: Complete skip bin order with transparent FAF pricing

[Step 1: Select Waste/Bin] → [Step 2: Quote with FAF Info]
                                      ↓
                        [Step 3: Quote Detail with FAF Breakdown]
                                      ↓
                        [Step 4: Customer Form with FAF Line Item]
                                      ↓
                        [Step 5: Submit Order → FAF Saved]
                                      ↓
                        [Step 6: Payment with FAF in Total]

Key Test Points:

  • FAF displayed transparently throughout journey
  • Price calculations accurate at each step
  • FAF snapshot captured on order submission
  • Payment total includes FAF

Scenario D: Change-Over Order Flow​

Actor: System Administrator
Goal: Create change-over order with current FAF config (not inherited)

[Select Original Order] → [Load Current Partner FAF Config]
                                   ↓
                    [NOT Inherited from Original Order Snapshot]
                                   ↓
                    [Recalculate FAF for New Bin/Price]
                                   ↓
                    [Rental Change-Over → No FAF]
                                   ↓
                    [Save New Order with Fresh FAF Snapshot]

Key Test Points:

  • FAF always from current Partner config
  • Rental status determines FAF inclusion
  • New order gets independent FAF snapshot

Scenario E: Order Edit (View-Only Verification)​

Actor: System Administrator
Goal: View existing order FAF without modification capability

[Order Edit Page] → [Load Order with FAF Snapshot]
                             ↓
                    [Display FAF: Read-Only Text]
                             ↓
                    [No Input Fields for FAF]
                             ↓
                    [Edit Other Fields → FAF Unaffected]
                             ↓
                    [Save → Original FAF Preserved]

Key Test Points:

  • FAF displayed as static information
  • No UI controls to modify FAF
  • Order changes do not affect FAF snapshot

Scenario F: Invoice Generation & Distribution​

Actor: System (Automated)
Goal: Generate accurate invoices with FAF line items

[Order Ready for Invoice] → [First Invoice Generation]
                                   ↓
                    [Add FAF via OrderInvoiceExtra (Idempotent)]
                                   ↓
                    [Generate PDF v1, v2]
                                   ↓
                    [Web Invoice View]
                                   ↓
                    [Email Invoice to Customer]
                                   ↓
                    [Xero Sync with FAF Line Item]

Key Test Points:

  • FAF appears consistently across all invoice formats
  • Invoice regeneration does not duplicate FAF (idempotent)
  • Totals include FAF in calculations
  • Xero receives FAF with same AccountCode as main service

3. Data Flow Testing​

Flow 1: Configuration to Order​

partners.has_faf
partners.faf_type     →   OrderController   →   order_details.faf_applied_type
partners.faf_value        (calculation)       order_details.faf_applied_rate
                                                  order_details.faf_total_amount

Verification Points:

  • FAF config correctly queried from default Partner
  • Calculation matches formula (percentage vs fixed)
  • Snapshot fields populated accurately
  • Float values rounded to 2 decimal places

Flow 2: Order to Invoice​

order_details.faf_*   →   InvoiceManagement   →   order_invoice_extras
                              ↓
                    FuelAdjustmentRepository::addFAFToInvoice()
                              ↓
                    [Idempotent Check: updateOrCreate]

Verification Points:

  • FAF only added for non-rental orders
  • OrderInvoiceExtra created with correct naming
  • Invoice totals updated to include FAF
  • No duplicate entries on regeneration

Flow 3: Invoice to Xero​

order_invoice_extras   →   xeroItemNonRental()   →   Xero API LineItem
        (FAF line)                              [AccountCode = $itemXero]

Verification Points:

  • FAF line item includes description with % if applicable
  • Same AccountCode used for FAF and main service
  • Rental orders excluded from Xero FAF sync

4. Risk-Based Testing Matrix​

Risk AreaLikelihoodImpactTest PriorityCoverage
FAF calculation errorsMediumHighP0All order types, both calculation methods
Invoice total mismatchesMediumHighP0All invoice formats, Xero sync
FAF appearing on rental ordersLowHighP0Rental order creation, change-over
Admin able to modify FAFLowHighP0Order edit verification
Duplicate FAF on regenerationLowMediumP1Invoice regeneration idempotency
Database migration issuesLowMediumP1Rollback/re-migration test
UI prefix not switchingLowLowP2JavaScript event handling
Xero AccountCode mismatchLowHighP0Xero payload verification

5. Acceptance Criteria by Feature​

AC-1: Partner Configuration​

  • Admin can enable/disable FAF for a Partner
  • Admin can select percentage or fixed amount type
  • Admin can enter numeric FAF value (decimals allowed)
  • Configuration saves via AJAX with visual feedback
  • Validation prevents negative values
  • UI shows $ or % prefix based on type selection

AC-2: Order Creation (Admin)​

  • Non-rental orders display calculated FAF (view-only)
  • Rental orders do not show FAF
  • FAF snapshot saved to order_details on creation
  • Order total includes FAF amount
  • No FAF edit controls present on order form

AC-3: Web Order Flow​

  • Step 2 (Quote): FAF info message displayed
  • Step 3 (Quote Detail): FAF breakdown visible
  • Step 4 (Customer Form): FAF as separate line item
  • Step 5 (Submit): FAF saved to database
  • Step 6 (Payment): FAF included in total

AC-4: Change-Over Orders​

  • FAF calculated from current Partner config (not inherited)
  • Rental change-overs exclude FAF
  • New order gets independent FAF snapshot
  • Admin view-only, cannot modify FAF

AC-5: Order Edit​

  • Existing FAF displayed as read-only
  • No input fields for FAF modification
  • Saving other fields does not affect FAF snapshot

AC-6: Invoice Generation​

  • FAF appears as separate line item on all invoice formats
  • Line item description includes percentage if applicable
  • Invoice totals include FAF
  • Idempotent creation (no duplicates on regeneration)

AC-7: Email Distribution​

  • First invoice email includes FAF summary
  • Part invoice email includes FAF summary
  • PDF attachment shows FAF line item

AC-8: Xero Integration​

  • FAF line item syncs to Xero
  • Same AccountCode used for FAF and main service
  • Rental orders do not sync FAF line

6. Regression Test Scope​

Must Verify (P0)​

  • Existing orders without FAF continue to calculate totals correctly
  • Existing invoices generate without FAF line items
  • Xero sync works for orders without FAF
  • Rental orders still exclude all FAF logic
  • Admin permissions unchanged

Should Verify (P1)​

  • Performance of order creation with FAF fields added
  • Database query performance with new columns
  • Email template rendering with/without FAF data

Nice to Verify (P2)​

  • UI responsiveness of AJAX save
  • Edge case: very large FAF values
  • Edge case: zero FAF value handling

7. Entry & Exit Criteria​

Entry Criteria​

  • FAF feature code deployed to test environment
  • Database migrations executed
  • Test data prepared (Partners with FAF enabled/disabled)
  • Access to admin panel and web order flow
  • Xero test environment available (if testing Xero sync)

Exit Criteria​

  • All P0 test scenarios passed
  • No critical or high defects open
  • Regression tests passed for core order/invoice flows
  • Performance impact assessed (if any)
  • Sign-off from QA and Product Owner

8. Defect Severity Definitions​

SeverityDefinitionExample
CriticalFeature unusable, data corruption, financial impactFAF calculated on rental orders, invoice totals incorrect
HighMajor feature broken, workaround difficultFAF not saving to database, not appearing on invoices
MediumFeature degraded, workaround availableFAF prefix not switching, minor display issues
LowCosmetic, no functional impactSpacing issues, typo in FAF description

9. Test Environment Requirements​

ComponentRequirement
DatabaseMigration 2026_04_09_041400 and 2026_04_09_041401 applied
Admin AccessUser with bin-hires-update permission
Test PartnersMinimum 4: No FAF, % FAF, Fixed FAF, Edge case values
XeroTest/sandbox Xero organization (for Xero sync tests)
Queue WorkerRunning for email processing
View CacheCleared (php artisan view:clear)

10. Quick Reference: Files to Monitor​

Critical Files (Changes likely to break FAF)​

  • app/Repositories/FuelAdjustmentRepository.php
  • app/Repositories/InvoiceManagement.php
  • app/Http/Controllers/OrderController.php
  • app/Http/Controllers/Admin/OrderSkipBinController.php

UI Files (Changes affect display)​

  • resources/js/components/AdminNewSkipBinOrder.vue
  • resources/js/components/AdminEditOrder.vue
  • resources/js/components/AdminChangeOver.vue
  • resources/views/admin/bin-hire/index.blade.php

Invoice Templates (Changes affect output)​

  • resources/views/document/invoice/first-invoice.blade.php
  • resources/views/document/new-invoice/first-invoice.blade.php
  • resources/views/frontend/invoice/index.blade.php
  • resources/views/mails/invoice/details-skip-bin.blade.php

This high-level test plan provides strategic testing direction. For detailed step-by-step test cases, see TC-001-Fuel-Adjustment-Factor.md