@torus-engineering/tas-kit 1.13.0 → 2.1.0

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

@@ -0,0 +1,274 @@
+---
+created_date: YYYY-MM-DD
+updated_date: YYYY-MM-DD
+executor: ""
+reviewer: ""
+status: Draft
+epic_id: ""
+feature_ids: []  # comma-separated Feature IDs chained in this scenario
+scenario_id: ""
+platform: web
+tags: []
+ver: 1.0
+---
+
+# E2E Test Specification: {Scenario Name}
+
+**Epic**: [{Epic_ID}] | **Features**: {feature_ids} | **Scenario**: [{Scenario_ID}]
+**Author**: @{executor} | **Reviewer**: @{reviewer} | **Status**: {status}
+
+---
+
+## 1. Scenario Overview
+
+> 📌 E2E Test Case mô phỏng **hành trình thực tế của người dùng (User Journey)** xuyên suốt hệ thống, kết nối multiple features thành một workflow hoàn chỉnh.
+
+| **Field**           | **Detail**                                                        |
+| ------------------- | ----------------------------------------------------------------- |
+| **Scenario Name**   | {Business Flow Name - e.g., "Complete Purchase Journey"}          |
+| **Business Value**  | {Why this flow matters - revenue, user retention, compliance}     |
+| **User Persona**    | {Who performs this journey - e.g., "First-time Customer", "Admin"} |
+| **Entry Point**     | {Where user starts - e.g., Homepage, Login page}                   |
+| **Exit Point**      | {Where user ends - e.g., Order confirmation, Dashboard}           |
+| **Success Criteria**| {What defines success - e.g., Order created, Email sent}           |
+
+---
+
+## 2. Integrated Systems & Dependencies
+
+> 🔗 **Systems involved in this E2E flow**
+
+| **System / Module**      | **Role**                           | **Integration Type** | **Failure Impact** |
+| ------------------------ | ---------------------------------- | ------------------- | ------------------ |
+| Frontend (Web/Mobile)    | User interface                    | Direct              | Critical           |
+| Backend API              | Business logic processing          | REST/GraphQL        | Critical           |
+| Database                 | Data persistence                   | ORM/Query           | Critical           |
+| Payment Gateway          | Payment processing                 | Third-party API     | High               |
+| Email Service            | Notifications                      | Webhook/API         | Medium             |
+| {External System}        | {Description}                      | {Type}              | {Impact}           |
+
+### Prerequisites & Setup
+
+| **Requirement**          | **State**                          | **Verification**                              |
+| ------------------------ | ---------------------------------- | --------------------------------------------- |
+| Test Environment         | Staging / Test                     | `curl https://test-api.example.com/health`   |
+| User Accounts            | Created with proper roles          | Check admin panel / DB                        |
+| Master Data              | Products, configs seeded           | Verify test data fixtures                     |
+| Third-party Credentials  | Payment gateway, SMS configured    | Test transaction → verify dashboard           |
+| Feature Flags            | Required features enabled          | Confirm with dev team                         |
+
+---
+
+## 3. Functional Test Cases Mapping
+
+> 📋 **E2E flow được xây dựng từ các Functional Test Cases đã có**
+> Mỗi bước trong E2E mapping với 1 hoặc nhiều Functional TCs
+
+| **E2E Step** | **Functional TC Reference**        | **Feature**              | **Purpose**                          |
+| ------------ | ---------------------------------- | ------------------------ | ------------------------------------ |
+| Step 1       | `{FT_ID}_001_H`                    | {Feature A}              | Initial action                       |
+| Step 2       | `{FT_ID}_002_H`, `{FT_ID}_003_N`   | {Feature B}              | Core processing                      |
+| Step 3       | `{FT_ID}_004_H`                    | {Feature C}              | Validation & confirmation            |
+
+---
+
+## 4. E2E Test Scenarios
+
+### Test ID Format: `{PROJECT}_E2E_{SCENARIO_ID}_{FLOW_TYPE}_{NUMBER}`
+
+**Flow Types:**
+- `HP` - Happy Path (Main user journey)
+- `NEG` - Negative Flow (Error handling across systems)
+- `EDGE` - Edge Case (Boundary conditions)
+- `PERF` - Performance Flow
+
+---
+
+### 4.1 Happy Path E2E Scenarios
+
+> ✅ **Main user journeys - MUST automate these**
+
+| **E2E Case ID**       | **User Persona** | **Business Flow**                           | **Pre-Conditions**                            | **Cross-Functional Steps**                                                                                                                                                                 | **Expected Final State**                                                              | **Priority** | **Autoable** | **Traceability**            |
+| --------------------- | ---------------- | ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------ | ------------ | -------------------------- |
+| `{PROJECT}_E2E_001_HP` | Customer         | Complete purchase journey                   | 1. User logged in<br>2. Product in stock<br>3. Payment method valid | **Step 1 [Browse]:** Navigate to product page<br>**Step 2 [Cart]:** Add to cart, verify total<br>**Step 3 [Checkout]:** Fill shipping info<br>**Step 4 [Payment]:** Process payment via gateway<br>**Step 5 [Confirm]:** Verify order created<br>**Step 6 [Notify]:** Check email sent | Order status = "Confirmed"<br>Inventory decremented<br>Payment recorded<br>Email received | P0           | Yes          | FT-001, FT-005, FT-012      |
+| `{PROJECT}_E2E_002_HP` | Admin            | User onboarding workflow                    | 1. Admin logged in<br>2. Email server configured | **Step 1 [Invite]:** Create user invite<br>**Step 2 [Email]:** Verify invitation sent<br>**Step 3 [Accept]:** User accepts invite<br>**Step 4 [Setup]:** Complete profile<br>**Step 5 [Notify]:** Admin notified | User status = "Active"<br>Admin dashboard updated<br>Welcome email sent              | P0           | Yes          | FT-020, FT-021, FT-025      |
+
+---
+
+### 4.2 Negative Flow E2E Scenarios
+
+> ❌ **Error handling across system boundaries**
+
+| **E2E Case ID**       | **User Persona** | **Business Flow**                           | **Pre-Conditions**                    | **Cross-Functional Steps**                                                                                                                                                                 | **Expected Final State**                                                            | **Priority** | **Autoable** | **Traceability**        |
+| --------------------- | ---------------- | ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------ | ------------ | ----------------------- |
+| `{PROJECT}_E2E_003_NEG` | Customer         | Payment failure recovery                    | 1. User logged in<br>2. Invalid card   | **Step 1 [Browse]:** Select product<br>**Step 2 [Cart]:** Proceed to checkout<br>**Step 3 [Payment]:** Submit invalid payment<br>**Step 4 [Error]:** Verify error message<br>**Step 5 [Retry]:** Update payment method<br>**Step 6 [Success]:** Complete payment | Order NOT created<br>Error displayed clearly<br>Cart preserved<br>Retry successful | P1           | Yes          | FT-001, FT-008, FT-015   |
+| `{PROJECT}_E2E_004_NEG` | Customer         | Stock depletion during checkout             | 1. Product low stock<br>2. Multiple users | **Step 1 [Browse]:** Add to cart (stock available)<br>**Step 2 [Delay]:** Wait 30s<br>**Step 3 [Checkout]:** Attempt payment<br>**Step 4 [Error]:** Verify out-of-stock message<br>**Step 5 [Notify]:** Check stock alert | Payment rejected<br>Clear OOS message<br>Back-in-stock notification registered      | P1           | Yes          | FT-001, FT-009, FT-018   |
+
+---
+
+### 4.3 Edge Case E2E Scenarios
+
+> ⚠️ **Boundary and unusual conditions**
+
+| **E2E Case ID**       | **User Persona** | **Business Flow**                           | **Pre-Conditions**                    | **Cross-Functional Steps**                                                                                                                                                                 | **Expected Final State**                                          | **Priority** | **Autoable** | **Traceability**      |
+| --------------------- | ---------------- | ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------ | ------------ | --------------------- |
+| `{PROJECT}_E2E_005_EDGE` | Customer         | Large order handling                        | 1. VIP customer<br>2. Bulk discount enabled | **Step 1 [Browse]:** Add 100+ items<br>**Step 2 [Cart]:** Verify bulk discount applied<br>**Step 3 [Checkout]:** Process large order<br>**Step 4 [Confirm]:** Verify order split if needed<br>**Step 5 [Notify]:** Verify warehouse notification | Order created with discount<br>Warehouse notified of bulk<br>Invoice correct | P2           | Yes          | FT-003, FT-007, FT-014 |
+| `{PROJECT}_E2E_006_EDGE` | Admin            | Concurrent user operations                  | 1. Two admin sessions<br>2. Same record  | **Step 1 [Session A]:** Open record for edit<br>**Step 2 [Session B]:** Attempt same record edit<br>**Step 3 [Conflict]:** Verify optimistic lock<br>**Step 4 [Resolve]:** Save latest changes<br>**Step 5 [Audit]:** Check audit log | Optimistic lock triggered<br>Last write wins<br>Audit log complete | P2           | Yes          | FT-022, FT-028         |
+
+---
+
+### 4.4 Performance E2E Scenarios
+
+> ⚡ **Load and timing validation**
+
+| **E2E Case ID**       | **User Persona** | **Business Flow**                           | **Pre-Conditions**                    | **Cross-Functional Steps**                                                                                                                                                                 | **Expected Final State**                                                                                   | **Priority** | **Autoable** | **Traceability**    |
+| --------------------- | ---------------- | ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------ | ------------ | ------------------- |
+| `{PROJECT}_E2E_007_PERF` | Customer         | Peak load checkout                          | 1. Load test configured<br>2. 50 concurrent users | **Step 1 [Load]:** Simulate 50 users starting checkout<br>**Step 2 [Process]:** All users complete payment<br>**Step 3 [Verify]:** Check all orders created<br>**Step 4 [DB]:** Verify no deadlocks<br>**Step 5 [Timing]:** Response < 3s p95 | All 50 orders created<br>No data corruption<br>p95 response time < 3s<br>Zero errors logged | P1           | Yes          | FT-001, FT-012, FT-018 |
+
+---
+
+## 5. Data Flow Validation
+
+> 🔄 **E2E phải kiểm tra dữ liệu cuối cùng trong Database/system bên thứ ba**
+
+| **Data Point**        | **Source**              | **Expected Value**                     | **Verification Method**                                      | **System**        |
+| --------------------- | ----------------------- | -------------------------------------- | ----------------------------------------------------------- | ----------------- |
+| Order Status          | Database                | "Confirmed"                            | `SELECT status FROM orders WHERE id = {order_id}`           | Backend DB        |
+| Payment Transaction   | Payment Gateway API     | transaction_id present, status=success | `GET /api/payment/{transaction_id}`                         | Third-party API   |
+| Inventory Count       | Database                | Decremented by 1                       | `SELECT quantity FROM products WHERE id = {product_id}`     | Backend DB        |
+| Email Delivered       | Email Service / Mailhog | Email present in inbox                | Check Mailhog or test email inbox                          | Email Service     |
+| Audit Log             | Database                | Action recorded with timestamp         | `SELECT * FROM audit_logs WHERE entity_id = {order_id}`     | Backend DB        |
+
+---
+
+## 6. Integration Points Validation
+
+> 🔗 **Critical checkpoints between systems**
+
+| **Integration Point**      | **Test Method**                              | **Success Criteria**                                      | **Failure Handling**                             |
+| -------------------------- | --------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
+| Frontend → Backend API     | Intercept network requests, verify response   | Status 200, valid JSON, correct data                      | Show user-friendly error, retry logic           |
+| Backend → Payment Gateway  | Mock or real payment, verify callback         | Payment success, transaction ID returned                  | Handle timeout, log failure, notify user        |
+| Backend → Email Service    | Check email delivery (Mailhog/test inbox)     | Email sent, correct recipient, valid content              | Queue for retry, log delivery status            |
+| Backend → Database         | Query DB after flow completes                 | Data persisted correctly, no orphan records               | Transaction rollback, error logging             |
+| External API Callback      | Simulate webhook from external system         | Callback received, processed, status updated              | Idempotency, retry mechanism, dead letter queue |
+
+---
+
+## 7. Browser & Platform Matrix
+
+| **Platform**   | **Browser / Device** | **Version**      | **Required** | **Notes**                          |
+| -------------- | -------------------- | ---------------- | ------------ | ---------------------------------- |
+| Desktop Web    | Chrome               | Latest           | Yes          | Primary platform                   |
+| Desktop Web    | Firefox              | Latest           | Yes          | Firefox-specific issues            |
+| Desktop Web    | Safari               | Latest           | Yes          | WebKit engine differences          |
+| Mobile Web     | iOS Safari           | iOS 17+          | Yes          | Mobile responsive                  |
+| Mobile Web     | Android Chrome       | Android 14+      | Yes          | Mobile responsive                  |
+| Mobile App     | iOS App              | iOS 17+          | Optional     | If mobile app exists               |
+| Mobile App     | Android App          | Android 14+      | Optional     | If mobile app exists               |
+
+---
+
+## 8. Success Criteria & Exit Conditions
+
+### Must Have (P0)
+- [ ] All Happy Path E2E scenarios pass
+- [ ] Database state verified correct after each flow
+- [ ] Third-party integrations validated (payment, email)
+- [ ] No data corruption or orphan records
+- [ ] User receives all expected notifications
+
+### Should Have (P1)
+- [ ] Negative flows handle errors gracefully
+- [ ] Performance within SLA (p95 < 3s)
+- [ ] All required browsers/platforms pass
+- [ ] Audit logs complete and accurate
+
+### Nice to Have (P2)
+- [ ] Edge cases handled correctly
+- [ ] Performance under load validated
+- [ ] Accessibility checks pass
+- [ ] Cross-browser consistency verified
+
+---
+
+## 9. Risk & Dependency Matrix
+
+| **Risk ID** | **Risk Description**                             | **Impact** | **Mitigation Strategy**                                      | **Owner**    |
+| ----------- | ------------------------------------------------ | ---------- | ------------------------------------------------------------ | ------------ |
+| E2E-RSK-01  | Payment gateway downtime during test             | High       | Have mock payment fallback, check status page first         | DevOps       |
+| E2E-RSK-02  | Test data not seeded properly                   | High       | Verify data setup script runs before E2E suite              | QA Lead      |
+| E2E-RSK-03  | Flaky tests due to timing issues                 | Medium     | Add explicit waits, use stable selectors                     | Automation   |
+| E2E-RSK-04  | Staging environment not production-like          | High       | Regular sync of staging with production config              | DevOps       |
+| E2E-RSK-05  | Third-party API rate limits during E2E runs      | Medium     | Use test API keys, implement exponential backoff            | Backend Dev  |
+
+---
+
+## 10. Automation Strategy
+
+### Framework & Tools
+
+| **Component**    | **Tool**           | **Purpose**                           |
+| ---------------- | ------------------ | ------------------------------------- |
+| Test Framework   | Playwright/Cypress | E2E test execution                   |
+| API Testing      | Postman/REST Assured | Backend integration validation      |
+| Data Verification | SQL scripts / DB client | Database state validation          |
+| Email Testing    | Mailhog / Test mail inbox | Notification verification         |
+| Load Testing     | k6 / JMeter        | Performance E2E scenarios            |
+
+### Automation Execution
+
+```bash
+# Run E2E suite locally
+yarn e2e:local
+
+# Run on specific environment
+yarn e2e:staging
+
+# Run specific scenario
+yarn e2e:scenario --scenarioId="E2E_001"
+
+# Run with report
+yarn e2e:report
+```
+
+### CI/CD Integration
+
+- Run smoke E2E tests on every PR
+- Run full E2E suite on merge to main
+- Run regression E2E nightly on staging
+- Block deployment if critical E2E tests fail
+
+---
+
+## 11. Coverage Summary
+
+**Feature Coverage:**
+
+| **Feature ID** | **Feature Name**            | **E2E Scenarios Covered** | **Coverage %** |
+| -------------- | --------------------------- | ------------------------- | -------------- |
+| {Feature-001}  | {Feature Name}              | E2E_001, E2E_003          | 100%           |
+| {Feature-002}  | {Feature Name}              | E2E_001, E2E_002          | 100%           |
+| {Feature-003}  | {Feature Name}              | E2E_005                   | 100%           |
+
+**Overall Coverage:**
+
+| **Metric**           | **Value**            |
+| -------------------- | -------------------- |
+| Total E2E Scenarios  | {count}              |
+| Happy Path           | {count} ({percent}%) |
+| Negative Flows       | {count} ({percent}%) |
+| Edge Cases           | {count} ({percent}%) |
+| Automatable         | {count} ({percent}%) |
+| Manual Only          | {count} ({percent}%) |
+
+---
+
+## 12. Change Log
+
+> **Note:** Changes are summarized daily (Daily Summary format).
+
+| **Date**          | **Ver** | **Daily Summary of Changes**                                              | **Author**    |
+| ----------------- | ------- | ------------------------------------------------------------------------- | ------------- |
+| {created_date}    | 1.0     | Initial E2E test specification created                                    | @{executor}   |
+| {updated_date}    | 1.0     | Initial E2E test specification created                                    | @{executor}   |

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

@@ -3,14 +3,14 @@ created_date:
 updated_date:
 executor:
 status: Draft
-epic_id:
+feature_ids: # comma-separated Feature IDs chained in this scenario
 scenario_id:
 ---
 
 # E2E Web Test Specification: {Scenario Name}
 
 **Scenario**: [{Scenario_ID}]({SCENARIO_LINK})
-**Epic(s)**: [{Epic_ID}]({Epic_LINK})
+**Features**: {feature_ids}
 **Author**: @[executor]
 **Created**: [created_date]
 **Status**: [status] (Draft | Ready | Implemented | Verified)
@@ -54,8 +54,8 @@ scenario_id:
 
 | 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 |
+| {PROJECT}_E2E_001_H | 1 | {Page} | {Action} | {Expected} | All | All |
+| {PROJECT}_E2E_001_H | 2 | {Page} | {Action} | {Expected} | All | All |
 
 ### Cross-Browser Specific
 

package/.tas/templates/Feature-Technical-Part.md

@@ -0,0 +1,69 @@
+---
+feature_id:              # e.g., Feature-001
+parent_technical_file:   # relative path to Feature-Technical.md (index)
+part_id:                 # e.g., part1, part2
+part_title:              # e.g., Cart Processing
+stacks_involved:         # e.g., [service, integration]
+plan_by:
+plan_date:
+status: Draft            # Draft | Approved | Implemented
+---
+# Feature-{NNN}-Technical: {Title} — Part: {part_title}
+
+> Sub-feature detail file for part `{part_id}`. Global context (Context Diagram, Data Flow, API Spec, ERD, Architecture Decisions): see [`{parent_technical_file}`]({parent_technical_file}).
+> Stacks involved in this part: {stacks_involved}.
+> Source of truth for SE during `/tas-dev` for this part only.
+
+---
+
+## Stack: {Stack}
+> *(repeat this section per stack involved in this part — omit stacks not touched here)*
+
+### Logic Flow
+1. {entry point}
+2. {validation / auth}
+3. {business logic}
+4. {persistence / external call}
+5. {response / event emit}
+
+### File Changes
+
+#### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+#### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+#### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+### Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+
+### Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+### Tasks
+- [ ] 1: {file + change}
+- [ ] 2: {file + change}
+- [ ] 3: Unit tests for AC-1, AC-2
+
+---
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|

package/.tas/templates/Feature-Technical-Stack.md

@@ -0,0 +1,74 @@
+---
+feature_id:              # e.g., Feature-001
+parent_technical_file:   # relative path to Feature-Technical.md (index)
+stack:                   # web | service | integration | app
+plan_by:
+plan_date:
+status: Draft            # Draft | Approved | Implemented
+---
+# Feature-{NNN}-Technical: {Title} — Stack: {Stack}
+
+> Stack detail file for `{stack}`. Global context (Context Diagram, Data Flow, API Spec, ERD, Architecture Decisions): see [`{parent_technical_file}`]({parent_technical_file}).
+> Source of truth for SE during `/tas-dev` for this stack only.
+
+---
+
+## Logic Flow
+1. {entry point}
+2. {validation / auth}
+3. {business logic}
+4. {persistence / external call}
+5. {response / event emit}
+
+Optional sequence diagram:
+:::mermaid
+sequenceDiagram
+  Caller->>Controller: request
+  Controller->>Service: invoke
+  Service->>Repository: read/write
+  Repository->>DB: query
+  DB-->>Service: rows
+  Service-->>Caller: response
+:::
+
+## File Changes
+
+### Modify
+| File | Change | Reason |
+|------|--------|--------|
+| {path} | {what} | {why} |
+
+### Create
+| File | Purpose |
+|------|---------|
+| {path} | {what it does} |
+
+### Delete
+| File | Reason |
+|------|--------|
+| {path} | {why removed} |
+
+## Config
+| Item | Type | Value / Source | Environment |
+|------|------|----------------|-------------|
+| {VAR_NAME} | env var | {description} | dev / staging / prod |
+
+## Unit Test Cases
+> Test ID: `{PROJECT}_F{FEATURE}_AC{N}_UT_NNN_{H|E|N}`
+
+| ID | AC Ref | Type | Description | Input | Expected Output |
+|----|--------|------|-------------|-------|-----------------|
+| {PROJ}_F{NNN}_AC1_UT_001_H | AC-1 | Happy | {description} | {input} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_E | AC-1 | Edge | {description} | {boundary} | {expected} |
+| {PROJ}_F{NNN}_AC1_UT_001_N | AC-1 | Negative | {description} | {invalid} | {error} |
+
+## Tasks
+- [ ] 1: {file + change}
+- [ ] 2: {file + change}
+- [ ] 3: Unit tests for AC-1, AC-2
+
+---
+
+## Changelog
+| Date | Changes | Author |
+|------|---------|--------|