qaa-agent 1.0.0

package/templates/test-inventory.md

@@ -0,0 +1,582 @@
+---
+template_name: test-inventory
+version: "1.0"
+artifact_type: inventory
+produces: TEST_INVENTORY.md
+producer_agent: qa-analyzer
+consumer_agents:
+  - qa-planner
+  - qa-executor
+required_sections:
+  - summary
+  - unit-tests
+  - integration-tests
+  - api-tests
+  - e2e-smoke-tests
+example_domain: shopflow
+---
+
+# TEST_INVENTORY.md Template
+
+**Purpose:** Complete, pyramid-based test case inventory with every test specified to the level of detail needed for automated generation. Every test case has a unique ID, specific target, concrete inputs, and an explicit expected outcome. This inventory is the single source of truth for what tests will be generated.
+
+**Producer:** `qa-analyzer` agent
+**Consumers:** `qa-planner` (reads inventory to create generation plan with task breakdown and file assignments), `qa-executor` (reads individual test cases to write actual test code)
+
+**Input required:** `QA_ANALYSIS.md` must exist before this artifact is produced. The analyzer uses the top 10 unit targets, API targets, risk assessment, and testing pyramid from the analysis to populate this inventory.
+
+---
+
+## Required Sections
+
+### Section 1: Summary
+
+**Description:** High-level overview of the complete test inventory. Provides counts and distributions that downstream agents use to estimate effort and validate completeness.
+
+**Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| total_tests | number | YES | Total number of test cases across all tiers |
+| unit_count | number | YES | Number of unit tests |
+| unit_percent | number | YES | Percentage of total (target: 60-70%) |
+| integration_count | number | YES | Number of integration tests |
+| integration_percent | number | YES | Percentage of total (target: 10-15%) |
+| api_count | number | YES | Number of API tests |
+| api_percent | number | YES | Percentage of total (target: 20-25%) |
+| e2e_count | number | YES | Number of E2E smoke tests |
+| e2e_percent | number | YES | Percentage of total (target: 3-5%) |
+| p0_count | number | YES | Number of P0 (blocks release) tests |
+| p1_count | number | YES | Number of P1 (should fix) tests |
+| p2_count | number | YES | Number of P2 (nice to have) tests |
+| coverage_narrative | string | YES | 2-3 sentence assessment of what this inventory covers and any known gaps |
+
+---
+
+### Section 2: Unit Tests (60-70%)
+
+**Description:** Tests for individual functions, methods, and modules in isolation. Each test case targets a specific function with concrete inputs and an explicit expected outcome. This is the largest tier and covers all business logic, validation, and utility functions.
+
+**Per test case -- ALL fields are MANDATORY:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| test_id | string | YES | Format: `UT-MODULE-NNN` (e.g., `UT-PRICE-001`) |
+| target | string | YES | Format: `file_path:function_name` (e.g., `src/utils/priceCalculator.ts:calculateOrderTotal`) |
+| what_to_validate | string | YES | One-sentence description of the behavior being tested |
+| concrete_inputs | string | YES | Actual values to pass -- NOT "valid data" or "correct input" |
+| mocks_needed | string | YES | List of dependencies to mock, or "None (pure function)" |
+| expected_outcome | string | YES | Exact return value, exact error message, or exact state change |
+| priority | enum | YES | `P0` (blocks release), `P1` (should fix), `P2` (nice to have) |
+
+**CRITICAL ANTI-PATTERN:**
+
+> "Returns correct value" is **NOT** an expected outcome.
+> "Returns 239.47" **IS** an expected outcome.
+>
+> "Handles error correctly" is **NOT** an expected outcome.
+> "Throws InvalidTransitionError with message 'Cannot transition from delivered to pending'" **IS** an expected outcome.
+>
+> Every expected outcome must contain a **concrete value, specific error, or measurable state change**.
+
+---
+
+### Section 3: Integration/Contract Tests (10-15%)
+
+**Description:** Tests verifying that two or more modules interact correctly. These test the contracts between components -- not internal logic (that's unit tests) and not HTTP contracts (that's API tests). Focus on database interactions, service-to-service calls, and cross-module state flows.
+
+**Per test case -- ALL fields are MANDATORY:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| test_id | string | YES | Format: `INT-MODULE-NNN` (e.g., `INT-ORDER-001`) |
+| components_involved | string | YES | Which modules interact (e.g., "orderService + inventoryService + Prisma") |
+| what_to_validate | string | YES | The interaction contract being tested |
+| setup_required | string | YES | Database state, mock services, or seed data needed before the test |
+| expected_outcome | string | YES | Specific behavior when components interact correctly |
+| priority | enum | YES | `P0`, `P1`, or `P2` |
+
+---
+
+### Section 4: API Tests (20-25%)
+
+**Description:** HTTP-level tests verifying request/response contracts for each endpoint. These ensure the API surface area behaves as documented -- correct status codes, response shapes, error formats, and auth enforcement.
+
+**Per test case -- ALL fields are MANDATORY:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| test_id | string | YES | Format: `API-RESOURCE-NNN` (e.g., `API-AUTH-001`) |
+| method_endpoint | string | YES | HTTP method + path (e.g., `POST /api/v1/auth/login`) |
+| request_body | string | YES | Exact JSON payload or "N/A" for GET requests |
+| headers | string | YES | Required headers (e.g., `Authorization: Bearer {token}`) or "None" |
+| expected_status | number | YES | Exact HTTP status code (200, 201, 400, 401, 404, etc.) |
+| expected_response | string | YES | Key fields in response body with types or exact values |
+| priority | enum | YES | `P0`, `P1`, or `P2` |
+
+---
+
+### Section 5: E2E Smoke Tests (3-5%)
+
+**Description:** End-to-end tests covering the most critical user journeys. These are the minimum set of tests that MUST pass before any release. Maximum 3-8 tests -- each one a multi-step user flow that exercises the full stack.
+
+**Per test case -- ALL fields are MANDATORY:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| test_id | string | YES | Format: `E2E-FLOW-NNN` (e.g., `E2E-FLOW-001`) |
+| user_journey | string | YES | Step-by-step description of what the user does |
+| pages_involved | string | YES | List of views/routes the user navigates through |
+| expected_outcome | string | YES | Final state the user observes after completing the journey |
+| priority | enum | YES | Always `P0` -- E2E tests are release-blocking by definition |
+
+---
+
+## Worked Example (ShopFlow E-Commerce API)
+
+> The following is a complete, filled TEST_INVENTORY.md for the ShopFlow e-commerce application. This example demonstrates the expected depth, specificity, and concrete values required in every test case.
+
+### Summary
+
+| Metric | Value |
+|--------|-------|
+| **Total Tests** | 45 |
+| **Unit Tests** | 28 (62%) |
+| **Integration Tests** | 7 (16%) |
+| **API Tests** | 8 (18%) |
+| **E2E Smoke Tests** | 2 (4%) |
+| **P0 (blocks release)** | 15 |
+| **P1 (should fix)** | 20 |
+| **P2 (nice to have)** | 10 |
+
+**Coverage narrative:** This inventory covers all business-critical logic (price calculation, order state machine, payment processing, authentication), the complete API contract surface, key integration points (order-to-inventory, payment-to-order), and the two most critical user journeys (purchase flow and registration). Known gap: admin-only endpoints (product CRUD) are covered at P1 level only -- no E2E test for admin flows since admin UI is out of current scope.
+
+---
+
+### Unit Tests (28 tests -- 62%)
+
+#### Price Calculation Module
+
+##### UT-PRICE-001: Calculate Order Total with Multiple Items
+- **Target:** `src/utils/priceCalculator.ts:calculateOrderTotal`
+- **What to validate:** Correctly sums line items with quantity multiplication
+- **Concrete inputs:** `[{sku: 'WIDGET-001', qty: 3, unitPrice: 29.99}, {sku: 'GADGET-002', qty: 1, unitPrice: 149.50}]`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `239.47` (29.99 * 3 + 149.50)
+- **Priority:** P0
+
+##### UT-PRICE-002: Apply Percentage Discount
+- **Target:** `src/utils/priceCalculator.ts:applyDiscount`
+- **What to validate:** Applies percentage discount correctly and rounds to 2 decimal places
+- **Concrete inputs:** `{subtotal: 239.47, discountCode: 'SAVE10', discountPercent: 10}`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `215.52` (239.47 * 0.90, rounded to 2 decimals)
+- **Priority:** P1
+
+##### UT-PRICE-003: Calculate Tax
+- **Target:** `src/utils/priceCalculator.ts:calculateTax`
+- **What to validate:** Applies state tax rate correctly
+- **Concrete inputs:** `{subtotal: 215.52, state: 'CA', taxRate: 0.0875}`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `18.86` (215.52 * 0.0875, rounded to 2 decimals)
+- **Priority:** P1
+
+##### UT-PRICE-004: Calculate Shipping by Weight
+- **Target:** `src/utils/priceCalculator.ts:calculateShipping`
+- **What to validate:** Returns correct shipping cost based on weight tiers
+- **Concrete inputs:** `{totalWeight: 4.5, shippingMethod: 'standard'}`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `8.99` (standard rate for 2-5 kg tier)
+- **Priority:** P2
+
+##### UT-PRICE-005: Calculate Order Total with Zero Items
+- **Target:** `src/utils/priceCalculator.ts:calculateOrderTotal`
+- **What to validate:** Returns 0 for empty cart
+- **Concrete inputs:** `[]`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `0.00`
+- **Priority:** P1
+
+#### Authentication Module
+
+##### UT-AUTH-001: Hash Password with bcrypt
+- **Target:** `src/services/authService.ts:hashPassword`
+- **What to validate:** Produces a bcrypt hash that validates against the original password
+- **Concrete inputs:** `'SecureP@ss123!'`
+- **Mocks needed:** None
+- **Expected outcome:** `bcrypt.compare('SecureP@ss123!', result)` returns `true`; result starts with `$2b$`
+- **Priority:** P0
+
+##### UT-AUTH-002: Verify Password -- Correct Password
+- **Target:** `src/services/authService.ts:verifyPassword`
+- **What to validate:** Returns true for correct password against stored hash
+- **Concrete inputs:** `{password: 'SecureP@ss123!', hash: '$2b$10$...' (pre-computed valid hash)}`
+- **Mocks needed:** None
+- **Expected outcome:** Returns `true`
+- **Priority:** P0
+
+##### UT-AUTH-003: Verify Password -- Wrong Password
+- **Target:** `src/services/authService.ts:verifyPassword`
+- **What to validate:** Returns false for incorrect password
+- **Concrete inputs:** `{password: 'WrongPassword!', hash: '$2b$10$...' (hash of 'SecureP@ss123!')}`
+- **Mocks needed:** None
+- **Expected outcome:** Returns `false`
+- **Priority:** P0
+
+##### UT-AUTH-004: Generate JWT Token with Correct Claims
+- **Target:** `src/services/authService.ts:generateToken`
+- **What to validate:** Generates a JWT with correct user ID, email, and expiration
+- **Concrete inputs:** `{userId: 'usr_abc123', email: 'test@shopflow.com', role: 'customer'}`
+- **Mocks needed:** Mock `jwt.sign` to capture payload
+- **Expected outcome:** Token payload contains `{sub: 'usr_abc123', email: 'test@shopflow.com', role: 'customer', exp: <now + 15min>}`
+- **Priority:** P0
+
+##### UT-AUTH-005: Reject Expired Token
+- **Target:** `src/services/authService.ts:verifyToken`
+- **What to validate:** Throws error when token has expired
+- **Concrete inputs:** JWT token with `exp` set to 1 hour ago
+- **Mocks needed:** None (use real jwt.verify with expired token)
+- **Expected outcome:** Throws `TokenExpiredError` with message "jwt expired"
+- **Priority:** P0
+
+#### Order Management Module
+
+##### UT-ORDER-001: Transition Order Status -- Valid Transition (pending -> confirmed)
+- **Target:** `src/services/orderService.ts:transitionOrderStatus`
+- **What to validate:** Accepts valid state transition and returns new status
+- **Concrete inputs:** `{orderId: 'ord_123', currentStatus: 'pending', newStatus: 'confirmed'}`
+- **Mocks needed:** Mock Prisma `order.update` to return updated record
+- **Expected outcome:** Returns `{orderId: 'ord_123', status: 'confirmed', updatedAt: <timestamp>}`
+- **Priority:** P0
+
+##### UT-ORDER-002: Transition Order Status -- Invalid Transition (delivered -> pending)
+- **Target:** `src/services/orderService.ts:transitionOrderStatus`
+- **What to validate:** Rejects invalid state transition with descriptive error
+- **Concrete inputs:** `{orderId: 'ord_456', currentStatus: 'delivered', newStatus: 'pending'}`
+- **Mocks needed:** Mock Prisma `order.findUnique` to return order with status 'delivered'
+- **Expected outcome:** Throws `InvalidTransitionError` with message "Cannot transition from delivered to pending"
+- **Priority:** P0
+
+##### UT-ORDER-003: Transition Order Status -- Cancel from Pending
+- **Target:** `src/services/orderService.ts:transitionOrderStatus`
+- **What to validate:** Allows cancellation from pending status
+- **Concrete inputs:** `{orderId: 'ord_789', currentStatus: 'pending', newStatus: 'cancelled'}`
+- **Mocks needed:** Mock Prisma `order.update` to return updated record
+- **Expected outcome:** Returns `{orderId: 'ord_789', status: 'cancelled', updatedAt: <timestamp>}`
+- **Priority:** P0
+
+##### UT-ORDER-004: Transition Order Status -- Cancel from Shipped (should fail)
+- **Target:** `src/services/orderService.ts:transitionOrderStatus`
+- **What to validate:** Rejects cancellation after shipment
+- **Concrete inputs:** `{orderId: 'ord_012', currentStatus: 'shipped', newStatus: 'cancelled'}`
+- **Mocks needed:** Mock Prisma `order.findUnique` to return order with status 'shipped'
+- **Expected outcome:** Throws `InvalidTransitionError` with message "Cannot cancel an order that has been shipped"
+- **Priority:** P1
+
+#### Payment Module
+
+##### UT-PAY-001: Charge Customer -- Success
+- **Target:** `src/services/paymentService.ts:chargeCustomer`
+- **What to validate:** Creates a Stripe charge and returns payment confirmation
+- **Concrete inputs:** `{orderId: 'ord_123', amount: 25846, currency: 'usd', paymentMethodId: 'pm_test_visa'}`
+- **Mocks needed:** Mock `stripe.paymentIntents.create` to return `{id: 'pi_abc', status: 'succeeded', amount: 25846}`
+- **Expected outcome:** Returns `{paymentId: 'pi_abc', status: 'succeeded', amount: 258.46}`
+- **Priority:** P0
+
+##### UT-PAY-002: Charge Customer -- Card Declined
+- **Target:** `src/services/paymentService.ts:chargeCustomer`
+- **What to validate:** Handles Stripe card decline gracefully
+- **Concrete inputs:** `{orderId: 'ord_456', amount: 15000, currency: 'usd', paymentMethodId: 'pm_test_declined'}`
+- **Mocks needed:** Mock `stripe.paymentIntents.create` to throw `StripeCardError` with code 'card_declined'
+- **Expected outcome:** Throws `PaymentFailedError` with message "Card was declined" and does NOT update order status
+- **Priority:** P0
+
+##### UT-PAY-003: Handle Webhook -- Valid Signature
+- **Target:** `src/services/paymentService.ts:handleWebhook`
+- **What to validate:** Processes webhook with valid Stripe signature
+- **Concrete inputs:** `{rawBody: '{"type":"payment_intent.succeeded",...}', signature: 'valid_sig_hash'}`
+- **Mocks needed:** Mock `stripe.webhooks.constructEvent` to return parsed event
+- **Expected outcome:** Returns `{processed: true, eventType: 'payment_intent.succeeded'}`
+- **Priority:** P0
+
+##### UT-PAY-004: Handle Webhook -- Invalid Signature
+- **Target:** `src/services/paymentService.ts:handleWebhook`
+- **What to validate:** Rejects webhook with invalid or missing Stripe signature
+- **Concrete inputs:** `{rawBody: '{"type":"payment_intent.succeeded",...}', signature: 'invalid_sig'}`
+- **Mocks needed:** Mock `stripe.webhooks.constructEvent` to throw `SignatureVerificationError`
+- **Expected outcome:** Throws `WebhookVerificationError` with message "Invalid webhook signature"
+- **Priority:** P0
+
+#### Inventory Module
+
+##### UT-INV-001: Reserve Stock -- Sufficient Inventory
+- **Target:** `src/services/inventoryService.ts:reserveStock`
+- **What to validate:** Decrements available stock when sufficient inventory exists
+- **Concrete inputs:** `{productId: 'prod_001', quantity: 3, currentStock: 10}`
+- **Mocks needed:** Mock Prisma `product.update` to return updated stock
+- **Expected outcome:** Returns `{productId: 'prod_001', reserved: 3, remainingStock: 7}`
+- **Priority:** P0
+
+##### UT-INV-002: Reserve Stock -- Insufficient Inventory
+- **Target:** `src/services/inventoryService.ts:reserveStock`
+- **What to validate:** Rejects reservation when insufficient stock
+- **Concrete inputs:** `{productId: 'prod_002', quantity: 5, currentStock: 2}`
+- **Mocks needed:** Mock Prisma `product.findUnique` to return product with stock 2
+- **Expected outcome:** Throws `InsufficientStockError` with message "Only 2 units available for prod_002, requested 5"
+- **Priority:** P0
+
+##### UT-INV-003: Release Stock on Payment Failure
+- **Target:** `src/services/inventoryService.ts:releaseStock`
+- **What to validate:** Increments available stock when releasing a reservation
+- **Concrete inputs:** `{productId: 'prod_001', quantity: 3, currentStock: 7}`
+- **Mocks needed:** Mock Prisma `product.update` to return updated stock
+- **Expected outcome:** Returns `{productId: 'prod_001', released: 3, availableStock: 10}`
+- **Priority:** P1
+
+#### Validation Module
+
+##### UT-VAL-001: Validate Email -- Valid Format
+- **Target:** `src/utils/validators.ts:validateEmail`
+- **What to validate:** Accepts valid email format
+- **Concrete inputs:** `'user@shopflow.com'`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `true`
+- **Priority:** P1
+
+##### UT-VAL-002: Validate Email -- Invalid Format
+- **Target:** `src/utils/validators.ts:validateEmail`
+- **What to validate:** Rejects invalid email format
+- **Concrete inputs:** `'not-an-email'`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `false`
+- **Priority:** P1
+
+##### UT-VAL-003: Validate Password -- Meets Requirements
+- **Target:** `src/utils/validators.ts:validatePassword`
+- **What to validate:** Accepts password meeting minimum requirements (8+ chars, 1 uppercase, 1 number, 1 special)
+- **Concrete inputs:** `'SecureP@ss123!'`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `{valid: true, errors: []}`
+- **Priority:** P1
+
+##### UT-VAL-004: Validate Password -- Too Short
+- **Target:** `src/utils/validators.ts:validatePassword`
+- **What to validate:** Rejects password under minimum length
+- **Concrete inputs:** `'Ab1!'`
+- **Mocks needed:** None (pure function)
+- **Expected outcome:** Returns `{valid: false, errors: ['Password must be at least 8 characters']}`
+- **Priority:** P1
+
+#### Auth Middleware
+
+##### UT-MID-001: Auth Middleware -- Valid Token
+- **Target:** `src/middleware/authMiddleware.ts:verifyToken`
+- **What to validate:** Attaches decoded user to request when valid token provided
+- **Concrete inputs:** `{headers: {authorization: 'Bearer <valid-jwt>'}, decoded: {sub: 'usr_abc123', email: 'test@shopflow.com'}}`
+- **Mocks needed:** Mock `jwt.verify` to return decoded payload
+- **Expected outcome:** `req.user` is set to `{id: 'usr_abc123', email: 'test@shopflow.com'}`, `next()` is called
+- **Priority:** P0
+
+##### UT-MID-002: Auth Middleware -- Missing Token
+- **Target:** `src/middleware/authMiddleware.ts:verifyToken`
+- **What to validate:** Returns 401 when no Authorization header present
+- **Concrete inputs:** `{headers: {}}`
+- **Mocks needed:** None
+- **Expected outcome:** Response status `401`, body `{error: 'Authentication required'}`
+- **Priority:** P0
+
+---
+
+### Integration Tests (7 tests -- 16%)
+
+##### INT-ORDER-001: Order Creation Reserves Inventory
+- **Components involved:** orderService + inventoryService + Prisma (PostgreSQL)
+- **What to validate:** Creating an order automatically reserves stock for each line item
+- **Setup required:** Seed database with Product (id: 'prod_001', stock: 10) and authenticated User (id: 'usr_001')
+- **Expected outcome:** After `orderService.createOrder({userId: 'usr_001', items: [{productId: 'prod_001', qty: 2}]})`, product stock is decremented to 8 in database, order status is 'pending'
+- **Priority:** P0
+
+##### INT-ORDER-002: Payment Success Updates Order Status
+- **Components involved:** paymentService + orderService + Prisma (PostgreSQL)
+- **What to validate:** Successful payment charge transitions order from pending to confirmed
+- **Setup required:** Seed database with Order (id: 'ord_001', status: 'pending', total: 259.47). Mock Stripe to return successful charge.
+- **Expected outcome:** After `paymentService.chargeCustomer({orderId: 'ord_001', ...})`, order status in database is 'confirmed', payment record exists with status 'succeeded'
+- **Priority:** P0
+
+##### INT-ORDER-003: Payment Failure Releases Inventory
+- **Components involved:** paymentService + inventoryService + orderService + Prisma (PostgreSQL)
+- **What to validate:** Failed payment releases reserved stock and keeps order in pending
+- **Setup required:** Seed database with Order (id: 'ord_002', status: 'pending'), Product (id: 'prod_001', stock: 8, reserved: 2). Mock Stripe to throw card_declined.
+- **Expected outcome:** After payment failure, product stock is restored to 10 in database, order status remains 'pending'
+- **Priority:** P0
+
+##### INT-ORDER-004: Webhook Updates Order After Async Payment
+- **Components involved:** paymentController (webhook handler) + orderService + Prisma (PostgreSQL)
+- **What to validate:** Stripe webhook event triggers order status update
+- **Setup required:** Seed database with Order (id: 'ord_003', status: 'pending'). Construct valid webhook payload with Stripe test signing secret.
+- **Expected outcome:** After webhook delivery with event type 'payment_intent.succeeded', order status in database is 'confirmed'
+- **Priority:** P0
+
+##### INT-AUTH-001: Auth Middleware Blocks Unauthorized Routes
+- **Components involved:** authMiddleware + orderController + Express routing
+- **What to validate:** Protected routes return 401 without valid JWT
+- **Setup required:** Express app with routes mounted, no auth token in request
+- **Expected outcome:** GET /api/v1/orders returns `401 {error: 'Authentication required'}`, POST /api/v1/orders returns `401 {error: 'Authentication required'}`
+- **Priority:** P1
+
+##### INT-AUTH-002: Refresh Token Rotation
+- **Components involved:** authService + authController + Prisma (PostgreSQL)
+- **What to validate:** Refreshing a token invalidates the old refresh token and issues a new pair
+- **Setup required:** Seed database with User and valid refresh token record
+- **Expected outcome:** After POST /api/v1/auth/refresh with old token, response contains new access token and new refresh token, old refresh token is marked invalid in database
+- **Priority:** P1
+
+##### INT-DB-001: Prisma Transaction Rollback on Error
+- **Components involved:** orderService + Prisma (PostgreSQL) transaction
+- **What to validate:** If any step in order creation fails, the entire transaction rolls back
+- **Setup required:** Seed database with Product (stock: 1). Attempt to create order with qty: 2 (should fail on inventory check).
+- **Expected outcome:** No order created in database, product stock unchanged at 1, `InsufficientStockError` thrown
+- **Priority:** P1
+
+---
+
+### API Tests (8 tests -- 18%)
+
+##### API-AUTH-001: Login with Valid Credentials
+- **Method + Endpoint:** `POST /api/v1/auth/login`
+- **Request body:** `{"email": "customer@shopflow.com", "password": "SecureP@ss123!"}`
+- **Headers:** `Content-Type: application/json`
+- **Expected status:** 200
+- **Expected response:** `{token: string (JWT format), refreshToken: string (UUID format), user: {id: string, name: "Test Customer", email: "customer@shopflow.com"}}`
+- **Priority:** P0
+
+##### API-AUTH-002: Login with Invalid Password
+- **Method + Endpoint:** `POST /api/v1/auth/login`
+- **Request body:** `{"email": "customer@shopflow.com", "password": "WrongPassword"}`
+- **Headers:** `Content-Type: application/json`
+- **Expected status:** 401
+- **Expected response:** `{error: "Invalid email or password"}`
+- **Priority:** P0
+
+##### API-AUTH-003: Register New User
+- **Method + Endpoint:** `POST /api/v1/auth/register`
+- **Request body:** `{"name": "New User", "email": "newuser@shopflow.com", "password": "SecureP@ss123!"}`
+- **Headers:** `Content-Type: application/json`
+- **Expected status:** 201
+- **Expected response:** `{id: string (UUID), email: "newuser@shopflow.com", token: string (JWT format)}`
+- **Priority:** P0
+
+##### API-ORDER-001: Create Order with Valid Items
+- **Method + Endpoint:** `POST /api/v1/orders`
+- **Request body:** `{"items": [{"productId": "prod_001", "qty": 2}], "shippingAddress": {"street": "123 Main St", "city": "San Francisco", "state": "CA", "zip": "94102"}}`
+- **Headers:** `Authorization: Bearer {valid_token}`, `Content-Type: application/json`
+- **Expected status:** 201
+- **Expected response:** `{orderId: string (UUID), status: "pending", total: number (> 0), items: [{productId: "prod_001", qty: 2, unitPrice: number}]}`
+- **Priority:** P0
+
+##### API-ORDER-002: Create Order Without Auth Token
+- **Method + Endpoint:** `POST /api/v1/orders`
+- **Request body:** `{"items": [{"productId": "prod_001", "qty": 1}], "shippingAddress": {...}}`
+- **Headers:** None (no Authorization header)
+- **Expected status:** 401
+- **Expected response:** `{error: "Authentication required"}`
+- **Priority:** P0
+
+##### API-ORDER-003: Update Order Status
+- **Method + Endpoint:** `PATCH /api/v1/orders/ord_001/status`
+- **Request body:** `{"status": "confirmed"}`
+- **Headers:** `Authorization: Bearer {valid_token}`, `Content-Type: application/json`
+- **Expected status:** 200
+- **Expected response:** `{orderId: "ord_001", status: "confirmed", updatedAt: string (ISO date)}`
+- **Priority:** P0
+
+##### API-PAY-001: Charge Payment for Order
+- **Method + Endpoint:** `POST /api/v1/payments/charge`
+- **Request body:** `{"orderId": "ord_001", "paymentMethodId": "pm_test_visa"}`
+- **Headers:** `Authorization: Bearer {valid_token}`, `Content-Type: application/json`
+- **Expected status:** 200
+- **Expected response:** `{paymentId: string, status: "succeeded", amount: number (matches order total)}`
+- **Priority:** P0
+
+##### API-PROD-001: List Products with Pagination
+- **Method + Endpoint:** `GET /api/v1/products?page=1&limit=10`
+- **Request body:** N/A
+- **Headers:** None (public endpoint)
+- **Expected status:** 200
+- **Expected response:** `{products: [{id: string, name: string, price: number, sku: string, category: string}], total: number, page: 1}`
+- **Priority:** P1
+
+---
+
+### E2E Smoke Tests (2 tests -- 4%)
+
+##### E2E-FLOW-001: Complete Purchase Flow
+- **User journey:**
+  1. User navigates to homepage (`/`)
+  2. User clicks a product card to view product detail (`/products/:id`)
+  3. User clicks "Add to Cart" button
+  4. User navigates to cart page (`/cart`)
+  5. User verifies item in cart with correct price and quantity
+  6. User clicks "Checkout" button
+  7. User fills checkout form (shipping address + payment card)
+  8. User clicks "Place Order" button
+  9. User sees order confirmation with order ID and "pending" status
+- **Pages involved:** HomePage, ProductDetailPage, CartPage, CheckoutForm, OrderConfirmationPage
+- **Expected outcome:** Order confirmation page displays with a valid order ID (UUID format), status shows "pending", order total matches the product price, and the user can navigate to order history (`/orders`) to see the new order listed
+- **Priority:** P0
+
+##### E2E-FLOW-002: User Registration to First Order
+- **User journey:**
+  1. User navigates to registration page (`/register`)
+  2. User fills registration form (name: "E2E Test User", email: "e2e-test@shopflow.com", password: "SecureP@ss123!")
+  3. User clicks "Create Account" button
+  4. User is redirected to homepage, logged in (sees user name in navbar)
+  5. User adds a product to cart
+  6. User completes checkout flow
+  7. User navigates to order history (`/orders`)
+  8. User sees the new order with correct status
+- **Pages involved:** RegisterPage, HomePage, ProductDetailPage, CartPage, CheckoutForm, OrderConfirmationPage, OrderHistoryPage
+- **Expected outcome:** Order history page shows exactly 1 order with status "pending", the navbar displays "E2E Test User", and the user can log out and log back in successfully
+- **Priority:** P0
+
+---
+
+## Guidelines
+
+### DO
+
+- **DO** use concrete values in every input and expected outcome field -- `239.47`, not "the correct total"
+- **DO** include both happy-path and error cases for each module (at minimum 1 success + 1 failure per function)
+- **DO** specify exact error types and messages in expected outcomes -- `Throws InvalidTransitionError` is better than `Throws an error`
+- **DO** fill in the Mocks field for every test case -- "None (pure function)" is a valid and useful answer
+- **DO** group unit tests by module with clear section headers
+- **DO** ensure test IDs are unique across the entire inventory -- no duplicate `UT-PRICE-001` in different sections
+- **DO** match test targets to the Top 10 Unit Test Targets from `QA_ANALYSIS.md`
+- **DO** include the exact JSON payload for API test request bodies
+
+### DON'T
+
+- **DON'T** write "returns correct data" as an expected outcome -- specify the exact data
+- **DON'T** write "handles error properly" -- specify what "properly" means (status code, error message, state change)
+- **DON'T** skip the Mocks field -- downstream agents need to know what to mock
+- **DON'T** use "valid data" or "correct input" as concrete inputs -- use actual values
+- **DON'T** assign P2 to payment or authentication tests -- those are always P0
+- **DON'T** include more than 8 E2E tests -- if you need more, some should be API or integration tests instead
+- **DON'T** create test IDs that don't follow the naming convention (UT-MODULE-NNN, INT-MODULE-NNN, API-RESOURCE-NNN, E2E-FLOW-NNN)
+
+---
+
+## Quality Gate
+
+Before delivering this artifact, verify all of the following:
+
+- [ ] Every test case has a unique ID following the naming convention
+- [ ] Every test case has an explicit expected outcome with a concrete value (not "works correctly")
+- [ ] Every unit test has all 7 mandatory fields filled (ID, target, what to validate, inputs, mocks, outcome, priority)
+- [ ] Every API test includes exact HTTP method, endpoint, request body, and expected status code
+- [ ] Summary counts match the actual number of test cases in each section
+- [ ] Summary percentages approximately match the testing pyramid (60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E)
+- [ ] Priority is assigned to every test case (P0, P1, or P2)
+- [ ] No expected outcome contains vague words: "correct", "proper", "appropriate", "valid", or "works" without defining what those mean
+- [ ] Test targets reference file paths and function names from `QA_ANALYSIS.md`
+- [ ] Both happy-path and error cases are included for critical modules (auth, payments, orders)