@torus-engineering/tas-kit 1.13.0 → 2.1.0

package/.tas/templates/Func-Test-Spec.md

@@ -1,187 +1,189 @@
 ---
-created_date:
-updated_date:
-executor:
+created_date: YYYY-MM-DD
+updated_date: YYYY-MM-DD
+executor: ""
+reviewer: ""
 status: Draft
-story_id:
-feature_id:
-epic_id:
-platform: # mobile | web | backend
+story_id: ""
+feature_id: ""
+epic_id: ""
+platform: web
+tags: []
+locator_ref: /docs/NAMING_CONVENTION.md
+ver: 1.0
 ---
 
 # Functional Test Specification: {Story Name}
 
-**Epic**: [{Epic_ID}]({Epic_LINK})
-**Feature**: [{Feature_ID}]({FEATURE_LINK})
-**Story**: [{Story_ID}]({STORY_LINK})
-**Platform**: {{platform}}
-**Author**: @[executor]
-**Created**: [created_date]
-**Status**: [status] (Draft | Ready | Implemented | Verified)
+**Epic**: [{Epic_ID}] | **Feature**: [{Feature_ID}] | **Story**: [{Story_ID}]
+**Author**: @{executor} | **Reviewer**: @{reviewer} | **Status**: {status}
 
 ---
 
-## Test Case Naming Convention
+## 1. Story Context
 
-> Functional Tests use type code **FT** following TAS standard format
+> 📌 Provide a brief summary of the User Story being tested. This helps QC understand **why** these test cases exist.
 
-### Format
-```
-{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_{NUMBER}_{MODIFIER}
-```
+| **Field**         | **Detail**                        |
+| ----------------- | --------------------------------- |
+| **Story Summary** | As a [user], I want to [action] so that [benefit] |
+| **Scope**         | What IS covered in this spec      |
+| **Out of Scope**  | What is NOT covered               |
+| **Dependencies**  | Upstream stories / APIs / mocks   |
+| **Test Strategy** | Manual → Automation               |
 
-### Example
-```
-AL_E002_F002_S001_FT_001_H  - Functional Test Happy path
-AL_E002_F002_S001_FT_002_N  - Functional Test Negative
-AL_E002_F002_S001_FT_003_E  - Functional Test Edge case
-```
+---
 
-### Modifier Codes
+## 2. Environment & Data Configuration
 
-| Code | Modifier | Description |
-|------|----------|-------------|
-| H | Happy | Positive test - success scenario |
-| N | Negative | Negative test - failure scenario |
-| E | Edge | Edge case - boundary conditions |
-| S | Security | Security test |
-| P | Performance | Performance test |
+> 🔗 **NFR Source:** This section is derived from the **Product Requirements Document (PRD) — Non-Functional Requirements** section.
+> All platform targets, environment tiers, and access constraints defined here must align with the PRD NFR.
+> Reference: [PRD – Non-Functional Requirements](/docs/PRD.md#non-functional-requirements)
 
----
+### 2.1 Execution Environment Matrix
 
-## Overview
+> 📌 *Derived from PRD NFR — Platform & Compatibility requirements. Do not add platforms not listed in the PRD.*
 
-> Brief description of what this functional test suite validates for the Story
+| **Platform / View** | **OS Version** | **Browser / Viewport** | **PRD NFR Ref**           |
+| ------------------- | -------------- | ---------------------- | ------------------------- |
+| Desktop Web         | Windows 11     | Chrome latest / 1440px | `NFR-COMPAT-01`           |
+| Desktop Web         | macOS 14       | Safari latest / 1440px | `NFR-COMPAT-02`           |
+| Mobile Web          | iOS 17         | Safari / 390px         | `NFR-COMPAT-03`           |
+| Mobile Web          | Android 14     | Chrome / 390px         | `NFR-COMPAT-04`           |
 
-**Scope**: {What user functionality is being tested}
-**Target Users**: {Clinical / Organic / Both}
+### 2.2 JSON Test Data Configuration
 
----
+> 📌 *Environment tiers derived from PRD NFR — Deployment & Data Isolation requirements.*
 
-## AC to Functional Test Mapping
+| **Environment** | **JSON Data File ID / Path**     | **PRD NFR Ref**   | **Description**                            |
+| --------------- | -------------------------------- | ----------------- | ------------------------------------------ |
+| **TEST**        | `data_test_S{STORY_ID}.json`     | `NFR-ENV-01`      | Internal test data (mock / seeded DB)      |
+| **STAG**        | `data_stag_S{STORY_ID}.json`     | `NFR-ENV-02`      | Integration data for UAT                   |
+| **PROD**        | `data_prod_S{STORY_ID}.json`     | `NFR-ENV-03`      | Production data — Secret, read-only access |
 
-> IMPORTANT: Every FT case MUST reference AC-ID to ensure traceability.
-> When AC changes, grep by AC-ID to know which FTs need update.
+### 2.3 Test Account & Role Matrix
 
-| AC ID | AC Description (Given/When/Then) | FT Test ID | Test Scenario | Modifier | Priority | Status |
-|-------|----------------------------------|------------|---------------|----------|----------|--------|
-| AC-1 | {Given...When...Then...} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H | {Happy path description} | Happy | P0 | Draft |
-| AC-1 | {Given...When...Then...} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N | {Negative scenario} | Negative | P0 | Draft |
-| AC-1 | {Given...When...Then...} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_003_E | {Edge case} | Edge | P1 | Draft |
-| AC-2 | {Given...When...Then...} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_004_H | {Happy path description} | Happy | P0 | Draft |
+> 📌 *Derived from PRD NFR — Security & Access Control requirements.*
 
-### Coverage Requirements
-- Each AC MUST have at minimum **1 Happy path (H)** test
-- Each AC SHOULD have **1 Negative (N)** test if error scenarios exist
-- Each AC MAY have **1 Edge case (E)** test if boundary conditions apply
+| **Role**      | **Username**        | **Access Level** | **PRD NFR Ref**   | **Notes**          | **JSON Data Source** |
+| ------------- | ------------------- | ---------------- | ----------------- | ------------------ | ------------------- |
+| Admin         | `{admin_username}`  | Full             | `NFR-SEC-01`      |                    | `data_{env}_S{STORY_ID}.json#admin` |
+| Standard User | `{standard_username}` | Limited          | `NFR-SEC-02`      |                    | `data_{env}_S{STORY_ID}.json#standard_user` |
+| Guest         | N/A                 | None / Public    | `NFR-SEC-03`      |                    | `data_{env}_S{STORY_ID}.json#guest` |
 
 ---
 
-## Test Scenarios
-
-### FT_001_H: {Title - Happy Path}
-- **AC Reference**: AC-1
-- **Preconditions**:
-  - {List preconditions}
-- **Test Data**:
-  - {Hardcoded values used in test}
-  - {Env-specific: from test-data.{env}.json}
-  - {Credentials: from .env via process.env}
-- **Steps**:
-  1. **Given** {initial state}
-  2. **When** {user action}
-  3. **Then** {expected outcome}
-- **Expected Result**: {Detailed expected behavior}
-
-### FT_002_N: {Title - Negative Scenario}
-- **AC Reference**: AC-1
-- **Preconditions**:
-  - {List preconditions}
-- **Test Data**:
-  - {Invalid/error data}
-- **Steps**:
-  1. **Given** {initial state}
-  2. **When** {user performs invalid action}
-  3. **Then** {expected error handling}
-- **Expected Result**: {Error message, recovery option}
-
-### FT_003_E: {Title - Edge Case}
-- **AC Reference**: AC-1
-- **Preconditions**:
-  - {Boundary condition setup}
-- **Test Data**:
-  - {Boundary values}
-- **Steps**:
-  1. **Given** {boundary state}
-  2. **When** {boundary action}
-  3. **Then** {graceful handling}
-- **Expected Result**: {Handled gracefully without crash}
+## 3. Acceptance Criteria Summary
+
+> 🗒️ List each AC from the User Story. Each AC maps directly to one or more test cases below.
+
+| **AC ID**      | **Acceptance Criteria (Given / When / Then)**                            | **Priority** |
+| -------------- | ------------------------------------------------------------------------ | ------------ |
+| `{USName}-AC01` | Given … / When … / Then …                                               | P1 – Must    |
+| `{USName}-AC02` | Given … / When … / Then …                                               | P2 – Should  |
+| `{USName}-AC03` | Given … / When … / Then …                                               | P3 – Nice    |
 
 ---
 
-## Test Data Requirements
+## 4. Test Cases
+
+> **🎯 Workflow Execution Guide (For QC Team):**
+>
+> * **Step 1 (Manual Testing):** Human QC reads `Logical Steps (Human)` and executes against the build. Fill in `Test Result` after each run.
+> * **Step 2 (Automation Evaluation):** Set `Autoable` to `Yes` when UI/logic is stable and the TC is feasible to automate. Leave as `None` if this TC must always remain manual.
+> * **Step 3 (Agent Handoff):** Use the *QC Agent UI Mapping* command. Agent scans TCs where `Autoable = Yes` and fills in `Execution Locators (Agent)`.
+>
+> **TC ID Format:** `[Epic_ID]-[Feat_ID]-[Story_ID]-[AC_ID]-[###]`
+> **Test Types:** `Happy Path` | `Negative` | `Edge Case` | `Boundary` | `Permission` | `UI/UX` | `Performance` | `Security`
+> **Test Result values:** `—` *(not run)* | `✅ Pass` | `❌ Fail` | `⛔ Blocked` | `N/A`
+> **Priority values:** `🔴 High – P0` | `🟡 Med – P1` | `🟢 Low – P2`
+> **Autoable values:**
+> * `None` — TC is **human-only** (exploratory, visual, subjective). `Test Data` is described **inline** in this column and in `Logical Steps`. `Execution Locators` stays blank permanently.
+> * `Yes` — TC **should be converted** to automation script. `Test Data` references a JSON file: `data_{env}_S{STORY_ID}.json#case_###`. Agent will fill `Execution Locators`.
+
+### 4.1 Happy Path Test Cases
+
+| **TC ID** | **Test Type** | **Description** | **Pre-Condition** | **Logical Steps (Human)** | **Test Data** | **Execution Locators (Agent)** | **Expected Result** | **Test Result** | **Priority** | **Autoable** | **Traceability** |
+| --------- | ------------- | --------------- | ----------------- | ------------------------- | ------------- | ------------------------------ | ------------------- | --------------- | ------------ | ------------ | ---------------- |
+| `E01-F01-US01-AC01-001` | Happy Path | [Automatable — standard flow] | 1. User is logged in<br>2. Page X is loaded | 1. Navigate to …<br>2. Click …<br>3. Verify … | `data_test_S{STORY_ID}.json#case_001` | *Leave blank — Agent fills* | 1. Element Y is visible<br>2. Toast shows "…"<br>3. DB state updated | — | `🔴 High – P0` | `Yes` | `{USName}-AC01` |
+| `E01-F01-US01-AC01-002` | Happy Path | [Human only — visual / exploratory check] | 1. User is logged in | 1. Open page<br>2. Visually verify layout matches Figma design<br>3. Data used: any valid account | `Any valid account — entered manually by QC at runtime` | — | Layout matches Figma spec | — | `🟡 Med – P1` | `None` | `{USName}-AC01` |
+
+### 4.2 Negative / Error Test Cases
+
+| **TC ID** | **Test Type** | **Description** | **Pre-Condition** | **Logical Steps (Human)** | **Test Data** | **Execution Locators (Agent)** | **Expected Result** | **Test Result** | **Priority** | **Autoable** | **Traceability** |
+| --------- | ------------- | --------------- | ----------------- | ------------------------- | ------------- | ------------------------------ | ------------------- | --------------- | ------------ | ------------ | ---------------- |
+| `E01-F01-US01-AC01-003` | Negative | [Automatable — invalid input] | 1. User is logged in | 1. Navigate to …<br>2. Submit empty form | `data_test_S{STORY_ID}.json#case_002` | *Leave blank — Agent fills* | 1. Inline error message shown<br>2. Form not submitted | — | `🟡 Med – P1` | `Yes` | `{USName}-AC01` |
+| `E01-F01-US01-AC01-004` | Negative | [Human only — subjective error UX review] | 1. User is logged in | 1. Trigger error state<br>2. Assess error message clarity and tone<br>3. Data used: any invalid input as judged by QC | `Any invalid input — described and entered by QC during run` | — | Error message is clear, actionable, and matches UX copy spec | — | `🟢 Low – P2` | `None` | `{USName}-AC01` |
+
+### 4.3 Edge Case / Boundary Test Cases
 
-| Data Item | Value | Source | Environment-Specific | Notes |
-|-----------|-------|--------|---------------------|-------|
-| User Email | test@example.com | test-data.{env}.json | Yes | Different per env |
-| User Password | (from .env) | process.env.TEST_USER_PASSWORD | Yes | NEVER hardcode |
-| {Entity} ID | {value} | test-data.{env}.json | Yes | Pre-seeded |
-| {Static Data} | {value} | Hardcoded in test | No | Same all envs |
+| **TC ID** | **Test Type** | **Description** | **Pre-Condition** | **Logical Steps (Human)** | **Test Data** | **Execution Locators (Agent)** | **Expected Result** | **Test Result** | **Priority** | **Autoable** | **Traceability** |
+| --------- | ------------- | --------------- | ----------------- | ------------------------- | ------------- | ------------------------------ | ------------------- | --------------- | ------------ | ------------ | ---------------- |
+| `E01-F01-US01-AC02-001` | Edge Case / Boundary | [Automatable — max length input] | — | 1. Enter 256-char string<br>2. Submit | `data_test_S{STORY_ID}.json#case_003` | *Leave blank — Agent fills* | Field truncated or error shown | — | `🟢 Low – P2` | `Yes` | `{USName}-AC02` |
 
-### Environment Data Files
-- **Dev**: `apps/{platform}/e2e/data/test-data.dev.json`
-- **Staging**: `apps/{platform}/e2e/data/test-data.staging.json`
-- **Prod**: `apps/{platform}/e2e/data/test-data.prod.json` (smoke tests only)
+### 4.4 Permission / Role-Based Test Cases
 
-### Credentials
-> NEVER put passwords/tokens in JSON files or test code.
-> Always use `.env` via `process.env`.
+| **TC ID** | **Test Type** | **Description** | **Pre-Condition** | **Logical Steps (Human)** | **Test Data** | **Execution Locators (Agent)** | **Expected Result** | **Test Result** | **Priority** | **Autoable** | **Traceability** |
+| --------- | ------------- | --------------- | ----------------- | ------------------------- | ------------- | ------------------------------ | ------------------- | --------------------------- | ------------ | ------------ | ---------------- |
+| `E01-F01-US01-AC03-001` | Permission | [Human only — access role verified manually] | User is Guest | 1. Log in as Guest (see Role Matrix §2.3 for credentials)<br>2. Navigate to /protected<br>3. Observe redirect<br>4. Data used: Guest credentials from Role Matrix | `Guest credentials — refer to Role Matrix §2.3; entered manually by QC` | — | Redirected to login page with 401 | — | `🔴 High – P0` | `None` | `{USName}-AC03` |
+
+### 4.5 UI / UX & Responsive Test Cases
+
+| **TC ID** | **Test Type** | **Description** | **Pre-Condition** | **Logical Steps (Human)** | **Test Data** | **Execution Locators (Agent)** | **Expected Result** | **Test Result** | **Priority** | **Autoable** | **Traceability** |
+| --------- | ------------- | --------------- | ----------------- | ------------------------- | ------------- | ------------------------------ | ------------------- | --------------- | ------------ | ------------ | ---------------- |
+| `E01-F01-US01-AC01-005` | UI/UX | [Human only — responsive layout check] | Mobile 390px viewport | 1. Open page on 390px device or emulator<br>2. Scroll through full page<br>3. Check element stacking and tap targets<br>4. No specific input data required | `No data required — visual inspection only` | — | No horizontal scroll; buttons full-width; tap targets ≥ 44px | — | `🟢 Low – P2` | `None` | `{USName}-AC01` |
 
 ---
 
-## Platform-Specific Implementation
-
-{{#if platform === "mobile"}}
-### Mobile (Detox)
-- **Script Location**: `apps/mobile/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.e2e.ts`
-- **Test IDs**: Import from `apps/mobile/e2e/test-ids.ts`
-- **Data Loader**: Import from `apps/mobile/e2e/helpers/data-loader.ts`
-- **Test Helpers**: Import from `apps/mobile/e2e/helpers/test-utils.ts`
-- **Run Command**: `yarn functest:mobile:{feature-slug}`
-{{/if}}
-{{#if platform === "web"}}
-### Web (Playwright)
-- **Script Location**: `apps/web/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.spec.ts`
-- **Selectors**: Use `data-testid` attributes
-- **Data Loader**: Import from `apps/web/e2e/helpers/data-loader.ts`
-- **Test Helpers**: Import from `apps/web/e2e/helpers/test-utils.ts`
-- **Run Command**: `yarn functest:web:{feature-slug}`
-- **Viewports**: Test mobile (375px), tablet (768px), desktop (1280px)
-{{/if}}
+## 5. Non-Functional Test Notes
+
+> ⚡ NFT items are tracked here for visibility. Full NFR specs live in [TEST_ENVIRONMENT_MATRIX.md](/docs/TEST_ENVIRONMENT_MATRIX.md).
+
+| **NFT Area**    | **Criteria**                                          | **Tool / Method**     | **Linked TC or Epic** |
+| --------------- | ----------------------------------------------------- | --------------------- | --------------------- |
+| Performance     | Page load ≤ 2s on 4G / LCP ≤ 2.5s                   | Lighthouse / k6       |                       |
+| Accessibility   | WCAG 2.1 AA – keyboard nav, ARIA labels, contrast     | axe / manual          |                       |
+| Security        | No PII in URL params; XSS inputs sanitized            | Manual / OWASP ZAP    |                       |
+| Localization    | All strings from i18n keys; no hard-coded text        | Manual review         |                       |
 
 ---
 
-## Traceability
+## 6. Requirement Coverage Matrix
+
+| **Requirement ID** | **Acceptance Criteria Summary** | **Covered by TC IDs**                                         | **Status**  |
+| ------------------ | ------------------------------- | ------------------------------------------------------------- | ----------- |
+| `{USName}-AC01`    |                                 | `E01-F01-US01-AC01-001`, `E01-F01-US01-AC01-002`, `…`        | Not Started |
+| `{USName}-AC02`    |                                 | `E01-F01-US01-AC02-001`                                       | Not Started |
+| `{USName}-AC03`    |                                 | `E01-F01-US01-AC03-001`                                       | Not Started |
+
+**Coverage Summary:**
 
-> This section enables impact analysis when requirements change.
+| **Total ACs** | **Covered** | **Not Covered** | **Coverage %** |
+| ------------- | ----------- | --------------- | -------------- |
+| 0             | 0           | 0               | 0%             |
 
-### How to find impacted tests when AC changes:
-1. Note the AC-ID that changed (e.g., AC-1)
-2. Search this document's "AC to Functional Test Mapping" table
-3. All FT Test IDs in rows matching that AC-ID need review
-4. Find corresponding script files using the FT Test ID as describe block name
+**Test Run Summary:**
 
-### Reverse traceability (test to requirement):
-Each test script `describe` block includes the AC-ID in comments:
-```typescript
-// AC Reference: AC-1
-describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => { ... });
-```
+| **Total TCs** | **✅ Pass** | **❌ Fail** | **⛔ Blocked** | **N/A** | **— Not Run** | **Pass Rate** |
+| ------------- | ---------- | ---------- | ------------- | ------- | ------------- | ------------- |
+| 0             | 0          | 0          | 0             | 0       | 0             | 0%            |
 
 ---
 
-## Changelog
+## 7. Risk & Assumption Log
+
+| **ID**  | **Type**       | **Description**                             | **Impact**   | **Mitigation**                   |
+| ------- | -------------- | ------------------------------------------- | ------------ | -------------------------------- |
+| `RSK-01` | Risk          | API not stable during test window           | High         | Use mock server fallback         |
+| `ASM-01` | Assumption    | Feature flag is ON in TEST environment      | Medium       | Confirm with dev before run      |
+
+---
+
+## 8. Change log
+
+> **Note:** Changes are summarized daily (Daily Summary format).
 
-| Date | Changes | Author |
-|------|---------|--------|
-| [created_date] | Initial functional test spec created | @[executor] |
+| **Date**          | **Ver** | **Daily Summary of Changes**                                              | **Author**    |
+| ----------------- | ------- | ------------------------------------------------------------------------- | ------------- |
+| {created_date}    | 1.0     | Initial functional test spec created                                      | @{executor}   |
+| {updated_date}    | 1.0     | Initial functional test spec created                                      | @{executor}   |