Integration and E2E Testing Principles

References

E2E test design: See references/e2e-design.md for UI Spec-driven E2E test candidate selection and browser test architecture. The reference uses Playwright as the default browser harness; substitute the project's standard when different.

Test Type Definition and Limits

Lane selection (E2E only):

• Default lane for user-facing UI journeys is fixture-e2e — it runs a real browser against deterministic fixtures, catches the bugs that unit/integration tests miss (button no-op, state never updates, navigation breaks), and runs in CI without infrastructure setup
• Add service-integration-e2e only when the journey's correctness depends on real cross-service behavior (data persistence, transactional consistency, external service contracts) that cannot be faked safely

The two E2E lanes are budgeted independently — having a fixture-e2e for a journey does not consume the service-integration-e2e budget and vice versa.

Behavior-First Principle

Include (High ROI)

• Business logic correctness (calculations, state transitions, data transformations)
• Data integrity and persistence behavior
• User-visible functionality completeness
• Error handling behavior (what user sees/experiences)

Redirect to Other Test Types

• External service connections → Verify via contract/interface tests
• Performance metrics → Verify via dedicated load testing
• Implementation details → Verify observable behavior instead
• UI layout specifics → Verify information availability instead

Principle: Test = User-observable behavior verifiable in isolated CI environment

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 Thresholds by Lane

The two E2E lanes have very different ownership costs and use independent thresholds.

Reserved slot rules (see Multi-Step User Journey Definition below) apply per lane and override the threshold (the reserved candidate is emitted regardless of its ROI score). Below-floor candidates beyond the reserved slot are not emitted, leaving budget intentionally unfilled rather than padding with low-value tests.

ROI Calculation Examples

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 classified for reserved-slot eligibility:

This classification applies only to the reserved-slot rule and the E2E Gap Check. Other selection follows lane-specific ROI rules above.

Use this definition when evaluating E2E test candidates and E2E gap detection.

Test Skeleton Specification

Required Comment Patterns

Each test MUST include the following annotations:

AC: [Original acceptance criteria text]
Behavior: [Trigger] → [Process] → [Observable Result]
@category: core-functionality | integration | edge-case | fixture-e2e | service-integration-e2e
@lane: integration | fixture-e2e | service-integration-e2e
@dependency: none | [component names] | full-system
@complexity: low | medium | high
ROI: [score]

@lane selection rule:

• integration — Component interaction in-process, no browser (e.g., RTL+MSW for React/TS, in-process module/handler integration in any language)
• fixture-e2e — Browser-level UI verification with mocked backend / fixture-driven state
• service-integration-e2e — Browser-level or end-to-end verification against running local services or stubs

Use the project's comment syntax to wrap these annotations (e.g., // for C-family, # for Python/Ruby/Shell).

Verification Items (Optional)

When verification points need explicit enumeration:

Verification items:
- [Item 1]
- [Item 2]

EARS Format Mapping

Test File Naming Convention

• Integration tests: *.int.test.* or *.integration.test.*
• fixture-e2e tests: *.fixture.e2e.test.* (or organize under tests/e2e/fixture/)
• service-integration-e2e tests: *.service.e2e.test.* (or organize under tests/e2e/service/)

The test runner or framework in the project determines the appropriate file extension. Repos that already use a single *.e2e.test.* convention may keep it as long as each file declares @lane: in its header — the lane annotation is the source of truth for routing and budget accounting.

Review Criteria

Skeleton and Implementation Consistency

Implementation Quality

Quality Standards

Required

• Each test verifies one behavior
• Clear AAA (Arrange-Act-Assert) structure
• No test interdependencies
• Deterministic execution