@torus-engineering/tas-kit 1.9.0 → 1.11.1

package/.claude/commands/tas-functest-web.md

@@ -1,192 +1,192 @@
-# /tas-functest-web $ARGUMENTS
-
-Vai tro: SE / QA
-Generate tat ca Playwright automation test scripts cho mot web Feature.
-
-## QUAN TRONG - Layer 2: Web Functional Test Scripts
-- Tao Playwright test scripts tu Func-Test-Spec (markdown)
-- Scripts nam trong `apps/web/e2e/features/`
-- Reusable helpers duoc export de Layer 3 (E2E) tai su dung
-- Data hardcoded trong test, credentials tu .env
-- Cross-viewport testing (mobile, tablet, desktop)
-
-## Hanh dong
-
-### Buoc 1: Xac dinh Feature
-1. $ARGUMENTS la Feature ID hoac file path
-2. Neu khong co: scan `docs/epics/**/Feature-*.md` tim features co status In Progress
-3. Doc Feature file de lay Epic/Feature numbers va danh sach Stories
-
-### Buoc 2: Kiem tra Prerequisites
-1. Kiem tra `apps/web/` ton tai. Neu khong → bao:
-   > "Web app chua ton tai trong project nay. Neu project chi co mobile, dung /tas-functest-mobile."
-   > DUNG LAI, KHONG tao file.
-2. Tim tat ca `Func-Test-*.md` files trong Feature directory:
-   ```
-   docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md
-   ```
-3. Neu khong co Func-Test-Spec nao → bao loi:
-   > "Chua co Func-Test-Spec nao cho Feature nay. Chay /tas-functest {story-ID} truoc."
-4. Doc `apps/web/playwright.config.ts` (neu co) de hieu config hien tai
-5. Doc `apps/web/e2e/helpers/` (neu co) de hieu patterns
-
-### Buoc 3: Aggregate FT Test Cases
-- Tu tat ca Func-Test-Spec files, tong hop danh sach FT test cases
-- Nhom theo Story
-- Lay test data requirements tu moi spec
-
-### Buoc 4: Generate Test Scripts
-Voi MOI Story co Func-Test-Spec:
-
-**File output**: `apps/web/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.spec.ts`
-
-**Structure**:
-```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 }) => {
-    await page.goto('/target-page');
-  });
-
-  // AC Reference: AC-1
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
-    test('should {description from spec}', async ({ page }) => {
-      // Given: {precondition}
-      // When: {action}
-      await page.getByTestId('element-id').click();
-      // Then: {expected}
-      await expect(page.getByTestId('result')).toBeVisible();
-    });
-  });
-
-  // Viewport testing for responsive features
-  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H - Viewports', () => {
-    const viewports = [
-      { width: 375, height: 812, name: 'mobile' },
-      { width: 768, height: 1024, name: 'tablet' },
-      { width: 1280, height: 720, name: 'desktop' },
-    ];
-
-    for (const vp of viewports) {
-      test(`should work on ${vp.name} (${vp.width}x${vp.height})`, async ({ page }) => {
-        await page.setViewportSize({ width: vp.width, height: vp.height });
-        // Test responsive behavior
-      });
-    }
-  });
-});
-```
-
-### Buoc 5: Generate Feature Helpers
-Tao file `apps/web/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
-```typescript
-import { Page, expect } from '@playwright/test';
-
-/**
- * Reusable helpers cho {Feature Name}
- * Duoc tai su dung boi Layer 3 E2E scripts
- */
-
-export async function {featureSpecificHelper}(page: Page) {
-  // Helper logic extracted from functional tests
-}
-```
-
-### Buoc 6: Generate/Update Data Loader (neu chua co)
-Neu `apps/web/e2e/helpers/data-loader.ts` chua ton tai, tao:
-```typescript
-type TestEnv = 'dev' | 'staging' | 'prod';
-
-export function loadTestData(env?: TestEnv) {
-  const targetEnv = env || (process.env.TEST_ENV as TestEnv) || 'dev';
-  return require(`../data/test-data.${targetEnv}.json`);
-}
-
-export function getCredentials(userType = 'default') {
-  const data = loadTestData();
-  const user = data.users[userType] || data.users.default;
-  return {
-    email: user.email,
-    password: process.env.TEST_USER_PASSWORD || '',
-  };
-}
-```
-
-### Buoc 7: Update package.json Script
-Them hoac update script trong `apps/web/package.json`:
-```json
-"functest:web:{feature-slug}": "npx playwright test e2e/features/{epic-slug}/{feature-slug}"
-```
-
-### Buoc 8: Generate Index
-Tao `apps/web/e2e/features/{epic-slug}/{feature-slug}/index.ts`:
-```typescript
-export * from './helpers';
-```
-
-## File Structure Output
-```
-apps/web/e2e/features/
-└── {epic-slug}/
-    └── {feature-slug}/
-        ├── {story-1-slug}.func.spec.ts
-        ├── {story-2-slug}.func.spec.ts
-        ├── helpers.ts
-        └── index.ts
-```
-
-## Selector Strategy (Playwright)
-- **Uu tien**: `data-testid` → `page.getByTestId('login-submit')`
-- **Text content**: `page.getByText('Welcome')`
-- **Role**: `page.getByRole('button', { name: 'Submit' })`
-- **Label**: `page.getByLabel('Email')`
-- KHONG dung CSS selectors truyen thong (`.class`, `#id`) tru khi bat buoc
-
-## Cross-Browser Testing
-- Chromium (bat buoc)
-- Firefox (bat buoc)
-- WebKit (bat buoc)
-- Config trong `playwright.config.ts` projects section
-
-## Test Data Convention
-- **Hardcoded values**: Truc tiep trong test
-- **Credentials**: `getCredentials()` → password tu process.env
-- **Environment data**: `loadTestData()` → tu test-data.{env}.json
-- **KHONG BAO GIO** hardcode passwords/tokens
-
-## Chay Tests
-```bash
-# Chay tat ca func tests cho feature
-yarn functest:web:{feature-slug}
-
-# Chay chi mot story
-npx playwright test e2e/features/{epic}/{feature}/{story}
-
-# Chay voi browser cu the
-npx playwright test --project=firefox e2e/features/{epic}/{feature}
-
-# Chay voi debug UI
-npx playwright test --ui e2e/features/{epic}/{feature}
-```
-
-## Nguyen tac
-- Script PHAI chay duoc ngay tu CLI
-- Moi describe block dung full FT ID
-- Helpers PHAI export de Layer 3 reuse
-- KHONG import tu Layer 3 (flows/)
-- Neu apps/web/ khong ton tai → bao loi graceful, KHONG tao
-- Test phai work tren tat ca viewports (mobile, tablet, desktop)
+# /tas-functest-web $ARGUMENTS
+
+Role: SE / QA
+Generate all Playwright automation test scripts for a web Feature.
+
+## IMPORTANT - Layer 2: Web Functional Test Scripts
+- Create Playwright test scripts from Func-Test-Spec (markdown)
+- Scripts located in `apps/web/e2e/features/`
+- Reusable helpers exported for Layer 3 (E2E) reuse
+- Hardcoded data in tests, credentials from .env
+- Cross-viewport testing (mobile, tablet, desktop)
+
+## Actions
+
+### Step 1: Identify Feature
+1. $ARGUMENTS is Feature ID or file path
+2. If not provided: scan `docs/epics/**/Feature-*.md` for features with status In Progress
+3. Read Feature file to get Epic/Feature numbers and list of Stories
+
+### Step 2: Check Prerequisites
+1. Check `apps/web/` exists. If not → report:
+   > "Web app doesn't exist in this project. If project only has mobile, use /tas-functest-mobile."
+   > STOP, DO NOT create file.
+2. Find all `Func-Test-*.md` files in Feature directory:
+   ```
+   docs/epics/{epic-dir}/{feature-dir}/Func-Test-*.md
+   ```
+3. If no Func-Test-Spec exists → report:
+   > "No Func-Test-Spec for this Feature yet. Run /tas-functest {story-ID} first."
+4. Read `apps/web/playwright.config.ts` (if exists) to understand current config
+5. Read `apps/web/e2e/helpers/` (if exists) to understand patterns
+
+### Step 3: Aggregate FT Test Cases
+- From all Func-Test-Spec files, aggregate list of FT test cases
+- Group by Story
+- Get test data requirements from each spec
+
+### Step 4: Generate Test Scripts
+For EACH Story with Func-Test-Spec:
+
+**File output**: `apps/web/e2e/features/{epic-slug}/{feature-slug}/{story-slug}.func.spec.ts`
+
+**Structure**:
+```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 }) => {
+    await page.goto('/target-page');
+  });
+
+  // AC Reference: AC-1
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H', () => {
+    test('should {description from spec}', async ({ page }) => {
+      // Given: {precondition}
+      // When: {action}
+      await page.getByTestId('element-id').click();
+      // Then: {expected}
+      await expect(page.getByTestId('result')).toBeVisible();
+    });
+  });
+
+  // Viewport testing for responsive features
+  test.describe('{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H - Viewports', () => {
+    const viewports = [
+      { width: 375, height: 812, name: 'mobile' },
+      { width: 768, height: 1024, name: 'tablet' },
+      { width: 1280, height: 720, name: 'desktop' },
+    ];
+
+    for (const vp of viewports) {
+      test(`should work on ${vp.name} (${vp.width}x${vp.height})`, async ({ page }) => {
+        await page.setViewportSize({ width: vp.width, height: vp.height });
+        // Test responsive behavior
+      });
+    }
+  });
+});
+```
+
+### Step 5: Generate Feature Helpers
+Create file `apps/web/e2e/features/{epic-slug}/{feature-slug}/helpers.ts`:
+```typescript
+import { Page, expect } from '@playwright/test';
+
+/**
+ * Reusable helpers for {Feature Name}
+ * Exported for Layer 3 E2E scripts reuse
+ */
+
+export async function {featureSpecificHelper}(page: Page) {
+  // Helper logic extracted from functional tests
+}
+```
+
+### Step 6: Generate/Update Data Loader (if not exists)
+If `apps/web/e2e/helpers/data-loader.ts` doesn't exist, create:
+```typescript
+type TestEnv = 'dev' | 'staging' | 'prod';
+
+export function loadTestData(env?: TestEnv) {
+  const targetEnv = env || (process.env.TEST_ENV as TestEnv) || 'dev';
+  return require(`../data/test-data.${targetEnv}.json`);
+}
+
+export function getCredentials(userType = 'default') {
+  const data = loadTestData();
+  const user = data.users[userType] || data.users.default;
+  return {
+    email: user.email,
+    password: process.env.TEST_USER_PASSWORD || '',
+  };
+}
+```
+
+### Step 7: Update package.json Script
+Add or update script in `apps/web/package.json`:
+```json
+"functest:web:{feature-slug}": "npx playwright test e2e/features/{epic-slug}/{feature-slug}"
+```
+
+### Step 8: Generate Index
+Create `apps/web/e2e/features/{epic-slug}/{feature-slug}/index.ts`:
+```typescript
+export * from './helpers';
+```
+
+## File Structure Output
+```
+apps/web/e2e/features/
+└── {epic-slug}/
+    └── {feature-slug}/
+        ├── {story-1-slug}.func.spec.ts
+        ├── {story-2-slug}.func.spec.ts
+        ├── helpers.ts
+        └── index.ts
+```
+
+## Selector Strategy (Playwright)
+- **Priority**: `data-testid` → `page.getByTestId('login-submit')`
+- **Text content**: `page.getByText('Welcome')`
+- **Role**: `page.getByRole('button', { name: 'Submit' })`
+- **Label**: `page.getByLabel('Email')`
+- DO NOT use traditional CSS selectors (`.class`, `#id`) unless required
+
+## Cross-Browser Testing
+- Chromium (required)
+- Firefox (required)
+- WebKit (required)
+- Config in `playwright.config.ts` projects section
+
+## Test Data Convention
+- **Hardcoded values**: Directly in test
+- **Credentials**: `getCredentials()` → password from process.env
+- **Environment data**: `loadTestData()` → from test-data.{env}.json
+- **NEVER** hardcode passwords/tokens
+
+## Run Tests
+```bash
+# Run all func tests for feature
+yarn functest:web:{feature-slug}
+
+# Run only one story
+npx playwright test e2e/features/{epic}/{feature}/{story}
+
+# Run with specific browser
+npx playwright test --project=firefox e2e/features/{epic}/{feature}
+
+# Run with debug UI
+npx playwright test --ui e2e/features/{epic}/{feature}
+```
+
+## Principles
+- Script MUST be runnable directly from CLI
+- Each describe block uses full FT ID
+- Helpers MUST export for Layer 3 reuse
+- DO NOT import from Layer 3 (flows/)
+- If apps/web/ doesn't exist → graceful error, DO NOT create
+- Tests must work on all viewports (mobile, tablet, desktop)

package/.claude/commands/tas-functest.md

@@ -1,76 +1,76 @@
-# /tas-functest $ARGUMENTS
-
-Vai tro: SE / QA
-Generate Functional Test Specification tu mot User Story, lien ket test cases voi Acceptance Criteria (AC).
-
-## QUAN TRONG - Layer 2: Functional Testing
-- Functional tests (FT) nam giua Unit tests (Layer 1) va E2E tests (Layer 3)
-- FT test tung chuc nang/story rieng le, KHONG test flow lien ket giua nhieu features
-- Moi FT case PHAI reference AC-ID de traceability
-
-## Hanh dong
-
-### Buoc 1: Xac dinh Story
-1. $ARGUMENTS la Story ID hoac file path
-2. Neu khong co $ARGUMENTS: scan `docs/epics/**/Story-*.md` tim stories co status In Progress hoac Committed
-3. Doc Story file de lay:
-   - Tat ca Acceptance Criteria (AC-1, AC-2, ...)
-   - Epic/Feature/Story numbers (tu frontmatter hoac file path)
-   - Platform context (mobile/web/backend)
-4. Doc `root/tas.yaml` de lay project code (vd: "AL")
-
-### Buoc 2: Auto-detect Platform
-Tu Story context, xac dinh platform:
-- **Mobile**: Keywords "screen", "navigation", "React Native", "Detox"; paths `apps/mobile/src/features/*`
-- **Web**: Keywords "browser", "page", "Playwright", "React"; paths `apps/web/*`
-- **Backend**: Keywords "API endpoint", "service", "controller"; paths `src/Torus.*`, `tests/`
-- Neu khong xac dinh duoc: hoi user
-
-### Buoc 3: Generate FT Test Cases
-Doc template tu `.tas/templates/Func-Test-Spec.md`
-
-Naming format:
-```
-{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_{NNN}_{MODIFIER}
-```
-
-Voi moi AC, generate:
-- **BAT BUOC**: 1 Happy path test (H)
-- **NEN CO**: 1 Negative test (N) neu co error scenarios
-- **TUY CHON**: 1 Edge case test (E) neu co boundary conditions
-
-Moi test case PHAI co cot AC-ID trong bang mapping.
-
-### Buoc 4: Generate Test Data Requirements
-- Xac dinh data can thiet cho moi test case
-- Data hardcoded: ghi truc tiep trong scenario
-- Credentials: chi reference `process.env.TEST_USER_PASSWORD`, KHONG hardcode
-- Data per environment: reference `test-data.{env}.json`
-
-### Buoc 5: Output File
-Luu file tai:
-```
-docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
-```
-
-### Buoc 6: Prompting
-Sau khi generate, hoi user:
-- "Co edge case nao can them khong?"
-- "Co negative test scenario nao bi bo sot khong?"
-- "Co test case nao can danh dau P0 Critical khong?"
-- "Test data va fixtures can chuan bi gi them?"
-
-## Traceability Feature
-- Moi FT case gan AC-ID trong cot mapping
-- Khi AC thay doi: grep AC-ID trong Func-Test-*.md de biet FT nao can update
-- Trong test script, moi describe block co comment `// AC Reference: AC-{N}`
-
-## Status Flow
-Draft → Ready → Implemented → Verified
-
-## Nguyen tac
-- KHONG tao test code, chi tao specification (markdown)
-- Test code duoc tao boi `/tas-functest-mobile` hoac `/tas-functest-web`
-- Func-Test-Spec la input cho Layer 2 script generation
-- Moi AC phai co it nhat 1 FT case
-- FT dung type code `FT`, KHONG dung `E2E` hay `UT`
+# /tas-functest $ARGUMENTS
+
+Role: SE / QA
+Generate Functional Test Specification from a User Story, linking test cases to Acceptance Criteria (AC).
+
+## IMPORTANT - Layer 2: Functional Testing
+- Functional tests (FT) sit between Unit tests (Layer 1) and E2E tests (Layer 3)
+- FT tests individual function/story in isolation, DOESN'T test linked flows between multiple features
+- Each FT case MUST reference AC-ID for traceability
+
+## Actions
+
+### Step 1: Identify Story
+1. $ARGUMENTS is Story ID or file path
+2. If no $ARGUMENTS: scan `docs/epics/**/Story-*.md` for stories with status In Progress or Committed
+3. Read Story file to get:
+   - All Acceptance Criteria (AC-1, AC-2, ...)
+   - Epic/Feature/Story numbers (from frontmatter or file path)
+   - Platform context (mobile/web/backend)
+4. Read `root/tas.yaml` to get project code (e.g., "AL")
+
+### Step 2: Auto-detect Platform
+From Story context, determine platform:
+- **Mobile**: Keywords "screen", "navigation", "React Native", "Detox"; paths `apps/mobile/src/features/*`
+- **Web**: Keywords "browser", "page", "Playwright", "React"; paths `apps/web/*`
+- **Backend**: Keywords "API endpoint", "service", "controller"; paths `src/Torus.*`, `tests/`
+- If cannot determine: ask user
+
+### Step 3: Generate FT Test Cases
+Read template from `.tas/templates/Func-Test-Spec.md`
+
+Naming format:
+```
+{PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_{NNN}_{MODIFIER}
+```
+
+For each AC, generate:
+- **REQUIRED**: 1 Happy path test (H)
+- **SHOULD HAVE**: 1 Negative test (N) if error scenarios exist
+- **OPTIONAL**: 1 Edge case test (E) if boundary conditions exist
+
+Each test case MUST have AC-ID column in mapping table.
+
+### Step 4: Generate Test Data Requirements
+- Identify data needed for each test case
+- Hardcoded data: write directly in scenario
+- Credentials: only reference `process.env.TEST_USER_PASSWORD`, DO NOT hardcode
+- Environment-specific data: reference `test-data.{env}.json`
+
+### Step 5: Output File
+Save file at:
+```
+docs/epics/{epic-dir}/{feature-dir}/Func-Test-{story-slug}.md
+```
+
+### Step 6: Prompting
+After generating, ask user:
+- "Any edge cases to add?"
+- "Any negative test scenarios missed?"
+- "Any test cases to mark as P0 Critical?"
+- "What additional test data and fixtures needed?"
+
+## Traceability Feature
+- Each FT case links AC-ID in mapping column
+- When AC changes: grep AC-ID in Func-Test-*.md to know which FTs need update
+- In test script, each describe block has comment `// AC Reference: AC-{N}`
+
+## Status Flow
+Draft → Ready → Implemented → Verified
+
+## Principles
+- DO NOT create test code, only create specification (markdown)
+- Test code created by `/tas-functest-mobile` or `/tas-functest-web`
+- Func-Test-Spec is input for Layer 2 script generation
+- Each AC must have at least 1 FT case
+- FT uses type code `FT`, NOT `E2E` or `UT`

package/.claude/commands/tas-init.md

@@ -1,17 +1,17 @@
-# /tas-init
+# /tas-init
 
-Khởi tạo bộ TAS cho dự án hiện tại.
+Initialize TAS kit for the current project.
 
-## Hành động
-1. Cần context từ root/tas.yaml. Nếu chưa có, copy từ .tas/tas-example.yaml ra root và hỏi user điền thông tin cần thiết.
-2. Tạo cấu trúc thư mục: .tas/templates/, .tas/checklists/, docs/, docs/adr/, docs/epics/, docs/bugs/
-3. Tạo file root/project-status.yaml với trạng thái ban đầu (artifacts, epics, adrs đều rỗng).
-4. Copy các template mặc định vào .tas/templates/ nếu chưa có.
-5. Nếu project type là brownfield và codebase_scan_on_init = true:
-   - Quét codebase hiện tại
-   - Tạo file docs/codebase-overview.md tóm tắt kiến trúc hiện có
-6. Hiển thị trạng thái: project type, team roles, workflow phases đang bật.
+## Actions
+1. Need context from root/tas.yaml. If not exists, copy from .tas/tas-example.yaml to root and ask user to fill required information.
+2. Create directory structure: .tas/templates/, .tas/checklists/, docs/, docs/adr/, docs/epics/, docs/bugs/
+3. Create root/project-status.yaml file with initial state (artifacts, epics, adrs all empty).
+4. Copy default templates to .tas/templates/ if not exist.
+5. If project type is brownfield and codebase_scan_on_init = true:
+   - Scan existing codebase
+   - Create docs/codebase-overview.md summarizing current architecture
+6. Display status: project type, team roles, enabled workflow phases.
 
-## Lưu ý
-- KHÔNG tạo lại file nếu đã tồn tại
-- Hỏi xác nhận trước khi thực hiện
+## Notes
+- DO NOT recreate files if already exist
+- Ask for confirmation before executing