Story Test Plan
Purpose
The story test plan translates one bounded technical design into executable verification intent before implementation starts. It maps story acceptance criteria to concrete new or existing tests, names the required setup and data, and gives Build a precise handoff for one story-sized slice.
Example
Show a worked example of this artifact
---
ddx:
id: example.story-test-plan.depositmatch.upload-csv
authoring:
home: repo
depends_on:
- example.user-story.depositmatch.upload-csv
- example.technical-design.depositmatch.upload-csv
- example.test-plan.depositmatch
---
# Story Test Plan: STP-001-upload-csv-files
## Story Reference
**User Story**: [[US-001-upload-csv-files]]
**Technical Design**: [[TD-001-upload-csv-files]]
**Related Solution Design**: [[SD-001-csv-import-column-mapping]]
**Project Test Plan**: [[test-plan]]
## Scope and Objective
**Goal**: Prove that a reviewer can upload one bank CSV and one invoice CSV for
a selected client, create a draft import session, reject invalid file types, and
record source file metadata.
**Blocking Gate**: `pnpm test -- importSessions && pnpm test:e2e -- upload-csv`
**In Scope**
- API-001 success response for a valid two-file upload.
- Problem-details error for non-CSV file upload.
- Draft import-session and import-file metadata persistence.
- React upload flow routing to mapping review after success.
**Out of Scope**
- Column mapping.
- Row-level validation.
- Import confirmation.
- Match suggestion generation.
- Cleanup of abandoned draft sessions.
## Acceptance Criteria Test Mapping
| AC ID | Acceptance Criterion (Given/When/Then) | New or Existing Test(s) to Create or Run | Asserted Behavior (what the test verifies) | AC-ID Citation (`@covers`) | Test Level | File or Command | Setup / Data | Notes |
|-------|----------------------------------------|----------------------------------|---|---|------------|-----------------|--------------|-------|
| US-001-AC1 | Given Maya is viewing Acme Dental, when she uploads one valid bank CSV and one valid invoice CSV, then DepositMatch creates one draft import session for Acme Dental and opens mapping review. | `creates_draft_import_session_for_two_csv_files`, `routes_to_mapping_review_after_success` | Creates draft session for Acme Dental and routes to mapping review after success | `@covers US-001-AC1` | Contract, Integration, E2E | `apps/api/test/routes/importSessions.test.ts`; `apps/web/src/features/import/ImportSessionUpload.test.tsx`; `pnpm test:e2e -- upload-csv` | `fixtures/acme-bank-2026-05-08.csv`, `fixtures/acme-invoices-2026-05-08.csv`, authenticated Maya user, Acme Dental client | Covers API and visible reviewer flow |
| US-001-AC2 | Given Maya is viewing Acme Dental, when she uploads a PDF instead of a CSV for either required file, then DepositMatch rejects the file before parsing and keeps the import session in draft. | `rejects_non_csv_bank_file`, `renders_problem_details_for_invalid_file_type` | Rejects non-CSV with actionable error and leaves session draft | `@covers US-001-AC2` | Contract, UI, E2E | `apps/api/test/routes/importSessions.test.ts`; `apps/web/src/features/import/ImportSessionUpload.test.tsx`; `pnpm test:e2e -- upload-csv` | `fixtures/statement.pdf`, valid invoice CSV | Asserts 415 `unsupported-import-file-type`; live upload-csv E2E also drives the rejection |
| US-001-AC3 | Given Maya has uploaded both required CSV files, when the files are accepted, then the import session records the client, file names, upload time, and source type for each file. | `persists_import_file_metadata`, `does_not_log_raw_csv_rows` | Persists client/file metadata without logging raw financial rows | `@covers US-001-AC3` | Integration, Security | `apps/api/test/services/importUploadService.test.ts`; `pnpm test -- importUploadService` | S3 fake, PostgreSQL test DB, log capture | Verifies metadata and financial-data logging concern |
## Executable Proof
These are planned commands, not observed passing results. At completion, link
normal reports here per the [verification contract](../../../../concerns/verification/practices.md).
Link supplemental manual file-picker observations only if normal reports cannot
capture them. Test source cites the stable criterion, for example
`// @covers US-001-AC2` above `rejects_non_csv_bank_file`.
### Primary Commands
```bash
pnpm test -- importSessions
pnpm test -- importUploadService
pnpm test -- ImportSessionUpload
pnpm test:e2e -- upload-csv
```
### Planned Test Files
- `apps/api/test/routes/importSessions.test.ts`
- `apps/api/test/services/importUploadService.test.ts`
- `apps/web/src/features/import/ImportSessionUpload.test.tsx`
- `apps/web/e2e/upload-csv.spec.ts`
### Coverage Focus
- P0: valid two-file upload, non-CSV rejection, metadata persistence, no raw
financial row logging.
- P1: UI advisory validation for missing second file.
## Data and Setup
| Need | Required For | Source / Strategy |
|------|--------------|-------------------|
| Authenticated Maya user | API, UI, E2E | Test user factory with Acme Dental access |
| Acme Dental client | API, UI, E2E | Client factory seeded before each test |
| Valid bank CSV | Happy path | `fixtures/acme-bank-2026-05-08.csv` |
| Valid invoice CSV | Happy path | `fixtures/acme-invoices-2026-05-08.csv` |
| Invalid PDF | Error path | `fixtures/statement.pdf` |
| S3-compatible fake | Integration | Test storage adapter with failure injection |
| Log capture | Security assertion | Test logger sink scanned for raw CSV values |
## Edge Cases and Failure Modes
- Non-CSV bank file returns 415 and does not create a committed import session.
- Missing invoice file keeps the UI in draft state and does not call mapping
review.
- Storage failure returns 503 and does not commit session metadata.
- Uploaded filenames are stored without local path components.
## Build Handoff
**Implementation Order**
1. Create API contract tests for success, missing file, non-CSV, and storage
failure responses.
2. Create repository/service integration tests for draft-session and file
metadata persistence.
3. Create UI component tests for successful routing and problem-details errors.
4. Create the Playwright upload flow after API/UI tests are green; drive both
successful upload and non-CSV rejection against the running app.
**Constraints**
- API-001 is normative.
- Raw CSV row values must not appear in application logs.
- S3 storage failure must not leave partial database state.
**Done When**
- [ ] Every in-scope acceptance criterion has passing evidence.
- [ ] Named commands and test files exist and run.
- [ ] Out-of-scope mapping and row-validation coverage remains deferred to
later story test plans.
- [ ] The story can fail red before implementation and pass green after
implementation.
## Diagnostic Proof
For the diagnostic adoption slice, create a governing story and Contract before
claiming its tests are ready. Plan a real OTel receiver test of the upload logger
and matching span, plus untraced outcomes and concurrent attempt isolation.
Inject private CSV sentinels into messages and subprocess output and verify no
sink captures them. Test exporter outage and bounded retrieval/rotation. These
are follow-up proof obligations, not executed tests for this upload example.Reference
| Activity | Test — Define how we know it works. Plans, suites, and procedures that bind specs to implementation. |
|---|---|
| Default location | docs/helix/03-test/test-plans/STP-{id}-{name}.md |
| Requires | None |
| Enables | None |
| Informs | Test Suites Implementation Plan |
| Referenced by | Technical Design Implementation Plan |
| Generation prompt | Show the full generation prompt |
| Template | Show the template structure |
Innsigle seal: model-primary by HELIX
The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.
- Composition
- model-primary
- Issuer
- HELIX
helix - Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a(build key)- Signed source
artifact-types/test/story-test-plan.md- Signed
- 2026-11-16T15:52:45Z
- Content digest
sha256:d4511f51…e079d50f
This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.
Raw attestation JSON
{
"payload": {
"innsigle": "1",
"type": "https://innsigle.dev/claim/colophon/v1",
"issued_at": "2026-11-16T15:52:45Z",
"issuer": {
"id": "helix",
"name": "HELIX",
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
},
"subjects": [
{
"uri": "https://documentdrivendx.github.io/helix/artifact-types/test/story-test-plan/",
"digest": {
"alg": "sha256",
"value": "d4511f51a793226d8485c32e8d5be95dfa86ab4e38379744ff39789ce079d50f"
}
}
],
"colophon": {
"schema_version": "1",
"composition": "model-primary",
"ingredients": [
{
"kind": "model",
"name": "Claude",
"role": "draft"
},
{
"kind": "tool",
"name": "sloptimizer",
"role": "rewrite"
},
{
"kind": "human",
"name": "operator",
"role": "structure-edit"
}
],
"notes": null
}
},
"payload_encoding": "json",
"signatures": [
{
"key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
"alg": "ed25519",
"sig": "fLI7W9CApA_X-zZKfxAzOjKhptGf4qKElzLD1vJix1s0X_6sON5HJiQQdaAk3AgpWwXhKzZjf5D_do9LIZw6Bg",
"signed_at": "2026-11-16T15:52:45Z"
}
]
}