@torus-engineering/tas-kit 1.7.0 → 1.9.0

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

@@ -0,0 +1,130 @@
+---
+created_date:
+executor:
+status: Draft
+story_id:
+feature_id:
+epic_id:
+---
+
+# E2E Mobile Test Specification
+
+**Epic**: [EPIC_LINK]  
+**Feature**: [FEATURE_LINK]  
+**Story**: [STORY_LINK]  
+**Author**: @[executor]  
+**Created**: [created_date]  
+**Status**: [status]
+
+---
+
+## 📋 Test Objective
+> Brief description of what this e2e test suite validates
+
+**Scope**: Mobile only (Detox)  
+**Target Audience**: [Clinical / Organic / Both]
+
+---
+
+## 🧪 Test Cases
+
+Use table format for QA verification:
+
+| ID | Test Type | Test Scenario | Preconditions | Test Data | Test Steps | Expected Result | Priority |
+|---|---|---|---|---|---|---|---|
+| TC_[FEATURE]_001 | Functional | [Scenario Title] | - Precondition 1<br>- Precondition 2 | Key data values | 1. Action 1<br>2. Action 2<br>3. Action 3 | - Expected result 1<br>- Expected result 2 | P0 |
+| TC_[FEATURE]_002 | Validation | [Validation Scenario] | - Precondition | Test data | 1. Action<br>2. Submit | - Validation error<br>- Stay on screen | P0 |
+| TC_[FEATURE]_003 | Error Handling | [Error Scenario] | - Error condition | N/A | 1. Trigger error<br>2. Observe handling | - Error message shown<br>- Recovery option provided | P1 |
+
+**Format Notes**:
+- **ID**: TC_[FEATURE]_###
+- **Test Type**: Functional / Validation / Navigation / Error Handling / Edge Case
+- **Test Scenario**: Brief description (use gerund/action verb)
+- **Preconditions**: Use bullet list with <br> for line breaks
+- **Test Data**: Concrete values or N/A
+- **Test Steps**: Numbered list with <br> separators
+- **Expected Result**: Bullet list with <br> separators
+- **Priority**: P0 (Critical) / P1 (Important) / P2 (Nice-to-have)
+
+---
+
+## 🎯 Test Coverage
+
+| Feature/Screen | Functional | Validation | Error Handling | Edge Cases | Total |
+|---|---|---|---|---|---|
+| [Feature 1] | 2 | 2 | 1 | 1 | 6 |
+| [Feature 2] | 3 | 3 | 2 | 0 | 8 |
+| **TOTAL** | **#** | **#** | **#** | **#** | **##** |
+
+---
+
+## 🔄 Test Environment & Prerequisites
+
+**Device Setup**:
+- [ ] iOS Simulator / Physical Device
+- [ ] Android Emulator / Physical Device
+- [ ] Min OS versions: iOS 14+, Android 9+
+
+**Test Data**:
+- [ ] Mock data fixtures prepared
+- [ ] User accounts ready
+- [ ] External service stubs configured
+
+**Tools**:
+- Detox (v[version])
+- Node/Yarn
+- [Other tools]
+
+---
+
+## ⚠️ Edge Cases & Error Scenarios
+
+| Scenario | Expected Behavior |
+|---|---|
+| Network failure during test | Graceful error handling |
+| [Other edge case] | [Expected behavior] |
+
+---
+
+## 📊 Success Criteria
+
+- [ ] All test cases pass on iOS
+- [ ] All test cases pass on Android
+- [ ] Test execution time < [X] seconds
+- [ ] Zero flaky tests (100% pass rate on 3 consecutive runs)
+- [ ] Code coverage meets [X]%
+
+---
+
+## Implementation Notes
+
+> Any special setup, mocking, or gotchas for implementing these tests
+
+---
+
+## ✅ QA Verification Checklist
+
+- [ ] TC_[FEATURE]_001: [Test scenario] verified on iOS
+- [ ] TC_[FEATURE]_001: [Test scenario] verified on Android
+- [ ] TC_[FEATURE]_002: [Test scenario] verified
+- [ ] All preconditions met before testing
+- [ ] All test data available and valid
+- [ ] All navigation flows working
+- [ ] All error messages displaying
+- [ ] No crashes or unhandled exceptions
+- [ ] Performance acceptable (< X seconds)
+- [ ] Device orientation changes handled
+- [ ] Network conditions tested (if applicable)
+
+**QA Sign-off**:
+- [ ] QA Tester: [Name] - Date: ____
+- [ ] QA Lead: [Name] - Date: ____
+- [ ] Ready for Production: [ ] Yes [ ] No
+
+---
+
+## Review & Approval
+
+- [ ] QA: [Name/ADO_ID]
+- [ ] Tech Lead: [Name/ADO_ID]
+- [ ] Product: [Name/ADO_ID]

package/.tas/templates/E2E-Report.md

@@ -0,0 +1,174 @@
+---
+created_date:
+executed_date:
+executor:
+status: Draft
+story_id:
+feature_id:
+environment: Local
+---
+
+# E2E Test Execution Report
+
+**Feature**: [FEATURE_NAME]  
+**Test Suite**: [e2e-mobile-test-suite]  
+**Created**: [created_date]  
+**Executed**: [executed_date]  
+**Duration**: [X min Y sec]  
+**Executor**: @[executor]  
+**Environment**: [environment]  
+**Status**: [status]
+
+---
+
+## 📊 Summary
+
+| Metric | Value |
+|---|---|
+| **Total Tests** | [N] |
+| **Passed** ✅ | [N] |
+| **Failed** ❌ | [N] |
+| **Skipped** ⊘ | [N] |
+| **Flaky** ⚠️ | [N] |
+| **Pass Rate** | [X]% |
+| **Execution Time** | [X min Y sec] |
+
+---
+
+## 🎯 Results by Platform
+
+### iOS
+- **Status**: ✅ PASS / ❌ FAIL
+- **Tests Run**: [N]
+- **Pass Rate**: [X]%
+- **Device**: [Simulator / Physical - model]
+- **OS Version**: iOS [version]
+
+### Android
+- **Status**: ✅ PASS / ❌ FAIL
+- **Tests Run**: [N]
+- **Pass Rate**: [X]%
+- **Device**: [Emulator / Physical - model]
+- **OS Version**: Android [version]
+
+---
+
+## ✅ Passed Tests
+
+```
+✓ TC-1: [Test Case Name]
+✓ TC-2: [Test Case Name]
+✓ TC-3: [Test Case Name]
+```
+
+---
+
+## ❌ Failed Tests
+
+### Failed: TC-X [Test Case Name]
+
+**Platform**: iOS / Android  
+**Error Message**:
+```
+[Actual error output]
+```
+
+**Root Cause**: 
+- [Analysis of why it failed]
+
+**Reproduction Steps**:
+1. [Step 1]
+2. [Step 2]
+
+**Action Items**:
+- [ ] Fix issue [JIRA/ADO link]
+- [ ] Update test data
+- [ ] Investigate environment issue
+
+---
+
+## ⚠️ Flaky Tests (Pass/Fail Intermittently)
+
+| Test Case | Flake Rate | Notes |
+|---|---|---|
+| [TC Name] | [X%] | Possible timing issue with [component] |
+
+---
+
+## 🔍 Detailed Logs & Artifacts
+
+**Video Recordings**:
+- [iOS recording link / artifact path]
+- [Android recording link / artifact path]
+
+**Screenshots**:
+- [Failed state screenshots]
+
+**Debug Logs**:
+- [Log file path or link]
+
+**Performance Metrics**:
+- Average screen load time: [X] ms
+- Average gesture response time: [X] ms
+- Memory usage: [X] MB
+- Frame rate (FPS): [X]
+
+---
+
+## 🎓 Test Coverage Analysis
+
+| Screen/Flow | Coverage | Pass/Fail |
+|---|---|---|
+| Authentication Flow | Happy + Error cases | ✅ PASS |
+| [Feature Screen] | [Coverage details] | ✅/❌ |
+
+---
+
+## 🚀 Blockers & Issues
+
+| Issue | Severity | Impact | Owner | ETA |
+|---|---|---|---|---|
+| [Issue description] | Critical / High / Medium | Blocks deployment | @[person] | [date] |
+
+---
+
+## ✅ Recommendations
+
+1. **Immediate Actions** (before merge):
+   - [ ] [Action item]
+
+2. **Follow-up Actions** (post-deployment):
+   - [ ] [Action item]
+   - [ ] Investigate flaky tests in TC-X
+
+3. **Test Maintenance**:
+   - [ ] Update fixtures for API v2
+   - [ ] Add test cases for new scenarios
+
+---
+
+## 📝 Sign-off
+
+- [ ] QA Approved: [Name] — [Date/Time]
+- [ ] Tech Lead Review: [Name] — [Date/Time]
+- [ ] Ready for Deployment: Yes / No
+
+**Comments**:
+> Any additional notes from reviewers
+
+---
+
+## 📎 Appendix: Environment Details
+
+**Detox Version**: [version]  
+**Node Version**: [version]  
+**Yarn Version**: [version]  
+**React Native**: [version]  
+**Device Info**: [Simulator/Emulator specs]  
+**Network**: [Mock / Real / Hybrid]  
+**Time Zone**: [TZ]
+
+---
+
+**Report Generated By**: Claude e2e Mobile Agent  
+**Next Test Run Scheduled**: [Date/Time if recurring]

package/.tas/templates/E2E-Scenario.md

@@ -0,0 +1,180 @@
+---
+created_date:
+updated_date:
+executor:
+status: Draft
+epic_id: # Single epic ID, or "XEPIC" for cross-epic
+scenario_type: # single-epic | cross-epic
+platform: # mobile | web | both
+---
+
+# E2E Scenario: {Scenario Name}
+
+**Epic(s)**: [{Epic_ID}]({link}) {{#if cross-epic}} + [{Epic_ID_2}]({link2}) {{/if}}
+**Scenario Type**: {{scenario_type}} (single-epic | cross-epic)
+**Platform**: {{platform}}
+**Author**: @[executor]
+**Created**: [created_date]
+**Status**: [status] (Draft | Ready | Implemented | Verified)
+
+---
+
+## Scenario Naming Convention
+
+### Single-Epic E2E
+```
+{PROJECT}_E{EPIC}_E2E_{NUMBER}_{MODIFIER}
+```
+Example: `AL_E002_E2E_001_H` - Full auth flow happy path
+
+### Cross-Epic E2E
+```
+{PROJECT}_XEPIC_E2E_{NUMBER}_{MODIFIER}
+```
+Example: `AL_XEPIC_E2E_001_H` - Registration through first scan journey
+
+---
+
+## Flow Overview
+
+> Narrative description of the end-to-end user journey.
+> This scenario tests {what} by simulating {user type} performing {complete flow}.
+
+**User Persona**: {Clinical / Organic / New User / Returning User}
+**Starting Point**: {Screen/Page where flow begins}
+**End Point**: {Screen/Page where flow ends}
+**Estimated Duration**: {X minutes}
+
+---
+
+## Scenario Steps
+
+| Step | Screen/Page | Action | Expected Result | Builds on FT IDs | Priority |
+|------|-------------|--------|-----------------|-------------------|----------|
+| 1 | {Start Screen} | {User action} | {Expected outcome} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H | P0 |
+| 2 | {Next Screen} | {User action} | {Expected outcome} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_H | P0 |
+| 3 | {Next Screen} | {User action} | {Expected outcome} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_003_H | P0 |
+| 4 | {Next Screen} | {User action} | {Expected outcome} | - (new step, no FT reference) | P1 |
+| 5 | {End Screen} | {Verify final state} | {Final expected state} | {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_005_H | P0 |
+
+### Step Details
+
+#### Step 1: {Action Title}
+- **Screen**: {Screen name}
+- **Preconditions**: {What must be true before this step}
+- **Action**: {Detailed user action}
+- **Expected Result**: {What should happen}
+- **FT Reference**: Reuses logic from `{FT_ID}` in `features/{epic}/{feature}/helpers.ts`
+- **Timeout**: {Expected max time for this step}
+
+#### Step 2: {Action Title}
+- **Screen**: {Screen name}
+- **Preconditions**: Step 1 completed successfully
+- **Action**: {Detailed user action}
+- **Expected Result**: {What should happen}
+- **FT Reference**: Reuses logic from `{FT_ID}`
+
+_(Continue for each step)_
+
+---
+
+## Alternate Flows
+
+### Alternate Flow 1: {Description}
+> What happens when {condition} differs from the main flow
+
+| Step | Diverges At | Action | Expected Result |
+|------|-------------|--------|-----------------|
+| 1a | Step {N} | {Alternative action} | {Different outcome} |
+| 1b | Step {N+1} | {Continue} | {Rejoins main flow or ends} |
+
+### Error Flow 1: {Description}
+> What happens when {error condition}
+
+| Step | Diverges At | Error Condition | Expected Recovery |
+|------|-------------|-----------------|-------------------|
+| E1 | Step {N} | {Error trigger} | {Error message + recovery} |
+
+---
+
+## Test Data (per Environment)
+
+| Data Item | Dev | Staging | Prod (Smoke) | Notes |
+|-----------|-----|---------|--------------|-------|
+| User Email | {dev-email} | {stag-email} | {prod-email} | From test-data.{env}.json |
+| User Password | (from .env) | (from .env) | (from .env) | NEVER hardcode |
+| {Entity} ID | {dev-id} | {stag-id} | {prod-id} | Pre-seeded data |
+| Base URL | {dev-url} | {stag-url} | {prod-url} | From test-data.{env}.json |
+
+### Data Files
+- `apps/{platform}/e2e/data/test-data.dev.json`
+- `apps/{platform}/e2e/data/test-data.staging.json`
+- `apps/{platform}/e2e/data/test-data.prod.json`
+
+---
+
+## Prerequisites
+
+- [ ] User account exists in target environment
+- [ ] Required test data seeded (products, allergens, etc.)
+- [ ] Backend services running and accessible
+- [ ] External service stubs/mocks configured (if applicable)
+- [ ] Device/browser configured and ready
+- [ ] Environment variables set (.env)
+
+---
+
+## Success Criteria
+
+- [ ] All main flow steps pass sequentially
+- [ ] All alternate flows pass (if applicable)
+- [ ] No screen transitions take > 3 seconds
+- [ ] No crashes or unhandled exceptions
+- [ ] No memory leaks detected during flow
+- [ ] Flow completes within {X} minutes total
+- [ ] Pass on target platforms:
+  {{#if platform === "mobile"}}
+  - [ ] iOS Simulator
+  - [ ] Android Emulator
+  {{/if}}
+  {{#if platform === "web"}}
+  - [ ] Chromium
+  - [ ] Firefox
+  - [ ] WebKit
+  {{/if}}
+
+---
+
+## Script Generation
+
+> This scenario will be used by `/tas-e2e-mobile` or `/tas-e2e-web` to generate executable scripts.
+
+### Mobile Script Output
+- **File**: `apps/mobile/e2e/flows/{scenario-slug}.e2e.ts`
+- **Reuses**: Helper functions from `apps/mobile/e2e/features/{epic}/{feature}/helpers.ts`
+- **Run**: `yarn e2e:flow:{scenario-slug}`
+
+### Web Script Output
+- **File**: `apps/web/e2e/flows/{scenario-slug}.spec.ts`
+- **Reuses**: Page objects + helpers from `apps/web/e2e/features/{epic}/{feature}/`
+- **Run**: `yarn e2e:flow:{scenario-slug}`
+
+---
+
+## FT Reuse Map
+
+> Maps scenario steps to existing functional test helpers for code reuse
+
+| Step | FT ID | Source File | Helper Function |
+|------|-------|-------------|-----------------|
+| 1 | {FT_ID_1} | `features/{epic}/{feature}/helpers.ts` | `{functionName}()` |
+| 2 | {FT_ID_2} | `features/{epic}/{feature}/helpers.ts` | `{functionName}()` |
+| 3 | - | (new logic) | N/A - write new code |
+
+---
+
+## Changelog
+
+| Date | Changes | Author |
+|------|---------|--------|
+| [created_date] | Initial E2E scenario created | @[executor] |

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