Integration Test & E2E Test Design/Implementation Rules

References

• references/e2e-design.md - E2E test design principles with Playwright (candidate sources, selection criteria, UI Spec mapping)
• references/e2e-environment-prerequisites.md - E2E environment prerequisites (seed data, auth fixtures, environment checklist)

Test Types and Limits

*.int.test.ts

*.e2e.test.ts

Critical User Journey: Features with revenue impact, legal requirements, or daily use by majority of users

Behavior-First Principle

Observability Check (All YES = Include)

Include/Exclude Criteria

Include: Business logic accuracy, data integrity, user-visible features, error handling Exclude: External live connections, performance metrics, implementation details, UI layout

Skeleton Specification

Required Comment Format

Each test MUST include the following annotations.

// AC: "[Acceptance criteria original text]"
// ROI: [0-100] | Business Value: [0-10] | Frequency: [0-10]
// Behavior: [Trigger] -> [Process] -> [Observable Result]
// @category: core-functionality | integration | edge-case | ux | e2e
// @dependency: none | [component name] | full-system
// @complexity: low | medium | high
// @real-dependency: [component name] (optional, when Test Boundaries specify non-mock setup)

Property Annotations

// Property: `[Verification expression]`
// fast-check: fc.property(fc.[arbitrary], (input) => [invariant])

Multi-Step User Journey Definition

A feature qualifies as containing a multi-step user journey when ALL of the following are true:

1. 2+ distinct interaction boundaries are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type:
   • Web: distinct routes/pages
   • Mobile native: distinct screens/views
   • CLI: distinct command invocations or interactive prompts
   • API: distinct API calls forming a transaction (e.g., create → confirm → finalize)
2. State carries across steps — data produced or actions taken in one step affect what the next step accepts or displays
3. The journey has a completion point — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow)

User-Facing vs Service-Internal Journeys

Multi-step journeys are further classified for E2E budget decisions:

Scope of this classification:

• Reserved E2E slot: Only user-facing journeys qualify. Service-internal journeys are excluded from the reserved slot.
• Normal ROI > 50 path: Both user-facing and service-internal journeys compete for the additional E2E slot (up to 1) on ROI merit alone. Classification does not affect this path.
• E2E Gap Check: Only user-facing journeys trigger the gap warning. Service-internal journeys do not.

ROI Calculation

ROI is used to rank candidates within the same test type (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently.

ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
              (range: 0–120)

Higher ROI Score = higher priority within its test type. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores.

ROI Threshold for E2E

E2E tests have high ownership cost (creation, execution, and maintenance are each 3-10× higher than integration tests). To justify creation, an E2E candidate (beyond the must-keep reserved slot) requires ROI Score > 50.

ROI Calculation Examples

Implementation Rules

Property-Based Test Implementation

When Property annotation exists, fast-check library is required:

import fc from 'fast-check'

it('AC2-property: Model name is always gemini-3-pro-image-preview', () => {
  fc.assert(
    fc.property(fc.string(), (prompt) => {
      const result = client.generate(prompt)
      return result.model === 'gemini-3-pro-image-preview'
    })
  )
})

Requirements:

• Write in

  fc.assert(fc.property(...))

  format
• Reflect skeleton's

  // fast-check:

  comment directly in implementation
• When failure case discovered, add as concrete unit test (regression prevention)

Behavior Verification Implementation

Behavior Description Verification Levels:

Pass Criteria: Pass if "observable result" is verified as return value or mock call argument of test target

Verification Item Determination Rules

// Verification items:

// Verification items:

Integration Test Mock Boundaries

Judgment Flow:

1. External API (HTTP communication) -> Mock required
2. Component interaction under test -> Actual required
3. Log output verification needed -> Use verifiable mock (vi.fn())
4. Log output verification not needed -> Actual or ignore

E2E Test Execution Conditions

• Execute only after all components are implemented
• Do not use mocks (

  @dependency: full-system

  )

Review Criteria

Skeleton and Implementation Consistency

Implementation Quality