@torus-engineering/tas-kit 1.7.0 → 1.9.0

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

@@ -0,0 +1,400 @@
+---
+api_name:
+api_slug:
+api_version:
+spec_source:
+code_path:
+status:
+created_date:
+updated_date:
+executor:
+story_id:
+framework: xUnit
+---
+
+# API Test Specification: {API Name}
+
+**API Version**: v{api_version}
+**Framework**: {framework}
+**Author**: @[executor]
+**Created**: [created_date]
+**Updated**: [updated_date]
+**Status**: [status] (Draft | Review | Approved | Deprecated)
+**Spec Source**: [spec_source]
+**Code Path**: [code_path]
+**Story**: [story_id] (if applicable)
+
+---
+
+## Version History
+
+> Mỗi API version có section riêng biệt. APPEND-ONLY: không sửa version cũ.
+
+| Version | Status | Created | Description |
+|---------|--------|---------|-------------|
+| v1 | Draft | [created_date] | Initial version |
+| v2 | Draft | [updated_date] | Added new endpoints |
+
+---
+
+## Test Environment Setup
+
+### Configuration (appsettings.json)
+
+```json
+{
+  "ApiTest": {
+    "BaseUrl": "https://localhost:5001",
+    "TimeoutSeconds": 30,
+    "Auth": {
+      "Type": "Bearer",
+      "TokenEndpoint": "/api/auth/token",
+      "Username": "",
+      "Password": ""
+    }
+  }
+}
+```
+
+### Environment-Specific Overrides
+
+| Environment | BaseUrl | Notes |
+|-------------|---------|-------|
+| Local | https://localhost:5001 | Development environment |
+| Test | https://test-api.example.com | Shared test environment |
+| Staging | https://staging-api.example.com | Pre-production |
+| Production | https://api.example.com | Smoke tests only |
+
+### Test Data Requirements
+
+| Data Item | Value | Source | Environment-Specific | Notes |
+|-----------|-------|--------|---------------------|-------|
+| Test User Email | test@example.com | test-data.{env}.json | Yes | Different per env |
+| Test User Password | (from .env) | process.env.APITEST__AUTH__PASSWORD | Yes | NEVER hardcode |
+| Auth Token | Generated at runtime | POST /api/auth/token | Yes | Refresh per test class |
+| {Entity} ID | {value} | test-data.{env}.json | Yes | Pre-seeded data |
+
+### Setup/Teardown Notes
+
+**Before All Tests:**
+- Authenticate and store token for authenticated requests
+- Seed test data if required
+- Configure HttpClient with base address and timeout
+
+**After All Tests:**
+- Dispose HttpClient
+- Clean up test data (unless debugging needed)
+
+**Before Each Test:**
+- Reset state if needed (clear headers, reset counters)
+
+**After Each Test:**
+- Log test result
+- Capture response on failure for debugging
+
+---
+
+## v{N} — Test Cases
+
+### Endpoints Overview
+
+| Method | Path | Description | Auth Required |
+|--------|------|-------------|---------------|
+| GET | /api/users | List users | Yes |
+| POST | /api/users | Create user | Yes |
+| GET | /api/users/{id} | Get user by ID | Yes |
+| PUT | /api/users/{id} | Update user | Yes |
+| DELETE | /api/users/{id} | Delete user | Yes |
+
+### Coverage Matrix
+
+| Endpoint | Happy Path | 401 Unauthorized | 403 Forbidden | 404 Not Found | 400/422 Validation | Business Rule |
+|----------|:---------:|:----------------:|:-------------:|:-------------:|:------------------:|:-------------:|
+| GET /api/users | ✓ | ✓ | | | | |
+| POST /api/users | ✓ | ✓ | | | ✓ | |
+| GET /api/users/{id} | ✓ | ✓ | | ✓ | | |
+| PUT /api/users/{id} | ✓ | ✓ | | ✓ | ✓ | |
+| DELETE /api/users/{id} | ✓ | ✓ | ✓ | ✓ | | |
+
+---
+
+### Test Case Details
+
+#### GET /api/users — List Users
+
+##### TC-001: Happy Path — Returns Paginated User List
+- **Endpoint**: `GET /api/users?page=1&limit=10`
+- **Auth**: Required (Bearer token)
+- **Preconditions**:
+  - Valid authentication token
+  - At least 10 users exist in database
+- **Request Query Params**:
+  - `page`: 1
+  - `limit`: 10
+- **Expected Response**:
+  - Status: 200 OK
+  - Body:
+    ```json
+    {
+      "data": [
+        {
+          "id": "guid",
+          "email": "user@example.com",
+          "name": "John Doe",
+          "role": "User",
+          "createdAt": "2024-01-01T00:00:00Z"
+        }
+      ],
+      "total": 100,
+      "page": 1,
+      "limit": 10
+    }
+    ```
+- **Assertions**:
+  - Response status is 200
+  - `data` is array with length ≤ 10
+  - Each item has required fields: id, email, name, role, createdAt
+  - `total` ≥ 0
+  - `page` and `limit` match request
+- **AC Reference**: N/A (API spec)
+- **Test Method Name**: `Get_Users_Returns200_WhenAuthenticated`
+
+##### TC-002: Security — Returns 401 When No Token
+- **Endpoint**: `GET /api/users`
+- **Auth**: Not provided
+- **Preconditions**: None
+- **Expected Response**:
+  - Status: 401 Unauthorized
+  - Body contains error message
+- **Assertions**:
+  - Response status is 401
+- **AC Reference**: N/A
+- **Test Method Name**: `Get_Users_Returns401_WhenNotAuthenticated`
+
+##### TC-003: Edge Case — Empty List When No Users Exist
+- **Endpoint**: `GET /api/users`
+- **Auth**: Required
+- **Preconditions**:
+  - Database is empty or no users match filter
+- **Expected Response**:
+  - Status: 200 OK
+  - Body:
+    ```json
+    {
+      "data": [],
+      "total": 0,
+      "page": 1,
+      "limit": 10
+    }
+    ```
+- **Assertions**:
+  - Response status is 200
+  - `data` is empty array
+  - `total` is 0
+- **AC Reference**: N/A
+- **Test Method Name**: `Get_Users_ReturnsEmptyArray_WhenNoUsersExist`
+
+#### POST /api/users — Create User
+
+##### TC-004: Happy Path — Creates New User
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "email": "newuser@example.com",
+    "name": "New User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 201 Created
+  - Body contains created user with generated `id`
+  - `Location` header contains URL of new resource
+- **Assertions**:
+  - Response status is 201
+  - `id` is valid GUID
+  - `email`, `name`, `role` match request
+  - `password` is NOT in response
+  - `createdAt` is recent
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns201_WhenValidRequest`
+
+##### TC-005: Validation — Returns 400 When Email Invalid
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "email": "invalid-email",
+    "name": "Test User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 400 Bad Request
+  - Body contains validation errors
+- **Assertions**:
+  - Response status is 400
+  - Error message indicates email format issue
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns400_WhenEmailInvalid`
+
+##### TC-006: Business Rule — Returns 409 When Email Already Exists
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Preconditions**: User with email already exists
+- **Request Body**:
+  ```json
+  {
+    "email": "existing@example.com",
+    "name": "Test User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 409 Conflict
+  - Body indicates email already registered
+- **Assertions**:
+  - Response status is 409
+  - Error message mentions duplicate email
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns409_WhenEmailAlreadyExists`
+
+#### GET /api/users/{id} — Get User by ID
+
+##### TC-007: Happy Path — Returns User When ID Exists
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Path Params**: `id` = valid GUID
+- **Expected Response**:
+  - Status: 200 OK
+  - Body contains user details
+- **Assertions**:
+  - Response status is 200
+  - All required fields present
+- **AC Reference**: N/A
+- **Test Method Name**: `GetById_Users_Returns200_WhenExists`
+
+##### TC-008: Error Path — Returns 404 When ID Not Found
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Path Params**: `id` = valid but non-existent GUID
+- **Expected Response**:
+  - Status: 404 Not Found
+- **Assertions**:
+  - Response status is 404
+- **AC Reference**: N/A
+- **Test Method Name**: `GetById_Users_Returns404_WhenNotFound`
+
+#### PUT /api/users/{id} — Update User
+
+##### TC-009: Happy Path — Updates User
+- **Endpoint**: `PUT /api/users/{id}`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "name": "Updated Name"
+  }
+  ```
+- **Expected Response**:
+  - Status: 200 OK
+  - Body contains updated user
+- **Assertions**:
+  - Response status is 200
+  - `name` matches request
+- **AC Reference**: N/A
+- **Test Method Name**: `Put_Users_Returns200_WhenValidUpdate`
+
+##### TC-010: Validation — Returns 400 When Name Empty
+- **Endpoint**: `PUT /api/users/{id}`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "name": ""
+  }
+  ```
+- **Expected Response**:
+  - Status: 400 Bad Request
+- **Assertions**:
+  - Response status is 400
+- **AC Reference**: N/A
+- **Test Method Name**: `Put_Users_Returns400_WhenNameEmpty`
+
+#### DELETE /api/users/{id} — Delete User
+
+##### TC-011: Happy Path — Deletes User
+- **Endpoint**: `DELETE /api/users/{id}`
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 204 No Content
+- **Assertions**:
+  - Response status is 204
+  - Subsequent GET returns 404
+- **AC Reference**: N/A
+- **Test Method Name**: `Delete_Users_Returns204_WhenExists`
+
+##### TC-012: Authorization — Returns 403 When Deleting Self
+- **Endpoint**: `DELETE /api/users/{id}` where id = current user's id
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 403 Forbidden
+- **Assertions**:
+  - Response status is 403
+  - Error message indicates cannot delete own account
+- **AC Reference**: N/A
+- **Test Method Name**: `Delete_Users_Returns403_WhenDeletingSelf`
+
+---
+
+## Story-Specific Test Cases (Optional)
+
+> Nếu spec được generate từ Story, thêm AC mapping ở đây.
+
+| AC ID | AC Description | Test Case IDs |
+|-------|----------------|---------------|
+| AC-1 | {Given...When...Then...} | TC-001, TC-002 |
+| AC-2 | {Given...When...Then...} | TC-004, TC-005 |
+
+---
+
+## Regression Tests (Optional)
+
+> Test cases cho bugs đã được tìm thấy và fix.
+
+| Bug ID | Description | Test Case ID | Date Added |
+|--------|-------------|--------------|------------|
+| BUG-001 | User profile missing notification_settings field | TC-R001 | 2024-01-15 |
+
+### TC-R001: BUG-001 Regression — notification_settings Present in Response
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 200 OK
+  - Body includes `notification_settings` field
+- **Assertions**:
+  - `notification_settings` is present and not undefined
+- **Test Method Name**: `BUG_R001_NotificationSettings_IsPresent`
+
+---
+
+## Changelog
+
+| Date | Version | Changes | Author |
+|------|---------|---------|--------|
+| [created_date] | v1 | Initial API test specification | @[executor] |
+| [updated_date] | v2 | Added endpoints for user management | @[executor] |
+
+---
+
+## AI Usage Log
+
+| # | Date | Command | Input (est.) | Output (est.) |
+|---|------|---------|-------------|---------------|
+| 1 | [created_date] | /tas-apitest-plan | ~{N}k | ~{N}k |
+| **Total** | | | **~{N}k** | **~{N}k** |

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

@@ -0,0 +1,198 @@
+---
+created_date:
+executor:
+status: # Pass | Fail | Partial
+test_layer: # functional | e2e
+scenario_id:
+feature_id:
+epic_id:
+platform: # mobile-ios | mobile-android | web-chromium | web-firefox | web-webkit
+environment: # dev | staging | prod
+---
+
+# Test Execution Report: {Scenario/Feature Name}
+
+**Layer**: {{test_layer}} (Functional | E2E)
+**Platform**: {{platform}}
+**Environment**: {{environment}}
+**Executor**: @[executor]
+**Date**: [created_date]
+**Status**: [status]
+
+---
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Tests | {count} |
+| Passed | {count} |
+| Failed | {count} |
+| Skipped | {count} |
+| Flaky | {count} |
+| Pass Rate | {X}% |
+| Execution Time | {duration} |
+| Environment | {{environment}} |
+
+---
+
+## Results by Test ID
+
+| Test ID | AC Ref | Description | Result | Duration | Failure Reason |
+|---------|--------|-------------|--------|----------|----------------|
+| {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_001_H | AC-1 | {description} | PASS | {Xs} | - |
+| {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_002_N | AC-1 | {description} | PASS | {Xs} | - |
+| {PROJECT}_E{EPIC}_F{FEATURE}_S{STORY}_FT_003_E | AC-1 | {description} | FAIL | {Xs} | {brief reason: element not found / assertion mismatch / timeout / ...} |
+
+---
+
+## Failed Tests
+
+### {Test ID}: {Test Description}
+
+**AC Reference**: AC-{N}
+**Failure Reason**: {Mô tả ngắn gọn LÝ DO fail — ví dụ: "Button 'Submit' không hiển thị sau khi nhập email hợp lệ", "API trả về 401 thay vì 200", "Timeout sau 5s chờ màn hình Home load"}
+**Error Type**: {Assertion Failure | Timeout | Crash | Element Not Found}
+**Error Message**:
+```
+{Error stack trace or message}
+```
+
+**Screenshot/Video**: `artifacts/{platform}/{test-id}.png`
+
+**Root Cause Analysis**:
+> {Brief analysis of why the test failed}
+
+**Severity**: {Critical | Major | Minor}
+**Action Required**: {Fix code | Fix test | Investigate flaky | Skip with reason}
+
+---
+
+## Flaky Tests
+
+| Test ID | Flaky Rate | Last 3 Runs | Suspected Cause |
+|---------|------------|-------------|-----------------|
+| {ID} | {X/3} | P/F/P | {Animation timing | Network | Race condition} |
+
+---
+
+## Platform Results
+
+{{#if platform.startsWith("mobile")}}
+### Mobile Platform Details
+
+| Detail | Value |
+|--------|-------|
+| Device | {iPhone 17 Pro / Samsung S21} |
+| OS | {iOS 18.x / Android 14} |
+| App Build | {Debug / Release} |
+| Detox Version | {version} |
+| React Native | {version} |
+| Node | {version} |
+
+### Device-Specific Issues
+| Issue | Device | Impact | Resolution |
+|-------|--------|--------|------------|
+| {Issue} | {Device} | {Tests affected} | {Fix/Workaround} |
+{{/if}}
+
+{{#if platform.startsWith("web")}}
+### Web Platform Details
+
+| Detail | Value |
+|--------|-------|
+| Browser | {Chromium / Firefox / WebKit} |
+| Browser Version | {version} |
+| Playwright Version | {version} |
+| Viewport | {width}x{height} |
+| Node | {version} |
+
+### Browser-Specific Issues
+| Issue | Browser | Impact | Resolution |
+|-------|---------|--------|------------|
+| {Issue} | {Browser} | {Tests affected} | {Fix/Workaround} |
+{{/if}}
+
+---
+
+## Artifacts
+
+| Type | Path | Description |
+|------|------|-------------|
+| Screenshots | `artifacts/{platform}/screenshots/` | Failure screenshots |
+| Videos | `artifacts/{platform}/videos/` | Test execution recordings |
+| Logs | `artifacts/{platform}/logs/` | Debug logs |
+| HTML Report | `reports/{layer}-report.html` | Interactive HTML report |
+| JUnit XML | `reports/{layer}-results.xml` | CI/CD compatible results |
+
+---
+
+## Test Coverage Analysis
+
+### AC Coverage
+
+| AC ID | FT Tests | E2E Tests | Covered | Status |
+|-------|----------|-----------|---------|--------|
+| AC-1 | FT_001_H, FT_002_N | E2E_001 (Step 1) | Yes | All Pass |
+| AC-2 | FT_003_H | E2E_001 (Step 3) | Yes | 1 Fail |
+| AC-3 | - | - | No | Not tested |
+
+### Uncovered Areas
+- {List any ACs or scenarios not covered by this test run}
+
+---
+
+## Performance Metrics
+
+| Step/Test | Duration | Threshold | Status |
+|-----------|----------|-----------|--------|
+| {Step 1: Login} | {1.2s} | {< 3s} | OK |
+| {Step 2: Navigate} | {0.5s} | {< 2s} | OK |
+| {Step 3: Load Data} | {4.1s} | {< 3s} | SLOW |
+| Total Flow | {8.5s} | {< 15s} | OK |
+
+---
+
+## Blockers & Issues
+
+| # | Issue | Severity | Impact | Status | Bug ID |
+|---|-------|----------|--------|--------|--------|
+| 1 | {Issue description} | Critical | {Tests blocked} | {Open / Resolved} | {BUG-XXX} |
+| 2 | {Issue description} | Major | {Tests affected} | {Open / Resolved} | {BUG-XXX} |
+
+---
+
+## Recommendations
+
+### Immediate Actions
+- [ ] {Fix failing test / Fix code bug}
+- [ ] {Create bug ticket for issue X}
+
+### Follow-up
+- [ ] {Investigate flaky test}
+- [ ] {Add missing test coverage for AC-X}
+
+### Maintenance
+- [ ] {Update test data for next sprint}
+- [ ] {Refactor helper function X}
+
+---
+
+## Sign-off
+
+| Role | Name | Date | Approved |
+|------|------|------|----------|
+| QA | @[name] | [date] | [ ] |
+| Tech Lead | @[name] | [date] | [ ] |
+| PE (for Verify) | @[name] | [date] | [ ] |
+
+**Deployment Readiness**: [ ] Ready [ ] Not Ready
+**Reason (if not ready)**: {explanation}
+
+---
+
+## Changelog
+
+| Date | Changes | Author |
+|------|---------|--------|
+| [created_date] | Initial execution report | @[executor] |