@torus-engineering/tas-kit 1.7.0 → 1.9.0

package/.tas/templates/Feature.md

@@ -1,55 +1,55 @@
----
-ado_id:
-ado_type: Feature
-ado_title: "{Title}"
-ado_state: New
-ado_assigned_to:
-ado_created:
-last_ado_sync:
-parent_ado_id:
----
-# Feature-{NNN}: {Title}
-
-> **Status:** New | Pending | In Design | In Progress | Ready for Dev | In Development | Ready To Verify | Verified | Done | Removed
-> **Epic:** Epic-{NNN}
-> **Owner:** {PE name}
-> **Created:** {Date}
-> **Verified Date:** {Date khi status = Verified}
-
-## Description
-{Mô tả chức năng}
-
-## User Stories
-| ID | Story | Priority | Estimate | Status |
-|----|-------|----------|----------|--------|
-| Story-001 | {name} | Must | S | New |
-
-## Acceptance Criteria
-- [ ] AC-1: {criteria}
-- [ ] AC-2: {criteria}
-
-## UI/UX Notes
-{Nếu có, reference đến design-spec.md}
-
-## Technical Notes
-{Nếu có, reference đến SAD/ADR}
-
-## Integration Test Cases
-PE thiết kế khi tạo Feature. SE implement trong code.
-
-| ID | Scenario | Expected Result | Status |
-|----|----------|-----------------|--------|
-| IT-1 | {Mô tả flow liên kết} | {Kết quả mong đợi} | - |
-| IT-2 | {Mô tả flow liên kết} | {Kết quả mong đợi} | - |
-
-## E2E / Acceptance Test Cases
-PE thiết kế khi tạo Feature. PE verify trên Staging ở Phase 2 bằng /tas-verify.
-
-| ID | User Scenario | Steps | Expected Result | Status | Verified Date |
-|----|---------------|-------|-----------------|--------|---------------|
-| E2E-1 | {Scenario} | {Bước thực hiện} | {Kết quả mong đợi} | - | - |
-| E2E-2 | {Scenario} | {Bước thực hiện} | {Kết quả mong đợi} | - | - |
-
-## Changelog
-| Date | Changes | Author |
-|------|---------|--------|
+---
+ado_id:
+ado_type: Feature
+ado_title: "{Title}"
+ado_state: New
+ado_assigned_to:
+ado_created:
+last_ado_sync:
+parent_ado_id:
+---
+# Feature-{NNN}: {Title}
+
+> **Status:** New | Pending | In Design | In Progress | Ready for Dev | In Development | Ready To Verify | Verified | Done | Removed
+> **Epic:** Epic-{NNN}
+> **Owner:** {PE name}
+> **Created:** {Date}
+> **Verified Date:** {Date khi status = Verified}
+
+## Description
+{Mô tả chức năng}
+
+## User Stories
+| ID | Story | Priority | Estimate | Status |
+|----|-------|----------|----------|--------|
+| Story-001 | {name} | Must | S | New |
+
+## Acceptance Criteria
+- [ ] AC-1: {criteria}
+- [ ] AC-2: {criteria}
+
+## UI/UX Notes
+{Nếu có, reference đến design-spec.md}
+
+## Technical Notes
+{Nếu có, reference đến SAD/ADR}
+
+## Integration Test Cases
+PE thiết kế khi tạo Feature. SE implement trong code.
+
+| ID | AC Ref | Scenario | Expected Result | Status |
+|----|--------|----------|-----------------|--------|
+| IT-1 | AC-1 | {Mô tả flow liên kết} | {Kết quả mong đợi} | - |
+| IT-2 | AC-2 | {Mô tả flow liên kết} | {Kết quả mong đợi} | - |
+
+## E2E / Acceptance Test Cases
+PE thiết kế khi tạo Feature. PE verify trên Staging ở Phase 2 bằng /tas-verify.
+
+| ID | AC Ref | User Scenario | Steps | Expected Result | Status | Verified Date |
+|----|--------|---------------|-------|-----------------|--------|---------------|
+| E2E-1 | AC-1 | {Scenario} | {Bước thực hiện} | {Kết quả mong đợi} | - | - |
+| E2E-2 | AC-2 | {Scenario} | {Bước thực hiện} | {Kết quả mong đợi} | - | - |
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

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

@@ -0,0 +1,254 @@
+# Functional Test Script Guide
+
+> This document defines the conventions for generated functional test scripts.
+> Used by `/tas-functest-mobile` and `/tas-functest-web` commands.
+
+---
+
+## File Structure Convention
+
+### Mobile (Detox)
+```
+apps/mobile/e2e/
+├── features/                           # Layer 2: Functional test scripts
+│   ├── {epic-slug}/
+│   │   ├── {feature-slug}/
+│   │   │   ├── {story-slug}.func.e2e.ts   # One file per story
+│   │   │   ├── helpers.ts                  # Feature-specific helpers (reusable by E2E)
+│   │   │   └── index.ts                    # Barrel export
+│   │   └── ...
+│   └── ...
+├── flows/                              # Layer 3: E2E scripts (separate)
+├── data/                               # Test data per environment
+│   ├── test-data.dev.json
+│   ├── test-data.staging.json
+│   └── test-data.prod.json
+├── helpers/                            # Shared helpers
+│   ├── data-loader.ts
+│   └── test-utils.ts
+└── test-ids.ts                         # Centralized test ID registry
+```
+
+### Web (Playwright)
+```
+apps/web/e2e/
+├── features/                           # Layer 2: Functional test scripts
+│   ├── {epic-slug}/
+│   │   ├── {feature-slug}/
+│   │   │   ├── {story-slug}.func.spec.ts   # One file per story
+│   │   │   ├── helpers.ts
+│   │   │   └── index.ts
+│   │   └── ...
+│   └── ...
+├── flows/                              # Layer 3: E2E scripts
+├── data/
+│   ├── test-data.dev.json
+│   ├── test-data.staging.json
+│   └── test-data.prod.json
+├── helpers/
+│   ├── data-loader.ts
+│   └── test-utils.ts
+└── page-objects/                       # Playwright page objects
+```
+
+---
+
+## File Naming Convention
+
+| Layer | Platform | Suffix | Example |
+|-------|----------|--------|---------|
+| Functional | Mobile | `.func.e2e.ts` | `login-form.func.e2e.ts` |
+| Functional | Web | `.func.spec.ts` | `login-form.func.spec.ts` |
+| E2E Flow | Mobile | `.e2e.ts` | `auth-complete-flow.e2e.ts` |
+| E2E Flow | Web | `.spec.ts` | `auth-complete-flow.spec.ts` |
+
+---
+
+## Script Template: Mobile (Detox)
+
+```typescript
+/**
+ * Functional Tests: {Story Name}
+ * Story: {Story_ID}
+ * Feature: {Feature_ID}
+ * Epic: {Epic_ID}
+ * 
+ * Generated by /tas-functest-mobile
+ * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ */
+
+import { device, element, expect, by, waitFor } from 'detox';
+import { TEST_IDS } from '../../test-ids';
+import { loadTestData, getCredentials } from '../../helpers/data-loader';
+import { login, navigateTo } from '../../helpers/test-utils';
+
+const testData = loadTestData();
+
+describe('{Feature Name} - {Story Name}', () => {
+  beforeAll(async () => {
+    await device.launchApp({ newInstance: true });
+    // Setup: login, navigate to target screen, etc.
+  });
+
+  beforeEach(async () => {
+    await device.reloadReactNative();
+  });
+
+  // AC Reference: AC-1
+  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    it('should {happy path description}', async () => {
+      // Given: {precondition}
+      // When: {action}
+      await element(by.id(TEST_IDS.FEATURE.ELEMENT)).tap();
+      // Then: {expected}
+      await expect(element(by.id(TEST_IDS.FEATURE.RESULT))).toBeVisible();
+    });
+  });
+
+  // AC Reference: AC-1
+  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N', () => {
+    it('should {negative scenario description}', async () => {
+      // Given: {precondition}
+      // When: {invalid action}
+      await element(by.id(TEST_IDS.FEATURE.INPUT)).typeText('invalid');
+      await element(by.id(TEST_IDS.FEATURE.SUBMIT)).tap();
+      // Then: {error handling}
+      await expect(element(by.id(TEST_IDS.FEATURE.ERROR))).toBeVisible();
+    });
+  });
+});
+```
+
+---
+
+## Script Template: Web (Playwright)
+
+```typescript
+/**
+ * Functional Tests: {Story Name}
+ * Story: {Story_ID}
+ * Feature: {Feature_ID}
+ * Epic: {Epic_ID}
+ * 
+ * Generated by /tas-functest-web
+ * Spec: docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+ */
+
+import { test, expect } from '@playwright/test';
+import { loadTestData, getCredentials } from '../../helpers/data-loader';
+
+const testData = loadTestData();
+
+test.describe('{Feature Name} - {Story Name}', () => {
+  test.beforeEach(async ({ page }) => {
+    // Setup: login, navigate to target page, etc.
+    await page.goto('/target-page');
+  });
+
+  // AC Reference: AC-1
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    test('should {happy path description}', async ({ page }) => {
+      // Given: {precondition}
+      // When: {action}
+      await page.getByTestId('feature-element').click();
+      // Then: {expected}
+      await expect(page.getByTestId('feature-result')).toBeVisible();
+    });
+
+    // Cross-viewport test
+    for (const viewport of [
+      { width: 375, height: 812, name: 'mobile' },
+      { width: 768, height: 1024, name: 'tablet' },
+      { width: 1280, height: 720, name: 'desktop' },
+    ]) {
+      test(`should work on ${viewport.name}`, async ({ page }) => {
+        await page.setViewportSize({ width: viewport.width, height: viewport.height });
+        // Test responsive behavior
+      });
+    }
+  });
+
+  // AC Reference: AC-1
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N', () => {
+    test('should {negative scenario description}', async ({ page }) => {
+      // Given: {precondition}
+      // When: {invalid action}
+      await page.getByTestId('feature-input').fill('invalid');
+      await page.getByTestId('feature-submit').click();
+      // Then: {error handling}
+      await expect(page.getByTestId('feature-error')).toBeVisible();
+    });
+  });
+});
+```
+
+---
+
+## Data Loading Pattern
+
+```typescript
+// Import data loader
+import { loadTestData, getCredentials } from '../../helpers/data-loader';
+
+// Load environment-specific data (reads TEST_ENV env var)
+const testData = loadTestData();
+// testData.users.default.email -> "e2e-user@yopmail.com" (from JSON)
+
+// Load credentials (passwords from .env, never from JSON)
+const creds = getCredentials();
+// creds.email -> from JSON
+// creds.password -> from process.env.TEST_USER_PASSWORD
+```
+
+---
+
+## describe/it Block Naming Convention
+
+```typescript
+// Top-level: Feature + Story name
+describe('{Feature Name} - {Story Name}', () => {
+  // Mid-level: Full FT ID (enables grep by test ID)
+  describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    // Leaf: Human-readable description
+    it('should {action} when {condition}', async () => { ... });
+  });
+});
+```
+
+---
+
+## Reusable Helpers
+
+Feature-specific helpers should be exported for Layer 3 (E2E) reuse:
+
+```typescript
+// features/{epic}/{feature}/helpers.ts
+export async function fillLoginForm(email: string, password: string) {
+  await element(by.id(TEST_IDS.AUTH.LOGIN.EMAIL_INPUT)).typeText(email);
+  await element(by.id(TEST_IDS.AUTH.LOGIN.PASSWORD_INPUT)).typeText(password);
+  await element(by.id(TEST_IDS.AUTH.LOGIN.SUBMIT_BUTTON)).tap();
+}
+
+export async function verifyLoginSuccess() {
+  await waitFor(element(by.id(TEST_IDS.HOME.SCREEN)))
+    .toBeVisible()
+    .withTimeout(5000);
+}
+```
+
+These helpers are imported by E2E flow scripts in `flows/` to avoid duplication.
+
+---
+
+## package.json Script Convention
+
+```json
+{
+  "scripts": {
+    "functest:mobile:{feature-slug}": "detox test --configuration ios.sim.debug --testPathPattern='features/{epic}/{feature}'",
+    "functest:web:{feature-slug}": "npx playwright test --grep '@{feature-slug}' e2e/features/{epic}/{feature}",
+    "functest:mobile:all": "detox test --configuration ios.sim.debug --testPathPattern='features/'",
+    "functest:web:all": "npx playwright test e2e/features/"
+  }
+}
+```

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] |