@torus-engineering/tas-kit 1.7.0 → 1.8.0

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

@@ -0,0 +1,187 @@
+---
+created_date:
+updated_date:
+executor:
+status: Draft
+story_id:
+feature_id:
+epic_id:
+platform: # mobile | web | backend
+---
+
+# 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)
+
+---
+
+## Test Case Naming Convention
+
+> Functional Tests dung type code **FT** theo format chuẩn TAS
+
+### Format
+```
+{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_{NUMBER}_{MODIFIER}
+```
+
+### 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
+
+| 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 |
+
+---
+
+## Overview
+
+> Brief description of what this functional test suite validates for the Story
+
+**Scope**: {What user functionality is being tested}
+**Target Users**: {Clinical / Organic / Both}
+
+---
+
+## AC to Functional Test Mapping
+
+> QUAN TRONG: Moi FT case PHAI reference AC-ID de dam bao traceability.
+> Khi AC thay doi, grep theo AC-ID de biet FT nao can update.
+
+| 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 |
+
+### 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
+
+---
+
+## 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}
+
+---
+
+## Test Data Requirements
+
+| 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 |
+
+### 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)
+
+### Credentials
+> NEVER put passwords/tokens in JSON files or test code.
+> Always use `.env` via `process.env`.
+
+---
+
+## 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}}
+
+---
+
+## Traceability
+
+> This section enables impact analysis when requirements change.
+
+### 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
+
+### 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', () => { ... });
+```
+
+---
+
+## Changelog
+
+| Date | Changes | Author |
+|------|---------|--------|
+| [created_date] | Initial functional test spec created | @[executor] |