@keber/qa-framework 1.0.4

package/templates/specification/01-business-rules.md

@@ -0,0 +1,90 @@
+# Business Rules — {{MODULE_NAME}}: {{SUBMODULE_NAME}}
+
+> **Module code**: {{MODULE_CODE}} | **Submodule code**: {{SUBMODULE_CODE}}  
+> **Last updated**: YYYY-MM-DD
+
+---
+
+## Summary
+
+| ID | Title | Type | Trigger |
+|----|-------|------|---------|
+| RN-{{M}}-001 | {{rule title}} | Validation | {{trigger}} |
+| RN-{{M}}-002 | {{rule title}} | Access Control | {{trigger}} |
+| RN-{{M}}-003 | {{rule title}} | State Machine | {{trigger}} |
+
+---
+
+## Rules
+
+### RN-{{MODULE_CODE}}-001: {{Rule Title}}
+
+- **Type**: Validation
+- **Trigger**: When user attempts to {{action}}
+- **Behavior**: {{what the system does}}
+- **Error message**: "{{exact text shown in UI}}"
+- **Notes**: {{any special circumstances}}
+
+---
+
+### RN-{{MODULE_CODE}}-002: {{Rule Title}}
+
+- **Type**: Access Control
+- **Trigger**: When user with role {{role}} navigates to {{URL}}
+- **Behavior**: {{redirect / error / empty page}}
+- **Notes**: —
+
+---
+
+### RN-{{MODULE_CODE}}-003: {{Rule Title}}
+
+- **Type**: State Machine
+- **Trigger**: When {{action}} is performed on a record with status {{STATUS_A}}
+- **Behavior**: Record transitions from {{STATUS_A}} to {{STATUS_B}}
+- **Invalid state**: Attempting this action on status {{STATUS_C}} results in {{error}}
+- **Notes**: —
+
+---
+
+### RN-{{MODULE_CODE}}-004: {{Rule Title}}
+
+- **Type**: Calculation
+- **Trigger**: When {{field}} or {{field}} changes
+- **Behavior**: {{calculated_field}} = {{formula}}
+- **Notes**: —
+
+---
+
+### RN-{{MODULE_CODE}}-005: {{Rule Title}}
+
+- **Type**: Integration
+- **Trigger**: When {{action}} completes successfully
+- **Behavior**: {{external system}} is notified/called — {{what happens}}
+- **Fallback**: {{what happens if external system fails}}
+- **Notes**: —
+
+---
+
+## State Machine (if applicable)
+
+```
+{{STATUS_INITIAL}}
+    │
+    ├─[action: approve]──► {{STATUS_APPROVED}}
+    │
+    └─[action: reject]───► {{STATUS_REJECTED}}
+```
+
+| State | Code | Description |
+|-------|------|-------------|
+| {{Pending}} | {{1}} | {{description}} |
+| {{Approved}} | {{2}} | {{description}} |
+| {{Rejected}} | {{3}} | {{description}} |
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Initial creation |

package/templates/specification/02-workflows.md

@@ -0,0 +1,114 @@
+# Workflows — {{MODULE_NAME}}: {{SUBMODULE_NAME}}
+
+> **Module code**: {{MODULE_CODE}} | **Submodule code**: {{SUBMODULE_CODE}}  
+> **Last updated**: YYYY-MM-DD
+
+---
+
+## FL-{{MODULE_CODE}}-001: {{Main Workflow Title}}
+
+**Actor**: {{Role}}  
+**Trigger**: {{What starts this workflow}}  
+**Precondition**: {{What must be true before this starts}}
+
+```
+[Start: navigate to {{URL}}]
+        │
+        ▼
+[Click 'New' button]
+        │
+        ▼
+[Form opens]
+        │
+        ├─[Required field empty]──► [Validation error shown] ──► [User corrects] ──► (loop back)
+        │
+        ▼
+[Fill all required fields]
+        │
+        ▼
+[Click 'Save']
+        │
+        ├─[Duplicate detected]────► [System shows duplicate error] ──► [End: failure]
+        │
+        ▼
+[Success message displayed]
+        │
+        ▼
+[New record appears in list]
+        │
+        ▼
+[End: record created successfully]
+```
+
+**Postcondition**: New record is persisted. Visible in the list view.
+
+---
+
+## FL-{{MODULE_CODE}}-002: {{Rejection / Cancellation Workflow Title}}
+
+**Actor**: {{Role}}  
+**Trigger**: {{What starts this workflow}}  
+**Precondition**: {{What must be true before this starts}}
+
+```
+[Start: navigate to pending records list]
+        │
+        ▼
+[Select record]
+        │
+        ▼
+[Click 'Reject' / 'Cancel']
+        │
+        ▼
+[Confirmation dialog appears]
+        │
+        ├─[User clicks 'No' / 'Cancel']──► [Dialog closes, no change]
+        │
+        ▼
+[User confirms]
+        │
+        ▼
+[System validates preconditions]
+        │
+        ├─[Precondition not met]─────────► [Error message]──► [End: rejected]
+        │
+        ▼
+[Record status changes to 'Rejected']
+        │
+        ▼
+[Notification sent (if applicable)]
+        │
+        ▼
+[End: record rejected]
+```
+
+**Postcondition**: Record status = Rejected. Notification sent to relevant parties.
+
+---
+
+## FL-{{MODULE_CODE}}-003: {{Error/Validation Workflow Title}}
+
+**Actor**: {{Role}}  
+**Trigger**: {{What starts this workflow when things go wrong}}
+
+```mermaid
+flowchart TD
+    A[User submits form] --> B{Validation passes?}
+    B -- No --> C[Show validation errors]
+    C --> D[User corrects input]
+    D --> A
+    B -- Yes --> E{Business rule passes?}
+    E -- No --> F[Show business rule error]
+    F --> G[End: submission rejected]
+    E -- Yes --> H[Record saved]
+    H --> I[Success feedback]
+    I --> J[End: success]
+```
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Initial creation |

package/templates/specification/03-roles-permissions.md

@@ -0,0 +1,49 @@
+# Roles and Permissions — {{MODULE_NAME}}: {{SUBMODULE_NAME}}
+
+> **Module code**: {{MODULE_CODE}} | **Submodule code**: {{SUBMODULE_CODE}}  
+> **Last updated**: YYYY-MM-DD
+
+---
+
+## Access Matrix
+
+| Feature / Action | {{Role 1}} | {{Role 2}} | {{Role 3}} | Notes |
+|-----------------|-----------|-----------|-----------|-------|
+| View list | ✅ | ✅ | ❌ | |
+| View detail | ✅ | ✅ | ❌ | |
+| Create new record | ✅ | ❌ | ❌ | |
+| Edit record | ✅ | ❌ | ❌ | |
+| Delete / deactivate | ✅ | ❌ | ❌ | Only own records |
+| Approve / reject | ❌ | ✅ | ❌ | |
+| Export | ✅ | ✅ | ❌ | |
+| View audit log | ✅ | ❌ | ❌ | |
+
+**Legend**: ✅ Permitted | ❌ Not permitted | ⚠️ Conditional
+
+---
+
+## Test User Reference
+
+| Role | Env var (email) | Env var (password) | Notes |
+|------|----------------|-------------------|-------|
+| {{Role 1}} | `QA_USER_{{ROLE1_UPPER}}_EMAIL` | `QA_USER_{{ROLE1_UPPER}}_PASSWORD` | {{any notes}} |
+| {{Role 2}} | `QA_USER_{{ROLE2_UPPER}}_EMAIL` | `QA_USER_{{ROLE2_UPPER}}_PASSWORD` | {{any notes}} |
+| {{Role 3}} | `QA_USER_{{ROLE3_UPPER}}_EMAIL` | `QA_USER_{{ROLE3_UPPER}}_PASSWORD` | {{any notes}} |
+
+> ⚠️ **Never put actual credentials in this file.** Credentials are loaded from environment variables only.
+
+---
+
+## Notes
+
+- {{Conditional access rule 1, e.g., "Admin can only edit records created by their team"}}
+- {{Conditional access rule 2}}
+- {{Any role-specific UI differences, e.g., "Encargado sees additional 'Assign' button"}}
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Initial creation |

package/templates/specification/04-test-data.md

@@ -0,0 +1,104 @@
+# Test Data — {{MODULE_NAME}}: {{SUBMODULE_NAME}}
+
+> **Module code**: {{MODULE_CODE}} | **Submodule code**: {{SUBMODULE_CODE}}  
+> **Last updated**: YYYY-MM-DD
+
+> ⚠️ **Security reminder**: Never put actual credentials, DNIs, or personal data in this file.  
+> All credentials are read from environment variables only.
+
+---
+
+## Prerequisites
+
+The following data must exist in the QA environment before tests run:
+
+| Item | Description | How provided |
+|------|-------------|-------------|
+| {{entity type}} | At least 1 active record exists | QA seed / pre-existing in env |
+| User: {{Role 1}} | Active user with {{Role 1}} role | `QA_USER_{{ROLE1_UPPER}}_EMAIL` env var |
+| User: {{Role 2}} | Active user with {{Role 2}} role | `QA_USER_{{ROLE2_UPPER}}_EMAIL` env var |
+| {{Prerequisite N}} | {{Description}} | Manual setup required / Seeder script |
+
+---
+
+## Data Shapes for Key Scenarios
+
+### Scenario: Happy path — create record
+
+| Field | Value / Rule |
+|-------|-------------|
+| {{name-field}} | `Test-{EXEC_IDX}` — unique per run via EXEC_IDX pattern |
+| {{select-field}} | Any valid option (first option is acceptable) |
+| {{date-field}} | `${2120 + (EXEC_IDX % 10)}-01-01` — future date, collision-resistant |
+| User | `{{Role 1}}`, credentials from `QA_USER_{{ROLE1_UPPER}}_EMAIL` |
+
+### Scenario: Required field validation
+
+| Field | Value |
+|-------|-------|
+| {{name-field}} | Empty (leave blank) |
+| All other fields | Valid values |
+
+**Expected**: Validation error prevents submission.
+
+### Scenario: Duplicate rejection
+
+| Field | Value |
+|-------|-------|
+| {{unique-field}} | Same value as an existing record |
+
+**Expected**: System error message: "{{exact duplicate error text}}"
+
+### Scenario: State transition — {{action}}
+
+| Field | Value |
+|-------|-------|
+| Source record | Record in status `{{STATUS_A}}` |
+| Action | Click '{{action button}}' |
+
+**Expected**: Record transitions to status `{{STATUS_B}}`. {{Notification sent if applicable.}}
+
+---
+
+## Dynamic Data Generation Pattern
+
+For tests that create records and need unique identifiers:
+
+```typescript
+// Changes every 60 seconds. Provides collision-resistant keys without cleanup.
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+// String key
+const entityName = `Test-${EXEC_IDX}`;
+
+// Date (far future avoids prod data overlap)
+const year = 2120 + (EXEC_IDX % 10);
+const month = String((EXEC_IDX % 12) + 1).padStart(2, '0');
+const day = String((EXEC_IDX % 28) + 1).padStart(2, '0');
+const testDate = `${year}-${month}-${day}`;
+```
+
+---
+
+## Data Isolation Rules
+
+1. Each test creates its own data — no shared mutable state between tests
+2. `beforeAll` creates records for the entire suite — provision ≥ N records for N consuming tests
+3. No test teardown required when EXEC_IDX-based names are used (future-dated records do not collide across runs)
+4. If a test modifies shared data (approve/reject), it must create its own record in `beforeAll`
+
+---
+
+## Retired / Deprecated Test Data
+
+| Item | Reason for retirement | Replaced by |
+|------|-----------------------|-------------|
+| {{item}} | Real employee data — PII risk | EXEC_IDX-generated test record |
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Initial creation |

package/templates/specification/05-test-scenarios.md

@@ -0,0 +1,226 @@
+# Test Scenarios — {{MODULE_NAME}}: {{SUBMODULE_NAME}}
+
+> **Module code**: {{MODULE_CODE}} | **Submodule code**: {{SUBMODULE_CODE}}  
+> **Last updated**: YYYY-MM-DD
+
+---
+
+## Summary
+
+| Priority | Total | Automated | Manual | Pending |
+|----------|-------|-----------|--------|---------|
+| P0 | 0 | 0 | 0 | 0 |
+| P1 | 0 | 0 | 0 | 0 |
+| P2 | 0 | 0 | 0 | 0 |
+| P3 | 0 | 0 | 0 | 0 |
+| **Total** | **0** | **0** | **0** | **0** |
+
+---
+
+## Test Cases
+
+---
+
+### TC-{{M}}-{{S}}-001: Unauthenticated access redirects to login
+
+| Field | Value |
+|-------|-------|
+| Priority | P0 |
+| Type | Security |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Preconditions**: User is NOT logged in.
+
+**Steps**:
+1. Navigate directly to `{{QA_BASE_URL}}/{{SUBMODULE_PATH}}`
+
+**Expected result**: Redirected to login page. `{{SUBMODULE_PATH}}` URL is not accessible.
+
+---
+
+### TC-{{M}}-{{S}}-002: Role without permission cannot access submodule
+
+| Field | Value |
+|-------|-------|
+| Priority | P0 |
+| Type | Security |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Preconditions**: Logged in as `{{ROLE_WITHOUT_PERMISSION}}`.
+
+**Steps**:
+1. Navigate to `{{QA_BASE_URL}}/{{SUBMODULE_PATH}}`
+
+**Expected result**: Permission error displayed OR menu item not visible OR redirect to home.
+
+---
+
+### TC-{{M}}-{{S}}-003: List loads correctly for authorized user
+
+| Field | Value |
+|-------|-------|
+| Priority | P0 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Preconditions**: Logged in as `{{AUTHORIZED_ROLE}}`. At least 1 record exists.
+
+**Steps**:
+1. Navigate to `{{QA_BASE_URL}}/{{SUBMODULE_PATH}}`
+
+**Expected result**: Table/grid displays records. Column headers visible. Pagination controls present.
+
+---
+
+### TC-{{M}}-{{S}}-004: Create new record — happy path
+
+| Field | Value |
+|-------|-------|
+| Priority | P0 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Test data**:
+- Name: `Test-{EXEC_IDX}` (unique per run)
+- other fields: valid values per 04-test-data.md
+
+**Steps**:
+1. Click 'New' / 'Create' button
+2. Fill all required fields with valid data
+3. Click 'Save' / 'Submit'
+
+**Expected result**: Success message appears. New record visible in the list.
+
+---
+
+### TC-{{M}}-{{S}}-005: Required field validation — name empty
+
+| Field | Value |
+|-------|-------|
+| Priority | P1 |
+| Type | Negative |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Steps**:
+1. Click 'New' / 'Create' button
+2. Leave required field `{{FIELD_NAME}}` empty
+3. Click 'Save' / 'Submit'
+
+**Expected result**: Validation error shown near the field: "{{exact error message text}}"
+
+---
+
+### TC-{{M}}-{{S}}-006: Duplicate rejection
+
+| Field | Value |
+|-------|-------|
+| Priority | P1 |
+| Type | Negative |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Preconditions**: A record with name "{{duplicate-value}}" already exists.
+
+**Steps**:
+1. Click 'New' / 'Create' button
+2. Enter the same name as an existing record
+3. Click 'Save' / 'Submit'
+
+**Expected result**: System rejects with error: "{{exact duplicate error message}}"
+
+---
+
+### TC-{{M}}-{{S}}-007: Edit existing record
+
+| Field | Value |
+|-------|-------|
+| Priority | P1 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Preconditions**: At least 1 record exists.
+
+**Steps**:
+1. Click 'Edit' on an existing record
+2. Modify `{{FIELD_NAME}}` to a new valid value
+3. Click 'Save'
+
+**Expected result**: Success message. Record in list shows updated value.
+
+---
+
+### TC-{{M}}-{{S}}-008: Delete / deactivate record
+
+| Field | Value |
+|-------|-------|
+| Priority | P1 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Partial |
+
+**Preconditions**: At least 1 deletable record exists.
+
+**Steps**:
+1. Click 'Delete' / 'Deactivate' on an existing record
+2. Confirm the action in the confirmation dialog
+
+**Expected result**: Record is removed from active list or marked as inactive.
+
+---
+
+### TC-{{M}}-{{S}}-009: Export to Excel / CSV
+
+| Field | Value |
+|-------|-------|
+| Priority | P2 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Partial |
+
+**Steps**:
+1. Navigate to list view
+2. Click 'Export' button
+
+**Expected result**: File download initiates. File is non-empty.
+
+---
+
+### TC-{{M}}-{{S}}-010: Search / filter works
+
+| Field | Value |
+|-------|-------|
+| Priority | P2 |
+| Type | Functional |
+| Origin | UI-OBSERVED |
+| Automation | Yes |
+
+**Steps**:
+1. Navigate to list view
+2. Type a known value in the search input
+3. Wait for filter to apply
+
+**Expected result**: Only records matching the search term are shown.
+
+---
+
+## Traceability
+
+| TC ID | Business Rules | Workflow |
+|-------|---------------|---------|
+| TC-{{M}}-{{S}}-001 | — | — |
+| TC-{{M}}-{{S}}-004 | RN-{{M}}-001 | FL-{{M}}-001 |
+| TC-{{M}}-{{S}}-005 | RN-{{M}}-001 | — |
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | Initial creation (N TCs) |

package/templates/test-case.md

@@ -0,0 +1,81 @@
+# Test Case — TC-{{MODULE}}-{{SUB}}-{{NNN}}: {{Title}}
+
+| Field | Value |
+|-------|-------|
+| TC-ID | TC-{{MODULE}}-{{SUB}}-{{NNN}} |
+| ADO WI | #{ADO_WORK_ITEM_ID} (after inject-ado-ids.ps1) |
+| Title | {{Title}} |
+| Module | {{MODULE_NAME}} |
+| Submodule | {{SUBMODULE_NAME}} |
+| Priority | P0 / P1 / P2 / P3 |
+| Type | Functional / Integration / Regression / Smoke |
+| Execution | Manual / Automated / Both |
+| Automation file | `qa/07-automation/e2e/{{module}}/{{submodule}}.spec.ts` (if automated) |
+| Preconditions | {{List required setup — see 04-test-data.md}} |
+| Author | (agent output — reviewed by human) |
+| Last updated | YYYY-MM-DD |
+
+---
+
+## Test Steps
+
+| # | Action | Expected Result |
+|---|--------|----------------|
+| 1 | Navigate to `{{QA_BASE_URL}}/{{path}}` | Login page loads with form visible |
+| 2 | Log in as `{{role}}` (credentials from `.env`) | Dashboard displays; role navigation visible |
+| 3 | Navigate to `{{module}} > {{submodule}}` | Grid/form renders without console errors |
+| 4 | {{Action on primary element}} | {{Observable, measurable outcome}} |
+| 5 | {{Confirm secondary state}} | {{Confirmation visible to end user}} |
+
+---
+
+## Expected Final State
+
+- **UI**: {{What the user sees after completing all steps}}
+- **Data**: {{Observable data change (record count, field value, etc.)}}
+- **Notifications**: {{toastr, SweetAlert, or inline message shown (exact text if known)}}
+- **Side effects**: {{Other systems/modules affected}}
+
+---
+
+## Test Data
+
+| Item | Value |
+|------|-------|
+| User | `{{QA_USER_EMAIL}}` (role: {{ROLE}}) |
+| Input field 1 | `EXEC_IDX` or `{{static-value}}` |
+| Input field 2 | `{{value}}` |
+
+> Use EXEC_IDX for fields that must be unique: `Math.floor(Date.now() / 60_000) % 100_000`
+
+---
+
+## Pass / Fail Criteria
+
+**PASS**: All step assertions met AND final state matches expected.
+
+**FAIL**: Any step assertion failed, unexpected error appeared, or final state differs.
+
+---
+
+## Linked Artifacts
+
+- Spec source: `{{module}}/{{submodule}}/05-test-scenarios.md`
+- Business rules: `{{module}}/{{submodule}}/01-business-rules.md §RN-{{M}}-{{NNN}}`
+- Related defects: DEF-{{NNN}} (if any)
+
+---
+
+## Execution History
+
+| Date | Executor | Environment | Result | Notes |
+|------|----------|-------------|--------|-------|
+| YYYY-MM-DD | | QA | Pass / Fail / Skip | |
+
+---
+
+## Changelog
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 1.0 | YYYY-MM-DD | TC created |