test(OUT-3708): unit + integration tests for invoice.created webhook

[SandipBajracharya]

Summary

• Adds 9 integration tests + 1 unit test pinning the production behavior of the invoice.created webhook handler.
• Mirrors the existing priceCreated/ integration suite shape (testcontainers + module-mocked Copilot/Intuit).
• Fixes a pre-existing flake in expiringSweep.test.ts surfaced by the higher integration-file count.

Linear: OUT-3708

What's covered

Integration (test/integration/quickbooks/invoiceCreated/):

• happyPath — OPEN status, mapped product, new customer (asserts mapped-product path via Description from copilot.getProduct)
• draftSkip — DRAFT gate sits before claim
• idempotency — pre-existing CREATED log blocks second delivery
• invoiceAlreadyExists — getInvoiceByNumber short-circuits at the top of webhookInvoiceCreated, before customer resolution
• qbCreateInvoiceFails — claim row flipped to FAILED with errorMessage
• statusPaidCreatesPayment — PAID branch creates Payment with LinkedTxn linked to the just-created invoice
• oneOffLineItem — line item without productId/priceId routes through the Assembly Service ref
• createNewProductFlagOff — flag-off + unmapped line item falls back to one-off (no qb_product_sync row)
• useCompanyNameFlag — company-only payload + flag-on creates customer with customerType='company'

Unit (test/unit/api/quickbooks/webhook/handleInvoiceCreated.test.ts):

• 5 orchestration branches: parse-failure / DRAFT skip / already-claimed / happy path / service-throws → FAILED log

Side fix

expiringSweep.test.ts was using a per-file vi.mock('@/utils/intuit', …) factory. Under integration's pool:forks + fileParallelism:false + isolate:false config, that mock didn't survive across files once any earlier test transitively loaded the real @/utils/intuit (every webhook test does, via auth.service.ts). With master's 7 integration files this never landed in the bad slot; with this branch's 16, it landed ~50% of the time.

Fix: moved the module mock to test/integration/setup.ts and pinned the singleton on globalThis (Vitest re-evaluates the setupFiles factory more than once per session under these flags — a naive shared mock still produces multiple vi.fn() instances). Verified with 10 consecutive full-suite runs all green. Full rationale in commit 2664c98 and in the inline comment in setup.ts.

Out of scope (separate tickets)

• INVOICE_UPDATED routing (uses the same handler with delayMs)
• absorbedFeeFlag (gates PAYMENT_SUCCEEDED only, not invoice.created)
• Tax math edge cases, fee-paid-by-client line item, sparse-customer-update, excluded-product

Test plan

• CI green (test.yml + lint.yml)
• Local yarn test — 22 files / 101 tests passing (verified 10/10 consecutive runs locally)
• yarn lint:check — clean
• yarn prettier:check — clean
• priceCreated regression — 6/6 still green
• Reviewer to spot-check the globalThis mock pin in test/integration/setup.ts is intelligible

🤖 Generated with Claude Code

[linear-code]

OUT-3708

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
quickbooks-sync	Ready	Preview, Comment	May 19, 2026 8:23am
quickbooks-sync (dev)	Ready	Preview, Comment	May 19, 2026 8:23am

[greptile-apps]

Greptile Summary

Adds comprehensive test coverage (9 integration + 2 unit files) for the invoice.created webhook handler, mirroring the existing priceCreated suite shape. Also fixes a pre-existing intermittent failure in expiringSweep.test.ts by moving the @/utils/intuit module mock to the shared test/integration/setup.ts and pinning its singleton on globalThis to survive multiple factory evaluations under the shared-module-registry Vitest configuration.

• Integration tests cover the full happy path plus 8 edge-case branches: DRAFT skip, idempotency guard, invoice-already-exists short-circuit, QB API failure → FAILED log, PAID branch creates Payment with LinkedTxn, one-off line items, createNewProductFlag: false fallback, and company-name customer type.
• Unit tests pin the orchestration layer of WebhookService.handleWebhookEvent (parse failure, DRAFT skip, claim-already-taken, happy path, service-throws → FAILED) and InvoiceService#resolveAvailableDocNumber (clean slot, suffix walk, exhaustion → Sentry + rethrow).
• Flake fix consolidates the @/utils/intuit mock into setup.ts with a globalThis guard so a single vi.fn() instance is shared across all integration files regardless of how many times Vitest re-evaluates the setup factory.

Confidence Score: 5/5

Safe to merge — all changes are test code and configuration; no production logic is modified.

The PR adds tests and fixes a flake; no production paths are touched. The globalThis singleton for the @/utils/intuit mock is unconventional but well-documented and addresses a real shared-module-registry constraint. All test logic is structurally sound: Once-queue mocks are correctly scoped inside optsFactory, the optsFactory pattern ensures fresh vi.fn() instances per beforeEach, and the idempotency/invoiceAlreadyExists/happyPath branches each target distinct code paths without overlapping DB state.

No files require special attention.

Important Files Changed

Filename	Overview
test/integration/setup.ts	Adds globalThis-singleton pattern for @/utils/intuit mock to prevent flake under shared module registry; well-documented and correct.
test/helpers/mocks.ts	Extends createMockCopilotAPI and createMockIntuitAPI with sensible invoice.created defaults; no issues.
test/helpers/seed.ts	Adds seedQBCustomer and seedQBInvoiceSync helpers with properly-typed base objects and override patterns consistent with existing seeders.
test/helpers/invoiceCreatedTestSetup.ts	setupInvoiceCreatedTest helper correctly mirrors setupPriceCreatedTest; optsFactory pattern ensures fresh vi.fn() instances per beforeEach.
test/integration/quickbooks/invoiceCreated/qboDocNumberCollision.test.ts	Both describe blocks correctly handle Once-queue drain: outer block uses mockResolvedValue (permanent), inner block builds mocks inside optsFactory for fresh queues each beforeEach.
test/integration/quickbooks/invoiceCreated/happyPath.test.ts	Thorough happy-path assertions covering customer creation, invoice DB row, sync log, DocNumber collision pre-flight, and mapped-product Description sourcing from Copilot.
test/integration/quickbooks/refreshTokens/expiringSweep.test.ts	Flake fixed by removing per-file vi.mock and wiring via vi.mocked(Intuit.getInstance) in beforeEach after clearAllMocks; correct approach for shared module registry.
test/integration/quickbooks/invoiceCreated/statusPaidCreatesPayment.test.ts	Correctly asserts Payment creation with LinkedTxn; uses string literal 'paid' instead of InvoiceStatus.PAID enum (minor style inconsistency, not a bug).
test/unit/api/quickbooks/webhook/handleInvoiceCreated.test.ts	Five orchestration branches correctly isolated with vi.fn() mocks hoisted before imports; covers all major control-flow paths.
test/unit/app/api/quickbooks/invoice/invoice.service.docNumber.test.ts	Tests private resolveAvailableDocNumber via type cast with appropriate justification; covers clean slot, suffix walk, and exhaustion-to-Sentry paths.
eslint.config.mjs	Adds no-restricted-imports rule preventing src/ from importing test helpers; good guardrail to enforce test/source boundary.
tsconfig.json	Excludes test/ from root tsconfig; test/ gets its own test/tsconfig.json that extends root, keeping type-check scopes separate.

_{Reviews (2): Last reviewed commit: "test(OUT-3708): rebuild DocNumber-race m..." | Re-trigger Greptile}

[SandipBajracharya]

@greptileai

[priosshrsth]

This pr is a very good start. Well done.