@teevee98/synapse-hub 4.2.4 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (76) hide show
  1. package/.agents/agents/api-engineer.md +1 -1
  2. package/.agents/agents/failure-analyst.md +1 -1
  3. package/.agents/agents/live-explorer.md +1 -1
  4. package/.agents/agents/orchestrator.md +1 -1
  5. package/.agents/agents/perf-engineer.md +1 -1
  6. package/.agents/agents/pom-crafter.md +1 -1
  7. package/.agents/agents/quality-gatekeeper.md +1 -1
  8. package/.agents/agents/test-designer.md +1 -1
  9. package/.agents/agents/test-runner.md +1 -1
  10. package/.agents/rules/author-integrity-guard.md +1 -0
  11. package/.agents/rules/communication-style.md +1 -0
  12. package/.agents/rules/context-engineering.md +1 -0
  13. package/.agents/rules/cypress_rules.md +46 -0
  14. package/.agents/rules/git-push-protocol.md +3 -2
  15. package/.agents/rules/graphify.md +1 -0
  16. package/.agents/rules/lessons-learned.md +11 -12
  17. package/.agents/rules/mandatory-playwright-live.md +8 -10
  18. package/.agents/rules/mobile_appium_rules.md +26 -10
  19. package/.agents/rules/performance_testing_rules.md +26 -5
  20. package/.agents/rules/security_testing_rules.md +21 -15
  21. package/.agents/rules/skill-precedence.md +12 -5
  22. package/.agents/rules/stack-auto-router.md +18 -12
  23. package/.agents/rules/systematic-debugging.md +4 -3
  24. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +71 -2
  25. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +38 -0
  26. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +27 -0
  27. package/.agents/skills/01-web-automation/mobile-maestro-detox-patterns/SKILL.md +134 -0
  28. package/.agents/skills/01-web-automation/mobile-maestro-detox-patterns/examples/sample_flow.yaml +6 -0
  29. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +30 -1
  30. package/.agents/skills/02-test-design/rbt-manual-testing/references/field_validation_checklist.md +13 -1
  31. package/.agents/skills/02-test-design/review-spec/SKILL.md +7 -0
  32. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +15 -0
  33. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +12 -0
  34. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +30 -0
  35. package/.agents/skills/09-ci-and-devops/gitlab-ci-templates/SKILL.md +123 -0
  36. package/.agents/skills/09-ci-and-devops/gitlab-ci-templates/examples/sample_gitlab_ci.yml +17 -0
  37. package/.agents/skills/09-ci-and-devops/jenkins-pipeline-templates/SKILL.md +133 -0
  38. package/.agents/skills/09-ci-and-devops/jenkins-pipeline-templates/examples/Jenkinsfile.example +21 -0
  39. package/.agents/workflows/analyze_requirement_document.md +1 -1
  40. package/.agents/workflows/export_testcases_excel.md +1 -1
  41. package/.agents/workflows/generate_combinatorial_test_data.md +1 -1
  42. package/.agents/workflows/generate_cross_module_test_plan.md +1 -1
  43. package/.agents/workflows/generate_manual_testcases_rbt.md +1 -1
  44. package/.agents/workflows/generate_requirements_from_website.md +1 -1
  45. package/.agents/workflows/generate_testcases_from_requirements.md +1 -1
  46. package/.agents/workflows/test-impact.md +1 -1
  47. package/.agents/workflows/verify.md +1 -1
  48. package/README.en.md +3 -3
  49. package/README.md +3 -3
  50. package/agentskills.json +2 -2
  51. package/docs/ARCHITECTURE.en.md +3 -3
  52. package/docs/ARCHITECTURE.md +2 -2
  53. package/docs/TOOL_CATALOG.md +1 -1
  54. package/package.json +1 -1
  55. package/plugin.json +1 -1
  56. package/scripts/install_global_plugin.ps1 +1 -1
  57. package/scripts/install_global_plugin.sh +1 -1
  58. package/skills_manifest.json +61 -4
  59. package/synapse.config.json +1 -1
  60. package/tools/TOOL_CATALOG.json +1 -1
  61. package/tools/__init__.py +1 -1
  62. package/tools/benchmark_swarm_context.py +1 -1
  63. package/tools/browser_helpers.js +2 -2
  64. package/tools/cli.py +4 -4
  65. package/tools/dashboard_generator.py +8 -8
  66. package/tools/mcp_docx_server.py +1 -1
  67. package/tools/mcp_excel_server.py +1 -1
  68. package/tools/mcp_server.py +1 -1
  69. package/tools/rules_router.py +4 -4
  70. package/tools/setup_project.py +91 -63
  71. package/tools/skill_canonical_digest.py +2 -2
  72. package/tools/task_memory_manager.py +2 -1
  73. package/tools/ui_server.py +1 -1
  74. package/tools/update_sentinel.py +3 -3
  75. package/tools/verify_all.py +1 -1
  76. package/tools/welcome_page.py +2 -2
@@ -72,14 +72,83 @@ All Page Classes **MUST** follow this strict locator hierarchy:
72
72
  | 4 | `CommonCategoryPage` | Common Categories & System Catalogs | Catalogs & Lookups | `addCategory()`, `editCategory()`, `verifyCatalog()` |
73
73
  | 5 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
74
74
 
75
- ### Phase 4: Implementation References
75
+ ### Phase 4: Multi-Stack Architecture & Directory Mapping
76
+
77
+ | Stack / Profile | Page / Screen Directory | Test Script Directory | Default Reports & Artifacts |
78
+ | :--- | :--- | :--- | :--- |
79
+ | **Katalon (`katalon`)** | `Keywords/<namespace>/pages/*.groovy` | `Scripts/**` | `JUnit_Report.xml`, `Screenshots/FAILED_*.png` |
80
+ | **Playwright TS (`playwright`)** | `src/pages/*.page.ts` or `pages/*.ts` | `tests/**/*.spec.ts` | `playwright-report/`, `test-results/` |
81
+ | **Cypress (`cypress`)** | `cypress/pages/*.page.ts` | `cypress/e2e/**/*.cy.(ts \| js)` | `cypress/reports/`, `cypress/screenshots/` |
82
+ | **Pytest (`pytest`)** | `pages/*_page.py` | `tests/**/test_*.py` | `reports/junit.xml`, `screenshots/` |
83
+ | **Appium Mobile (`mobile-appium`)** | `screens/*_screen.(ts \| py)` + `locators/(ios \| android)/` | `tests/**` | `reports/`, `screenshots/` |
84
+
85
+ ### Phase 5: Implementation References
76
86
 
77
87
  - [**Standard Clean POM Methods (`pom_patterns.groovy`)**](references/pom_patterns.groovy): Full implementation of `searchRecord`, `editRecord`, `deleteRecord`, `setCalendarDate`, `selectMultiOptions`.
78
88
  - [**Standard Test Script Template (`standard_test_case.groovy`)**](examples/standard_test_case.groovy): 7-step complete script template from Login -> Create -> Search -> Edit -> Delete.
79
89
  - **Zero-Token XPath Lookup (`tools/lookup_xpath.py`):** Targeted locator retrieval in under 200 tokens.
80
90
  - **Browser Runtime Helper (`tools/browser_helpers.js`):** In-browser validation engine for form audits, safe clicks, and batch verification.
81
91
 
82
- ### Phase 5: Anti-Junk Test Protocol & Authoring Gate
92
+ ### Phase 6: Concurrency & Race Condition Automation Patterns
93
+
94
+ When `Concurrency Gate = ON`:
95
+
96
+ #### Pattern 1: Playwright Multi-Context Isolated Concurrency
97
+ <!-- classification: illustrative -->
98
+ ```typescript
99
+ test('Verify stock contention: exactly 1 purchase succeeds and 1 receives 409 conflict', async ({ browser }) => {
100
+ // Spawn 2 completely isolated browser contexts (different sessions & storage states)
101
+ const contextA = await browser.newContext();
102
+ const contextB = await browser.newContext();
103
+ const pageA = await contextA.newPage();
104
+ const pageB = await contextB.newPage();
105
+
106
+ const checkoutA = new CheckoutPage(pageA);
107
+ const checkoutB = new CheckoutPage(pageB);
108
+
109
+ await Promise.all([
110
+ checkoutA.navigateToItem('ITEM_LAST_STOCK_01'),
111
+ checkoutB.navigateToItem('ITEM_LAST_STOCK_01')
112
+ ]);
113
+
114
+ // Execute simultaneous checkout click in parallel (< 50ms window)
115
+ const [resA, resB] = await Promise.all([
116
+ checkoutA.confirmOrder(),
117
+ checkoutB.confirmOrder()
118
+ ]);
119
+
120
+ // Assert exactly 1 succeeds and 1 encounters conflict without negative stock
121
+ const statuses = [resA.status, resB.status];
122
+ expect(statuses).toContain(200);
123
+ expect(statuses).toContain(409);
124
+
125
+ await contextA.close();
126
+ await contextB.close();
127
+ });
128
+ ```
129
+
130
+ #### Pattern 2: Katalon Studio Parallel Suite / GPars Execution
131
+ <!-- classification: illustrative -->
132
+ ```groovy
133
+ // In Custom Keyword: ConcurrencyKeyword.groovy
134
+ import groovyx.gpars.GParsPool
135
+ import com.kms.katalon.core.annotation.Keyword
136
+
137
+ public class ConcurrencyKeyword {
138
+ @Keyword
139
+ static def executeConcurrentRequests(List<Closure> actions) {
140
+ def results = []
141
+ GParsPool.withPool {
142
+ results = actions.collectParallel { action ->
143
+ action.call()
144
+ }
145
+ }
146
+ return results
147
+ }
148
+ }
149
+ ```
150
+
151
+ ### Phase 7: Anti-Junk Test Protocol & Authoring Gate
83
152
 
84
153
  Before authoring or modifying any automated test script or Page Class, pass this **4-Question Authoring Gate**:
85
154
  1. **Observable Contract:** Does this test protect an observable user/business behavior, invariant, or independent contract?
@@ -125,6 +125,44 @@ await responsePromise;
125
125
  await expect(page.getByText('Order Created')).toBeVisible();
126
126
  ```
127
127
 
128
+ ### Pattern D: Concurrent Session Testing & Race Condition Automation
129
+ <!-- classification: illustrative -->
130
+ ```typescript
131
+ // test/concurrency/race_condition.spec.ts
132
+ import { test, expect } from '@playwright/test';
133
+ import { CheckoutPage } from '../pages/checkout.page';
134
+
135
+ test('Concurrent checkout on last remaining stock enforces zero overselling', async ({ browser }) => {
136
+ // Launch 2 distinct browser contexts with separate isolated sessions
137
+ const contextA = await browser.newContext();
138
+ const contextB = await browser.newContext();
139
+ const pageA = await contextA.newPage();
140
+ const pageB = await contextB.newPage();
141
+
142
+ const checkoutA = new CheckoutPage(pageA);
143
+ const checkoutB = new CheckoutPage(pageB);
144
+
145
+ await Promise.all([
146
+ pageA.goto('/checkout?item=LAST_ITEM_1'),
147
+ pageB.goto('/checkout?item=LAST_ITEM_1')
148
+ ]);
149
+
150
+ // Synchronize rapid simultaneous submission
151
+ const [resA, resB] = await Promise.all([
152
+ checkoutA.completeOrder(),
153
+ checkoutB.completeOrder()
154
+ ]);
155
+
156
+ // Exactly 1 order succeeds (200/201), concurrent attempt is rejected (409 Conflict)
157
+ const outcomes = [resA, resB];
158
+ expect(outcomes.filter(o => o.status === 201).length).toBe(1);
159
+ expect(outcomes.filter(o => o.status === 409).length).toBe(1);
160
+
161
+ await contextA.close();
162
+ await contextB.close();
163
+ });
164
+ ```
165
+
128
166
  ---
129
167
 
130
168
  ### Parallel Sharding & CI/CD Governance
@@ -98,6 +98,33 @@ katalonc -noSplash -runMode=console \
98
98
 
99
99
  ---
100
100
 
101
+ ### Katalon Mobile Automation Architecture (Katalon Studio & KRE)
102
+
103
+ Katalon Studio provides native keywords for Android and iOS mobile test execution alongside Web and API:
104
+
105
+ 1. **Native Mobile Keywords (`Mobile.*`):**
106
+ - Use built-in mobile keywords: `Mobile.startExistingApplication(appId)`, `Mobile.tap(findTestObject('Mobile/btn_Submit'), 10)`, `Mobile.setText(findTestObject('Mobile/input_Username'), text, 10)`, `Mobile.verifyElementExist(findTestObject('Mobile/lbl_Success'), 15)`.
107
+ - Never mix Web `WebUI.*` keywords in mobile scripts; keep `Mobile.*` encapsulated in Page Classes (`Keywords/<namespace>/pages/*_mobile.groovy`).
108
+ 2. **Mobile Object Repository Hierarchy:**
109
+ - Store mobile test objects strictly under `Object Repository/Mobile/<platform>/<screen>/` (e.g. `Object Repository/Mobile/Android/Login/btn_Submit`).
110
+ - Locator preference: Accessibility ID (`content-desc` / `accessibilityIdentifier`), Android resource-id, iOS predicate string. Strictly avoid positional index XPath.
111
+ 3. **KRE Mobile CLI Execution:**
112
+ <!-- classification: illustrative -->
113
+ ```bash
114
+ # Run Katalon Mobile Test Suite on connected Android device / emulator via KRE
115
+ katalonc -noSplash -runMode=console \
116
+ -projectPath="$(pwd)/project.prj" \
117
+ -retry=0 \
118
+ -testSuitePath="Test Suites/TS_Mobile_Smoke" \
119
+ -browserType="Android" \
120
+ -deviceId="emulator-5554" \
121
+ -appId="com.example.app" \
122
+ -executionProfile="default" \
123
+ -apiKey="$KATALON_API_KEY"
124
+ ```
125
+
126
+ ---
127
+
101
128
  ### Definition of Done (DoD)
102
129
 
103
130
  1. **Exit Code = 0:** Runner completes cleanly without runtime crash.
@@ -0,0 +1,134 @@
1
+ ---
2
+ name: mobile-maestro-detox-patterns
3
+ description: "Declarative mobile UI test patterns for Maestro flows and Detox gray-box automation on React Native and native mobile apps. Use when authoring declarative mobile flows or fast gray-box mobile tests."
4
+ category: test_automation_and_execution
5
+ version: "1.0.0"
6
+ policies:
7
+ network: localhost-only
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
10
+ ---
11
+ # Mobile Maestro & Detox Testing Patterns
12
+
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Use when authoring or executing declarative mobile UI test flows with Maestro (`.yaml`), configuring Detox gray-box automation for React Native applications (`.detoxrc.js`), establishing mobile test synchronization without flakiness, or running fast simulator/emulator smoke tests.
20
+ - **Activation Scope:**
21
+ - Native iOS & Android mobile apps.
22
+ - React Native and Flutter mobile applications.
23
+ - Declarative Maestro automation flows (`.maestro/*.yaml`).
24
+ - Detox gray-box E2E suites (`e2e/*.test.ts`).
25
+
26
+ ---
27
+
28
+ ## 2. Non-Goals & Boundary Constraints
29
+
30
+ - **What NOT to do:**
31
+ - Do NOT use hardcoded coordinate taps (`tap: { x: 100, y: 200 }`); always target semantic labels, testIDs, or accessibility identifiers.
32
+ - Do NOT use static sleeps in Maestro flows; rely on Maestro automatic element waiting and `extendedWaitUntil`.
33
+ - Do NOT commit mobile app binaries (`.ipa`, `.apk`) to the git repository.
34
+ - **Sibling Skill Boundaries:**
35
+ - `mobile-appium-som`: Handles enterprise Appium Screen Object Model (SOM) for iOS/Android.
36
+ - `mobile-maestro-detox-patterns` (this skill): Handles declarative Maestro YAML flows and Detox gray-box testing.
37
+
38
+ ---
39
+
40
+ ## 3. Ordered Execution Workflow
41
+
42
+ ### Phase 1: Maestro Declarative Flow Pattern
43
+
44
+ Maestro executes declarative YAML test flows with built-in tolerance for animations and network delays.
45
+
46
+ <!-- classification: illustrative -->
47
+ ```yaml
48
+ # .maestro/login_checkout_flow.yaml
49
+ appId: com.example.app
50
+ ---
51
+ - launchApp:
52
+ clearState: true
53
+
54
+ # Assert initial screen state
55
+ - assertVisible: "Welcome Back"
56
+
57
+ # Input credentials using accessible labels or testIDs
58
+ - tapOn: "Email Address"
59
+ - inputText: "tester.auto@example.com"
60
+
61
+ - tapOn: "Password"
62
+ - inputText: "SecurePass123!"
63
+
64
+ - hideKeyboard
65
+
66
+ - tapOn:
67
+ id: "btn_login"
68
+
69
+ # Dynamic smart synchronization
70
+ - extendedWaitUntil:
71
+ visible: "Product Catalog"
72
+ timeout: 10000
73
+
74
+ # Perform search and add to cart
75
+ - tapOn: "Search Products"
76
+ - inputText: "Wireless Headphones"
77
+ - tapOn: "Add to Cart"
78
+
79
+ - assertVisible: "Item added to cart"
80
+ ```
81
+
82
+ ### Phase 2: Detox Gray-Box Automation Pattern
83
+
84
+ Detox runs in-process synchronization with the React Native bridge to eliminate timing flakiness.
85
+
86
+ <!-- classification: illustrative -->
87
+ ```typescript
88
+ // e2e/auth_flow.e2e.ts
89
+ import { by, device, element, expect } from 'detox';
90
+
91
+ describe('Authentication Journey', () => {
92
+ beforeAll(async () => {
93
+ await device.launchApp({ newInstance: true });
94
+ });
95
+
96
+ beforeEach(async () => {
97
+ await device.reloadReactNative();
98
+ });
99
+
100
+ it('should authenticate user and display home dashboard', async () => {
101
+ await expect(element(by.id('login_screen'))).toBeVisible();
102
+
103
+ await element(by.id('input_email')).typeText('tester.auto@example.com');
104
+ await element(by.id('input_password')).typeText('SecurePass123!\n');
105
+
106
+ await element(by.id('btn_submit')).tap();
107
+
108
+ await expect(element(by.text('Dashboard'))).toBeVisible();
109
+ });
110
+ });
111
+ ```
112
+
113
+ ### Phase 3: Mobile Selector Hierarchy
114
+
115
+ 1. **Test ID / Accessibility ID:** `id: "btn_submit"` (React Native `testID`, Android `content-desc`, iOS `accessibilityIdentifier`).
116
+ 2. **Visible Text / Label:** `tapOn: "Complete Purchase"`.
117
+ 3. **Regex Pattern:** `tapOn: { text: "Order #\\d+" }`.
118
+
119
+ ---
120
+
121
+ ## 4. Verification Points & DoD
122
+
123
+ 1. **Declarative Syntax:** Maestro YAML flows and Detox specs pass syntax and linter checks.
124
+ 2. **Accessibility-First:** 100% of selectors target testIDs, accessibility labels, or semantic text.
125
+ 3. **Zero Static Sleeps:** Flow execution relies entirely on native gray-box synchronization or `extendedWaitUntil`.
126
+ 4. **Idempotency:** Test runs start with isolated app state (`clearState: true` or `newInstance: true`).
127
+
128
+ ---
129
+
130
+ ## 5. Handoff Protocol
131
+
132
+ - **Deliverables:** Declarative `.maestro/*.yaml` flows, Detox E2E specs, and configuration blueprints.
133
+ - **Next Subagent:** Pass to `test-runner` for simulator/emulator execution or `quality-gatekeeper` for acceptance.
134
+ - **Output Format:** Clean YAML/TypeScript adhering to mobile automation standards.
@@ -0,0 +1,6 @@
1
+ appId: com.example.app
2
+ ---
3
+ - launchApp
4
+ - tapOn: "Login"
5
+ - inputText: "user@example.com"
6
+ - assertVisible: "Dashboard"
@@ -110,9 +110,38 @@ flowchart TD
110
110
  - **Medium:** CRUD operations, table filtering, search, pagination.
111
111
  - **Low:** Cosmetic UI, tooltips, static informational content.
112
112
  - Non-Functional & Resilience Scenarios:
113
- - **Double Submit / Race Conditions:** Rapid consecutive clicks on submit, concurrent edits.
114
113
  - **Network Interruption:** Connection drops mid-transaction.
115
114
  - **Browser Navigation:** Browser Back/Forward or page refresh during multi-step wizards.
115
+
116
+ #### Conditional Concurrency & Race Condition Matrix
117
+ > **Activation Rule:** Evaluate the feature against the *Concurrency Gate* first.
118
+ > - **AUTO-ENABLE** only if the feature involves: financial transactions/balances, limited inventory/bookings/vouchers, multi-step state approvals, shared multi-user edits, or async webhooks/retries.
119
+ > - **AUTO-SKIP** for read-only views, static pages, or single-user non-transactional CRUD forms (log `Concurrency Gate: SKIPPED — non-contentious feature`).
120
+
121
+ When `Concurrency Gate = ON`, generate targeted cases for applicable vectors:
122
+ 1. **Double-Submit / Rapid Click:** Trigger submit/pay/create twice within <300ms (UI click or duplicate POST) -> verify only 1 record/charge is created and button disables or backend rejects duplicate.
123
+ 2. **Resource Contention (Last-Item / Overselling):** Two concurrent sessions claim the last available stock/slot/voucher at the exact same timestamp -> verify exactly 1 succeeds and 1 receives a clear conflict error (`409 Conflict` / out-of-stock message), with zero negative balance/stock.
124
+ 3. **Stale State / Optimistic Locking:** User A and User B open the same record; User A saves first, then User B saves outdated data -> verify system blocks silent overwrite (version/ETag check) or prompts merge/refresh.
125
+ 4. **Retry & Idempotency:** Simulate network timeout after server commits, then retry with the same `Idempotency-Key` -> verify server returns the original result without creating duplicate records.
126
+
127
+ #### Conditional ISTQB Advanced Test Design Techniques
128
+ In addition to Equivalence Partitioning (EP), Boundary Value Analysis (BVA), and Exploratory Testing, conditionally activate targeted formal techniques:
129
+
130
+ | Technique | Auto-Activation Rule | Mandatory Generation Rule |
131
+ | :--- | :--- | :--- |
132
+ | **Decision Table** | Business logic has **≥ 2 combined conditions** governing outputs (pricing, discounts, loan limits, RBAC permissions). | Enumerate combinatorial matrix of condition states (`True/False` or distinct levels) covering valid combinations, conflicting rules, and precedence ordering. |
133
+ | **State Transition** | Entities with an **explicit lifecycle or finite states** (`Draft -> Pending -> Approved -> Cancelled / Refunded`). | Generate valid sequential lifecycle transitions and invalid/illegal leapfrog or backwards transitions that must be blocked. |
134
+ | **Pairwise / All-Pairs** | Screens or APIs with **≥ 3 independent combinatorial selection/filter fields** (e.g. OS × Browser × Payment × Currency). | Apply orthogonal/all-pairs combinatorial reduction to test 100% of two-way parameter interactions instead of combinatorial explosion. |
135
+
136
+ #### Conditional Data Integrity Checklist
137
+ > **Activation Rule:** AUTO-ENABLE only for features with DB mutations, multi-step transactions, financial/numeric calculations, or file import/export. AUTO-SKIP for static/read-only views.
138
+
139
+ When `Data Integrity Gate = ON`, generate targeted cases for applicable vectors:
140
+ 1. **Atomicity & Rollback:** Simulate a failure mid-transaction (e.g., balance deducted / stock decremented, then order creation fails) -> verify full DB rollback with zero orphaned records or balance drift.
141
+ 2. **3-Tier Consistency (UI ↔ API ↔ DB):** After save/update, reload UI (F5), call GET API, and verify DB state -> confirm 100% match across UTF-8 Vietnamese text, currency rounding, and timezone formatting.
142
+ 3. **Referential Integrity / Soft Delete:** Delete or archive a parent record referenced by child data (e.g., product linked to existing orders) -> verify historical child records remain intact and render without errors.
143
+ 4. **Partial Update Safety & Audit Trail:** Update a single field (e.g., display name) -> verify unrelated fields are not wiped/reset (`PATCH` vs `PUT`), `created_at` stays immutable, and `updated_at` / audit log updates accurately.
144
+
116
145
  - Field-Level Validation: Generate dedicated test cases for each input field.
117
146
 
118
147
  ### Stage 6: Template Mapping & Automation Metadata
@@ -24,6 +24,18 @@ Comprehensive boundary values, negative test vectors, and security edge cases ac
24
24
 
25
25
  ## Non-Functional & Resilience Invariants
26
26
 
27
- - **Double Submit / Race Conditions:** Rapid consecutive clicks on submit; concurrent edits across browser tabs.
27
+ ### 1. Concurrency & Race Condition Verification
28
+ - **Double Submit / Rapid Click:** Trigger submit/pay/create twice within <300ms (UI click or duplicate POST) -> verify only 1 record/charge is created and button disables or backend rejects duplicate.
29
+ - **Resource Contention (Last-Item / Overselling):** Two concurrent sessions claim the last available stock/slot/voucher at the exact same timestamp -> verify exactly 1 succeeds and 1 receives a clear conflict error (`409 Conflict` / out-of-stock message), with zero negative balance/stock.
30
+ - **Stale State / Optimistic Locking:** User A and User B open the same record; User A saves first, then User B saves outdated data -> verify system blocks silent overwrite (version/ETag check) or prompts merge/refresh.
31
+ - **Retry & Idempotency:** Simulate network timeout after server commits, then retry with the same `Idempotency-Key` -> verify server returns the original result without creating duplicate records.
32
+
33
+ ### 2. Data Integrity & Database Safety
34
+ - **Atomicity & Rollback:** Simulate a failure mid-transaction (e.g., balance deducted / stock decremented, then order creation fails) -> verify full DB rollback with zero orphaned records or balance drift.
35
+ - **3-Tier Consistency (UI ↔ API ↔ DB):** After save/update, reload UI (F5), call GET API, and verify DB state -> confirm 100% match across UTF-8 Vietnamese text, currency rounding, and timezone formatting.
36
+ - **Referential Integrity / Soft Delete:** Delete or archive a parent record referenced by child data (e.g., product linked to existing orders) -> verify historical child records remain intact and render without errors.
37
+ - **Partial Update Safety & Audit Trail:** Update a single field (e.g., display name) -> verify unrelated fields are not wiped/reset (`PATCH` vs `PUT`), `created_at` stays immutable, and `updated_at` / audit log updates accurately.
38
+
39
+ ### 3. Network & Session Resilience
28
40
  - **Network Interruption:** Connection drops mid-transaction; slow 3G timeout handling.
29
41
  - **Browser Navigation:** Browser Back/Forward or page refresh during multi-step wizards without data loss.
@@ -78,6 +78,13 @@ Order of evaluation: **System Boundaries -> Dynamic Data & Teardown -> Assertion
78
78
  - Concrete Page Class mappings or API endpoint routes.
79
79
  - Clean POM Flat Architecture compliance (locators belongs in Page Classes, not test scripts).
80
80
 
81
+ #### Conditional Gate — Vector 6: Concurrency & Race Condition Readiness (Auto-Triggered Only)
82
+ - **Trigger:** Activate ONLY when the spec involves financial/balance changes, limited stock/slots/vouchers, shared multi-user mutations, state-machine transitions, or retryable APIs. Skip automatically for read-only or simple single-user CRUD specs.
83
+ - **Checks when active:**
84
+ - Does the spec define expected behavior on **double-submit** or duplicate requests (UI debounce + backend idempotency)?
85
+ - Does the spec specify conflict resolution when **2+ actors mutate the same resource** (e.g., `409 Conflict`, optimistic locking, or atomic decrement)?
86
+ - If missing in a high-risk transactional spec, flag as `[CONCURRENCY GAP]` before approving the spec for test script generation.
87
+
81
88
  ---
82
89
 
83
90
  ### Autonomous Execution Workflow
@@ -85,6 +85,21 @@ Every negative test case must assert two distinct layers:
85
85
 
86
86
  ---
87
87
 
88
+ ### Concurrency & Idempotency API Verification
89
+
90
+ For transactional or state-changing endpoints (`POST`, `PUT`, `PATCH`, `DELETE`):
91
+ 1. **Burst / Parallel Request Testing:**
92
+ - Execute concurrent bursts of the exact same request using `Promise.all([req1, req2])` or parallel HTTP clients with 0ms delay.
93
+ - For limited inventory/financial claims: assert exactly 1 request returns `200/201` and subsequent concurrent requests return `409 Conflict` or domain validation errors (`422 Unprocessable Entity`), with zero negative inventory/balance drift.
94
+ 2. **Idempotency-Key Validation:**
95
+ - Transmit duplicate requests carrying the identical `Idempotency-Key` header.
96
+ - Assert server returns the original processed outcome without re-executing business side effects or duplicating records.
97
+ 3. **Optimistic Locking (`ETag` / `If-Match`):**
98
+ - Transmit conflicting updates with stale ETag / version tokens.
99
+ - Assert server rejects stale writes with `412 Precondition Failed` or `409 Conflict`.
100
+
101
+ ---
102
+
88
103
  ### Automated Execution via Tooling
89
104
 
90
105
  Agent can automatically invoke `tools/generate_api_matrix.py` and `tools/export_postman_collection.py`:
@@ -61,6 +61,18 @@ flowchart LR
61
61
 
62
62
  ---
63
63
 
64
+ ### Multi-Stack Architecture & Diagnostic Artifact Mapping
65
+
66
+ | Stack / Profile | Target Page / Screen Classes | Test Scripts Location | Primary Error Logs & Artifacts |
67
+ | :--- | :--- | :--- | :--- |
68
+ | **Katalon (`katalon`)** | `Keywords/<namespace>/pages/*.groovy` | `Scripts/**` | `Reports/**/JUnit_Report.xml`, `Screenshots/FAILED_*.png` |
69
+ | **Playwright TS (`playwright`)** | `src/pages/*.page.ts` or `pages/*.ts` | `tests/**/*.spec.ts` | `playwright-report/`, `test-results/**/trace.zip`, `.png` |
70
+ | **Cypress (`cypress`)** | `cypress/pages/*.page.ts` | `cypress/e2e/**/*.cy.(ts \| js)` | `cypress/screenshots/**`, `cypress/videos/**` |
71
+ | **Pytest (`pytest`)** | `pages/*_page.py` | `tests/**/test_*.py` | `reports/junit.xml`, `screenshots/**` |
72
+ | **Appium Mobile (`mobile-appium`)** | `screens/*_screen.(ts \| py)` | `tests/**` | Appium server log, device logcat, failure screenshot |
73
+
74
+ ---
75
+
64
76
  ### Dynamic Module & Page Class Mapping Architecture
65
77
 
66
78
  | Functional Module Category | Target Page Class to Heal | Common Failure Vector | Recommended Auto-Heal Strategy |
@@ -50,6 +50,10 @@ policies:
50
50
  - Negative numbers, extreme floats, zero, boundary integer limits (`2^31 - 1`, `2^63 - 1`, `Number.MAX_SAFE_INTEGER`).
51
51
  3. **Domain-Specific Constraints:**
52
52
  - Tax IDs, phone numbers, email RFC formats, and GIS coordinates (e.g., non-overlapping closed polygons).
53
+ 4. **PII Safety Invariant:**
54
+ - Never copy or mirror real customer production data (PII) into test fixtures. All synthesized entities must use purely artificial data with identifiable prefixes (`AUTO_`, `PERF_AUTO_`, `AUTO_RACE_`) paired with automated teardown cleanup hooks.
55
+ 5. **Vietnam Locale Standards:**
56
+ - Support national telecom prefixes (`03x`, `05x`, `07x`, `08x`, `09x`), 12-digit Citizen Identity Card (CCCD) format, full UTF-8 Vietnamese diacritics, and VND currency conventions (`100.000 ₫` / `100.000 VND`).
53
57
 
54
58
  ---
55
59
 
@@ -105,6 +109,32 @@ export function generateValidPolygon(centerLat = 21.0285, centerLng = 105.8542,
105
109
  }
106
110
  ```
107
111
 
112
+ ### Recipe D: Vietnamese Locale Test Data
113
+ <!-- classification: illustrative -->
114
+ ```typescript
115
+ export class VietnamDataFactory {
116
+ static validPhone(): string {
117
+ const prefixes = ['032', '038', '039', '056', '070', '079', '081', '085', '090', '091', '098'];
118
+ const prefix = prefixes[Math.floor(Math.random() * prefixes.length)];
119
+ const suffix = Math.floor(1000000 + Math.random() * 9000000).toString().substring(0, 7);
120
+ return `${prefix}${suffix}`;
121
+ }
122
+
123
+ static validCCCD(): string {
124
+ // 12-digit format: 001 (Hanoi) + 0 (male, 20th century) + 98 (birth year) + 6 random digits
125
+ const province = '001';
126
+ const genderCentury = '0';
127
+ const birthYear = '98';
128
+ const randomSeq = Math.floor(100000 + Math.random() * 900000).toString();
129
+ return `${province}${genderCentury}${birthYear}${randomSeq}`;
130
+ }
131
+
132
+ static formattedVND(amount: number): string {
133
+ return new Intl.NumberFormat('vi-VN', { style: 'currency', currency: 'VND' }).format(amount);
134
+ }
135
+ }
136
+ ```
137
+
108
138
  ---
109
139
 
110
140
  ### Edge-Case Fuzzing & Input Sanitization Suite (`tools/fuzz_payloads.py`)
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: gitlab-ci-templates
3
+ description: "Production GitLab CI/CD pipeline blueprints for test automation, Playwright matrix sharding, Katalon KRE execution, and artifact retention governance. Use when wiring test pipelines or quality gates into GitLab CI."
4
+ category: architecture_and_analysis
5
+ version: "1.0.0"
6
+ policies:
7
+ network: none
8
+ shell: none
9
+ filesystem: workspace-sandbox
10
+ ---
11
+ # GitLab CI/CD Templates for Test Automation
12
+
13
+ > **Author Attribution & MIT License Guard:** Synapse Hub is open-source software created by **Thế Vị (@TeeVee98)** (<https://github.com/TeeVee98/Synapse-Hub>) under the MIT License.
14
+
15
+ ---
16
+
17
+ ## 1. Trigger & Activation
18
+
19
+ - **Trigger Clause:** Use when configuring GitLab CI/CD pipelines (`.gitlab-ci.yml`), creating parallel test execution matrices, setting up Katalon Runtime Engine (KRE) jobs, configuring dependency caching, or establishing artifact retention policies for test reports.
20
+ - **Activation Scope:**
21
+ - Automated test suites (Playwright, Cypress, Katalon, Pytest).
22
+ - Parallel matrix sharding across GitLab runners.
23
+ - Quality Gate Definition of Done (DoD) verification.
24
+
25
+ ---
26
+
27
+ ## 2. Non-Goals & Boundary Constraints
28
+
29
+ - **What NOT to do:**
30
+ - Do NOT hardcode credentials, private tokens, or license keys in `.gitlab-ci.yml`; inject exclusively via GitLab CI/CD masked/protected variables (`$KATALON_API_KEY`, `$CI_JOB_TOKEN`).
31
+ - Do NOT configure unlimited artifact retention; always set `expire_in: 7 days` (or max 14 days) to avoid saturating runner storage.
32
+ - Do NOT leave runner processes hanging; always specify job-level `timeout: 30m`.
33
+ - **Sibling Skill Boundaries:**
34
+ - `github-actions-templates`: Owns GitHub Actions workflows (`.github/workflows/*.yml`).
35
+ - `gitlab-ci-templates` (this skill): Owns GitLab CI/CD pipeline definitions (`.gitlab-ci.yml`).
36
+ - `jenkins-pipeline-templates`: Owns Jenkins Declarative Pipelines (`Jenkinsfile`).
37
+
38
+ ---
39
+
40
+ ## 3. Ordered Execution Workflow
41
+
42
+ ### Phase 1: Pipeline Configuration & Parallel Sharding
43
+
44
+ Author or update the `.gitlab-ci.yml` pipeline configuration.
45
+
46
+ <!-- classification: illustrative -->
47
+ ```yaml
48
+ stages:
49
+ - test
50
+ - report
51
+
52
+ default:
53
+ interruptible: true
54
+ timeout: 30m
55
+
56
+ # Cache dependencies across pipeline runs
57
+ .npm-cache: &npm-cache
58
+ cache:
59
+ key:
60
+ files:
61
+ - package-lock.json
62
+ paths:
63
+ - .npm/
64
+ policy: pull-push
65
+
66
+ # Playwright Parallel Matrix Sharding
67
+ test:playwright:
68
+ stage: test
69
+ image: mcr.microsoft.com/playwright:v1.49.0-noble
70
+ <<: *npm-cache
71
+ parallel: 4
72
+ before_script:
73
+ - npm ci --cache .npm --prefer-offline
74
+ script:
75
+ - npx playwright test --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}
76
+ artifacts:
77
+ when: always
78
+ expire_in: 7 days
79
+ paths:
80
+ - playwright-report/
81
+ - test-results/
82
+ reports:
83
+ junit: test-results/results.xml
84
+
85
+ # Katalon Runtime Engine (KRE) Headless Execution
86
+ test:katalon:
87
+ stage: test
88
+ image: katalonstudio/katalon:latest
89
+ rules:
90
+ - if: '$KATALON_API_KEY'
91
+ script:
92
+ - katalonc -noSplash -runMode=console -projectPath="$(pwd)/project.prj" -retry=0 -testSuitePath="Test Suites/TS_Smoke" -browserType="Chrome (headless)" -executionProfile="default" -apiKey="$KATALON_API_KEY"
93
+ artifacts:
94
+ when: always
95
+ expire_in: 7 days
96
+ paths:
97
+ - Reports/
98
+ reports:
99
+ junit: Reports/**/JUnit_Report.xml
100
+ ```
101
+
102
+ ### Phase 2: Artifact & Storage Governance
103
+
104
+ 1. **Selective Artifact Retention:** Always set `artifacts.expire_in: 7 days` for test traces, screenshots, and videos.
105
+ 2. **Native JUnit Integration:** Map test result XML to `artifacts.reports.junit` for GitLab native test report parsing and MR telemetry.
106
+ 3. **Fail-Fast & Timeout Controls:** Enforce `default.interruptible: true` to auto-cancel stale pipelines on push, and set explicit job timeouts.
107
+
108
+ ---
109
+
110
+ ## 4. Verification Points & DoD
111
+
112
+ 1. **Syntax Validation:** `.gitlab-ci.yml` passes GitLab CI Lint API validation.
113
+ 2. **Secret Protection:** Zero hardcoded API keys, passwords, or personal access tokens in pipeline YAML.
114
+ 3. **Artifact Expiry:** Every job publishing artifacts defines an explicit `expire_in` policy ($\le 14$ days).
115
+ 4. **Clean Execution:** All jobs complete with exit code 0 or cleanly capture JUnit XML on test assertion failure.
116
+
117
+ ---
118
+
119
+ ## 5. Handoff Protocol
120
+
121
+ - **Deliverables:** Production-ready `.gitlab-ci.yml` definitions and reusable job templates.
122
+ - **Next Subagent:** Pass to `test-runner` for runner validation or `quality-gatekeeper` for CI/CD acceptance.
123
+ - **Output Format:** Valid GitLab CI/CD YAML specification adhering to enterprise security baselines.
@@ -0,0 +1,17 @@
1
+ stages:
2
+ - test
3
+
4
+ test_playwright:
5
+ stage: test
6
+ image: mcr.microsoft.com/playwright:v1.49.0-noble
7
+ parallel: 2
8
+ script:
9
+ - npm ci
10
+ - npx playwright test --shard=${CI_NODE_INDEX}/${CI_NODE_TOTAL}
11
+ artifacts:
12
+ when: always
13
+ expire_in: 7 days
14
+ paths:
15
+ - playwright-report/
16
+ reports:
17
+ junit: test-results/results.xml