@torus-engineering/tas-kit 1.14.0 → 2.1.0

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

@@ -1,192 +1,176 @@
-# /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)
+---
+model: sonnet
+---
+
+# /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/features/{CODE}-Feature-*/{CODE}-Feature-*.md` for Features with status `In Development`
+3. Read Feature file to get Feature ID + slug
+
+### Step 2: Check Prerequisites
+1. Check `apps/web/` exists. If not → report:
+   > "Web app doesn't exist. If project only has mobile, use `/tas-functest-mobile`."
+   > STOP, DO NOT create file.
+2. Find `Func-Test-Spec.md` in Feature directory:
+   ```
+   docs/features/{CODE}-Feature-{NNN}-{slug}/Func-Test-Spec.md
+   ```
+3. If missing → report:
+   > "No Func-Test-Spec for this Feature. Run `/tas-functest {Feature-ID}` first."
+4. Read `apps/web/playwright.config.ts` (if exists) for current config
+5. Read `apps/web/e2e/helpers/` for patterns
+
+### Step 3: Aggregate FT Test Cases
+- From Func-Test-Spec, list all FT test cases grouped by AC
+- Pull test data requirements from spec
+
+### Step 4: Generate Test Scripts
+
+**File output**: `apps/web/e2e/features/{feature-slug}/{feature-slug}.func.spec.ts`
+
+**Structure**:
+```typescript
+/**
+ * Functional Tests: {Feature Name}
+ * Feature: {Feature_ID}
+ * Stack: web
+ *
+ * Generated by /tas-functest-web
+ * Spec: docs/features/{feature-dir}/Func-Test-Spec.md
+ */
+
+import { test, expect } from '@playwright/test';
+import { loadTestData, getCredentials } from '../../helpers/data-loader';
+
+const testData = loadTestData();
+
+test.describe('{Feature Name}', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/target-page');
+  });
+
+  // AC Reference: AC-1
+  test.describe('{PROJECT}_F{FEATURE}_AC1_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}_F{FEATURE}_AC1_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 });
+      });
+    }
+  });
+});
+```
+
+### Step 5: Generate Feature Helpers
+`apps/web/e2e/features/{feature-slug}/helpers.ts`:
+```typescript
+import { Page, expect } from '@playwright/test';
+
+export async function {featureSpecificHelper}(page: Page) {
+  // Helper logic extracted from functional tests
+}
+```
+
+### Step 6: Generate/Update Data Loader (if missing)
+```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
+```json
+"functest:web:{feature-slug}": "npx playwright test e2e/features/{feature-slug}"
+```
+
+### Step 8: Generate Index
+`apps/web/e2e/features/{feature-slug}/index.ts`:
+```typescript
+export * from './helpers';
+```
+
+## File Structure Output
+```
+apps/web/e2e/features/
+└── {feature-slug}/
+    ├── {feature-slug}.func.spec.ts
+    ├── helpers.ts
+    └── index.ts
+```
+
+## Selector Strategy (Playwright)
+- **Priority**: `data-testid` → `page.getByTestId('login-submit')`
+- **Text**: `page.getByText('Welcome')`
+- **Role**: `page.getByRole('button', { name: 'Submit' })`
+- **Label**: `page.getByLabel('Email')`
+- DO NOT use traditional CSS selectors unless required
+
+## Cross-Browser
+- 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
+yarn functest:web:{feature-slug}
+npx playwright test e2e/features/{feature-slug}
+npx playwright test --project=firefox e2e/features/{feature-slug}
+npx playwright test --ui e2e/features/{feature-slug}
+```
+
+## 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
+- Tests must work on all viewports