@torus-engineering/tas-kit 1.6.0 → 1.8.0

package/.tas/templates/E2E-Web-Spec.md

@@ -0,0 +1,164 @@
+---
+created_date:
+updated_date:
+executor:
+status: Draft
+epic_id:
+scenario_id:
+---
+
+# E2E Web Test Specification: {Scenario Name}
+
+**Scenario**: [{Scenario_ID}]({SCENARIO_LINK})
+**Epic(s)**: [{Epic_ID}]({Epic_LINK})
+**Author**: @[executor]
+**Created**: [created_date]
+**Status**: [status] (Draft | Ready | Implemented | Verified)
+
+---
+
+## Test Framework
+
+- **Framework**: Playwright
+- **Config**: `apps/web/playwright.config.ts`
+- **Script Location**: `apps/web/e2e/flows/{scenario-slug}.spec.ts`
+- **Run Command**: `yarn e2e:flow:{scenario-slug}`
+
+---
+
+## Browser Matrix
+
+| Browser | Engine | Version | Required |
+|---------|--------|---------|----------|
+| Chrome | Chromium | Latest | Yes |
+| Firefox | Gecko | Latest | Yes |
+| Safari | WebKit | Latest | Yes (via Playwright) |
+| Edge | Chromium | Latest | No (covered by Chromium) |
+
+---
+
+## Viewport Testing
+
+| Viewport | Width | Height | Test Required |
+|----------|-------|--------|---------------|
+| Mobile | 375px | 812px | Yes |
+| Tablet | 768px | 1024px | Yes |
+| Desktop | 1280px | 720px | Yes |
+| Large Desktop | 1920px | 1080px | Optional |
+
+---
+
+## Test Cases
+
+### Main Flow
+
+| Test ID | Step | Page | Action | Expected | Browser | Viewport |
+|---------|------|------|--------|----------|---------|----------|
+| {PROJECT}_E{EPIC}_E2E_001_H | 1 | {Page} | {Action} | {Expected} | All | All |
+| {PROJECT}_E{EPIC}_E2E_001_H | 2 | {Page} | {Action} | {Expected} | All | All |
+
+### Cross-Browser Specific
+
+| Test ID | Browser | Issue | Test Action | Expected |
+|---------|---------|-------|-------------|----------|
+| {ID}_BROWSER_001 | Firefox | {Known issue} | {Action} | {Expected} |
+| {ID}_BROWSER_002 | WebKit | {Known issue} | {Action} | {Expected} |
+
+### Responsive Specific
+
+| Test ID | Viewport | Component | Test Action | Expected |
+|---------|----------|-----------|-------------|----------|
+| {ID}_RESP_001 | Mobile | {Nav menu} | {Hamburger menu test} | {Expected} |
+| {ID}_RESP_002 | Tablet | {Layout} | {Grid layout test} | {Expected} |
+
+---
+
+## Playwright Configuration
+
+```typescript
+// playwright.config.ts additions for this scenario
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  timeout: 30000,
+  retries: 1,
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
+    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
+  ],
+  reporter: [
+    ['html', { outputFolder: 'reports/e2e' }],
+    ['junit', { outputFile: 'reports/e2e-results.xml' }],
+  ],
+});
+```
+
+---
+
+## Selectors Strategy
+
+| Element Type | Selector Pattern | Example |
+|-------------|-----------------|---------|
+| Interactive | `data-testid` | `page.getByTestId('login-submit')` |
+| Text | `getByText` | `page.getByText('Welcome')` |
+| Role | `getByRole` | `page.getByRole('button', { name: 'Submit' })` |
+| Label | `getByLabel` | `page.getByLabel('Email')` |
+
+> Prefer `data-testid` for stability. Use semantic selectors (role, label) for accessibility validation.
+
+---
+
+## Network Handling
+
+| Scenario | Mock/Real | Handler |
+|----------|-----------|---------|
+| API calls | Mock (route intercept) | `page.route('/api/**', handler)` |
+| Auth token | From .env | `process.env.TEST_AUTH_TOKEN` |
+| Slow network | Simulated | `page.route('**', route => setTimeout(() => route.continue(), 3000))` |
+| Offline | Simulated | `context.setOffline(true)` |
+
+---
+
+## Accessibility Checks
+
+- [ ] All interactive elements are keyboard accessible
+- [ ] ARIA labels present on custom components
+- [ ] Color contrast meets WCAG AA
+- [ ] Screen reader navigation works for main flow
+- [ ] Focus management correct during navigation
+
+---
+
+## Performance Budgets
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Page Load (LCP) | < 2.5s | Playwright metrics |
+| Interaction (INP) | < 200ms | Playwright metrics |
+| Layout Shift (CLS) | < 0.1 | Playwright metrics |
+| JS Bundle | < 300KB | Build output |
+
+---
+
+## Success Criteria
+
+- [ ] All test cases pass on Chromium
+- [ ] All test cases pass on Firefox
+- [ ] All test cases pass on WebKit
+- [ ] All viewport tests pass (mobile, tablet, desktop)
+- [ ] No flaky tests (100% pass on 3 runs)
+- [ ] Total execution time < {X} minutes
+- [ ] Accessibility checks pass
+- [ ] Performance budgets met
+
+---
+
+## Changelog
+
+| Date | Changes | Author |
+|------|---------|--------|
+| [created_date] | Initial web E2E spec created | @[executor] |

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/"
+  }
+}
+```