Testing Strategy¶

Rule of Thumb¶

1. Pure decisions and formatting logic → unit tests
2. Workflow and API behaviour → integration tests
3. User-critical happy paths → browser tests
4. Do not add browser tests for implementation details
5. Every core workflow change should update at least one existing test layer

Test Layers¶

Unit Tests¶

Use when the code is pure or nearly pure, does not need a running app, and has branching logic easy to regress.

Good examples: - src/lib/analysis/commercial-readiness.test.ts - src/lib/proposal-sharing.test.ts - src/components/workbench/proposal-editor-utils.test.ts - src/components/workbench/proposal-management-utils.test.ts - src/components/workbench/proposal-share-controls.test.ts - src/components/workbench/proposal-workbench-helpers.test.ts

Use for: scoring, ranking, status transitions in helpers, formatting/label/derived summaries, tab-agnostic calculations.

Don't use for: route auth behaviour, database-backed lifecycle flows, browser interaction sequences.

Integration Tests¶

Use when the behaviour spans route handlers, auth/role checks, Prisma/database state, or multi-step business workflows.

Primary example: scripts/integration-test.mjs

Current coverage: proposal creation, version saves, readiness/approval, publish/revoke sharing, export flow, discovery idempotency isolation, demo route gating.

Use for: route/service contracts, lifecycle state changes, export/download behaviour, token-gated public access, multi-tenant correctness.

Don't use for: icon/text rendering, layout-only UI, micro-interactions.

Browser Tests¶

Use for narrow, high-value journeys where the actual UI matters.

Examples: - scripts/workbench-ui-test.mjs - scripts/public-share-ui-test.mjs

Use for: workbench smoke flow, public share portal behaviour, critical navigation that can break even when APIs are fine.

Keep browser tests: short, deterministic, focused on visible user outcomes.

Don't use for: every button, deep matrix coverage, internal component implementation details.

How to Choose a Test¶

Minimum Expectation for Core Workflow Changes¶

Changes to these flows should update tests: - Create proposal - Revise in workbench - Collaborate/review/approve - Publish/revoke public share - Export proposal

Anti-Patterns¶

• Adding browser tests when a unit test would prove the logic
• Adding unit tests for code that is mostly fetch/auth/database wiring
• Duplicating the same assertion in unit, integration, and browser layers
• Writing tests that depend on unstable copy unless the copy itself is the point

Core Workflow Coverage Matrix¶

1. Create Proposal¶

• Integration: scripts/integration-test.mjs — auth failure, role failure, successful create
• Browser: scripts/workbench-ui-test.mjs — creates proposal and opens workbench
• Gap: no dedicated browser check for proposal creation form UX

2. Draft and Revise in Workbench¶

• Unit: editor-utils, share-controls, management-utils, bom-panel, canvas-panel
• Integration: saves versions, checks diff and readiness paths
• Browser: validates workbench load, document mode, major tab navigation
• Gap: no browser coverage for AI sidekick or diff-review acceptance flow

3. Collaborate, Review, Approve¶

• Unit: commercial-readiness.test.ts, proposal-sharing.test.ts
• Integration: comments, resolution, section reviews, readiness, approval gate
• Browser: collaboration tab render only
• Gap: no browser assertion for adding a comment or changing review state

4. Publish or Revoke Public Share¶

• Unit: proposal-sharing.test.ts, proposal-share-controls.test.ts
• Integration: publish, token access, revoke, access removed
• Browser: none yet
• Gap: missing browser path for public share portal

5. Export Proposal¶

• Unit: limited direct coverage
• Integration: lifecycle/export status covered indirectly
• Browser: none yet
• Gap: export UX and file-delivery need dedicated coverage

Immediate Coverage Priorities¶

1. Add browser test for public share portal
2. Add stronger export-flow coverage
3. Add one browser interaction for comment/review behaviour if collaboration becomes high-change area