@teevee98/synapse-hub 4.1.4 → 4.2.1

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 (133) hide show
  1. package/.agents/rules/git-push-protocol.md +2 -2
  2. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +52 -3
  3. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +55 -5
  4. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +62 -67
  5. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +54 -4
  6. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +62 -12
  7. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +55 -8
  8. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +60 -12
  9. package/.agents/skills/01-web-automation/mobile-appium-som/examples/BaseScreen.java +2 -2
  10. package/.agents/skills/01-web-automation/mobile-appium-som/examples/LoginScreen.java +2 -2
  11. package/.agents/skills/01-web-automation/mobile-appium-som/examples/TC_MobileLogin.java +2 -2
  12. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +54 -91
  13. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +59 -11
  14. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +50 -4
  15. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +55 -9
  16. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +55 -9
  17. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +55 -8
  18. package/.agents/skills/02-test-design/review-spec/SKILL.md +50 -6
  19. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +50 -4
  20. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +56 -5
  21. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +53 -7
  22. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +86 -36
  23. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +54 -6
  24. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +50 -6
  25. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +50 -3
  26. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +63 -14
  27. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +51 -5
  28. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +54 -4
  29. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +51 -5
  30. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +53 -6
  31. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +54 -8
  32. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +60 -24
  33. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +52 -6
  34. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +56 -10
  35. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +58 -12
  36. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +58 -12
  37. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +53 -5
  38. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +56 -5
  39. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +53 -4
  40. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +58 -5
  41. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +57 -11
  42. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +83 -34
  43. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  44. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +55 -10
  45. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +49 -6
  46. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +52 -7
  47. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +55 -10
  48. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +51 -5
  49. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +54 -17
  50. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  51. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +50 -4
  52. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +53 -7
  53. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +50 -4
  54. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +58 -13
  55. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +51 -5
  56. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +57 -10
  57. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +50 -4
  58. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +50 -4
  59. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +55 -9
  60. package/.cursor/rules/synapse-qa.mdc +20 -7
  61. package/.cursorrules +19 -5
  62. package/.windsurfrules +18 -3
  63. package/AGENTS.md +51 -59
  64. package/CLAUDE.md +38 -24
  65. package/LICENSE +5 -5
  66. package/NOTICE +1 -1
  67. package/README.en.md +4 -4
  68. package/README.md +4 -4
  69. package/agentskills.json +1 -1
  70. package/docs/ARCHITECTURE.en.md +2 -2
  71. package/docs/ARCHITECTURE.md +11 -2
  72. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  73. package/docs/CLI_REFERENCE.en.md +6 -4
  74. package/docs/CLI_REFERENCE.md +1 -1
  75. package/docs/CONTRIBUTING.en.md +1 -1
  76. package/docs/CONTRIBUTING.md +2 -2
  77. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  78. package/docs/TOOL_CATALOG.md +6 -2
  79. package/docs/research/agent_skill_training_analysis.md +1 -1
  80. package/package.json +1 -1
  81. package/plugin.json +1 -1
  82. package/skills_manifest.json +320 -55
  83. package/synapse.config.json +1 -1
  84. package/templates/ai_bridges/CLAUDE.md +29 -26
  85. package/templates/ai_bridges/copilot-instructions.md +14 -5
  86. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  87. package/templates/ai_bridges/windsurfrules +14 -3
  88. package/templates/ui/index.html +2 -2
  89. package/tools/TOOLS_RUNBOOK.md +1 -1
  90. package/tools/TOOL_CATALOG.json +63 -3
  91. package/tools/__init__.py +1 -1
  92. package/tools/api_fuzzer.py +447 -132
  93. package/tools/author_integrity.py +121 -11
  94. package/tools/benchmark_swarm_context.py +130 -22
  95. package/tools/break_ui_generator.py +233 -0
  96. package/tools/browser_helpers.js +2 -2
  97. package/tools/check_version_sync.py +18 -50
  98. package/tools/cli.py +110 -19
  99. package/tools/core/bm25_retriever.py +218 -0
  100. package/tools/core/i18n.py +5 -5
  101. package/tools/core/provider_usage_adapter.py +383 -0
  102. package/tools/core/token_estimator.py +81 -15
  103. package/tools/count_tokens.py +7 -2
  104. package/tools/coverage_reporter.py +245 -0
  105. package/tools/dashboard_generator.py +8 -8
  106. package/tools/db_sandbox.py +290 -9
  107. package/tools/distill_log.py +1 -1
  108. package/tools/distill_skill.py +206 -0
  109. package/tools/git_pre_commit_guard.py +202 -1
  110. package/tools/humanize_linter.py +3 -0
  111. package/tools/mcp_docx_server.py +1 -1
  112. package/tools/mcp_excel_server.py +1 -1
  113. package/tools/mcp_server.py +104 -16
  114. package/tools/micro_mutator.py +114 -15
  115. package/tools/pentest_scope_guard.py +674 -58
  116. package/tools/perf/benchmark_perf_runner.py +42 -0
  117. package/tools/project_state.py +29 -5
  118. package/tools/reversible_sandbox.py +58 -13
  119. package/tools/rules_router.py +473 -60
  120. package/tools/security_scanner.py +80 -0
  121. package/tools/senior_code_review.py +14 -0
  122. package/tools/skill_canonical_digest.py +302 -0
  123. package/tools/skill_profiles.py +77 -7
  124. package/tools/slide_deck_exporter.py +477 -0
  125. package/tools/sync_agent_rules.py +187 -61
  126. package/tools/sync_skills_manifest.py +166 -0
  127. package/tools/task_memory_manager.py +275 -0
  128. package/tools/ui_server.py +3 -1
  129. package/tools/update_sentinel.py +3 -3
  130. package/tools/validate_host_interop.py +485 -0
  131. package/tools/validate_skills_schema.py +575 -0
  132. package/tools/verify_all.py +668 -44
  133. package/tools/welcome_page.py +2 -2
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: lam-script-generator
3
3
  description: "Transform user stories and acceptance criteria into Clean POM automation scripts. Use when the user provides a user story, acceptance criteria, or requirement document that must become a runnable script."
4
+ category: test_automation_and_execution
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: none
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # LAM Script Generator — Large Action Model for Test Automation
7
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:** Transform user stories and acceptance criteria into Clean POM automation scripts. Use when the user provides a user story, acceptance criteria, or requirement document that must become a runnable script.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `lam-script-generator`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT generate raw XPaths, CSS selectors, or coordinate clicks in test scripts.
28
+ - Do NOT hallucinate non-existent Page Classes; query existing methods from project state and AST maps.
29
+ - Do NOT generate tests that consume runtime LLM tokens during CI/CD replays.
30
+ - **Sibling Skill Boundaries:**
31
+ - clean-pom-crafter designs Page Classes; lam-script-generator consumes User Stories to synthesize workflow test scripts.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Inspired by the **LaVague AI Web Agent & Large Action Model (LAM)** framework, this skill bridges the gap between natural language requirements (User Stories, Acceptance Criteria) and durable, deterministic automation code conforming to Clean POM Flat Architecture.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. The Dual-Engine LAM Architecture
41
+ ### The Dual-Engine LAM Architecture
13
42
 
14
43
  ```mermaid
15
44
  flowchart TD
@@ -17,7 +46,7 @@ flowchart TD
17
46
 
18
47
  WorldModel --> ActionEngine["<b>2. Action Engine (Code Generator)</b><br/>• Queries Page Classes via Knowledge Graph<br/>• Maps action to existing methods: LoginPage.login(), TablePage.openAddModal()<br/>• Injects dynamic uniqueCode timestamp"]
19
48
 
20
- ActionEngine --> CodeGen["<b>3. Durable Clean POM Script (.groovy / .ts)</b><br/>• 100% Zero raw XPath in scripts<br/>• Infinite CI/CD replays with 0 LLM Tokens"]
49
+ ActionEngine --> CodeGen["<b>3. Durable Clean POM Script (.groovy / .ts)</b><br/>• 100% Zero raw XPath in scripts<br/>• Deterministic CI/CD replays without runtime LLM token consumption"]
21
50
  ```
22
51
 
23
52
  1. **World Model (Reasoning Engine):**
@@ -26,15 +55,16 @@ flowchart TD
26
55
  2. **Action Engine (Code Generator):**
27
56
  - Instead of speculative coordinates, Action Engine queries the project Knowledge Graph to select existing Page Classes and standardized methods.
28
57
  - Generates clean, robust test scripts adhering strictly to Clean POM.
29
- 3. **Zero-Token Replayability:**
58
+ 3. **Deterministic Replayability:**
30
59
  - Once verified, the generated script is committed to the test suite on disk.
31
60
  - All subsequent CI/CD pipeline runs execute deterministically without consuming any LLM tokens.
32
61
 
33
62
  ---
34
63
 
35
- ## 2. Transformation Workflow: User Story to Clean POM
64
+ ### Transformation Workflow: User Story to Clean POM
36
65
 
37
66
  ### Input (User Story):
67
+ <!-- classification: illustrative -->
38
68
  ```text
39
69
  "Verify adding a new Industry record:
40
70
  1. Login as system administrator.
@@ -46,6 +76,7 @@ flowchart TD
46
76
  ```
47
77
 
48
78
  ### Output (Clean POM Groovy Script):
79
+ <!-- classification: illustrative -->
49
80
  ```groovy
50
81
  import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
51
82
  import internal.GlobalVariable as GlobalVariable
@@ -76,12 +107,12 @@ IndustryDataPage.deleteRecordByCode(uniqueCode)
76
107
 
77
108
  ---
78
109
 
79
- ## 3. Mandatory Generation Constraints
110
+ ### Mandatory Generation Constraints
80
111
  - Zero raw XPaths, CSS selectors, or `findTestObject` in the generated script.
81
112
  - Always generate dynamic identifiers with prefixes via `BasePage.uniqueCode()`.
82
113
  - Always generate mandatory teardown cleanup for created entities.
83
114
 
84
- ## 4. Proven-vs-Owed Traceability Pipeline
115
+ ### Proven-vs-Owed Traceability Pipeline
85
116
 
86
117
  > *Borrowed and adapted from the Kane CLI generate→execute→prove workflow (Apache-2.0, lambdatest/kane-cli).*
87
118
 
@@ -111,7 +142,7 @@ Rules:
111
142
 
112
143
  ---
113
144
 
114
- ## 5. Boundary vs `clean-pom-crafter` and `gherkin-to-suite`
145
+ ### Boundary vs `clean-pom-crafter` and `gherkin-to-suite`
115
146
 
116
147
  - **This skill** = natural-language story → action-sequence script skeleton
117
148
  (the "what steps, in what order" reasoning layer).
@@ -121,3 +152,19 @@ Rules:
121
152
  - **`gherkin-to-suite`** is the deterministic (0-token) alternative when
122
153
  requirements already exist as `.feature` files; use it first, and feed its
123
154
  Universal IR here only when story-level reasoning must fill the gaps.
155
+
156
+ ---
157
+
158
+ ## 4. Verification Points & DoD
159
+
160
+ 1. Generated scripts contain strictly Page Class business method calls.
161
+ 2. All test data entities use dynamic timestamped codes (`BasePage.uniqueCode()`).
162
+ 3. Scripts execute deterministically without runtime LLM dependencies.
163
+
164
+ ---
165
+
166
+ ## 5. Handoff Protocol
167
+
168
+ - **Deliverables:** Clean POM test scripts (`TC-xxx.groovy` or `*.spec.ts`) mapping 1:1 to User Stories.
169
+ - **Next Subagent:** pom-crafter / test-runner
170
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: mobile-appium-som
3
3
  description: "Enterprise Screen Object Model (SOM) and Appium mobile automation standards for iOS and Android. Use when authoring, refactoring, or executing native or hybrid mobile tests with Appium, UIAutomator2, or XCUITest."
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
4
10
  ---
5
-
6
11
  # Mobile Appium Screen Object Model (SOM) — Enterprise Architecture Standards
7
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:** Enterprise Screen Object Model (SOM) and Appium mobile automation standards for iOS and Android. Use when authoring, refactoring, or executing native or hybrid mobile tests with Appium, UIAutomator2, or XCUITest.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `mobile-appium-som`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT use absolute screen coordinates or brittle XPath hierarchies (`//android.widget.FrameLayout[1]/...`).
28
+ - Do NOT use static sleeps for mobile transitions; use Appium explicit waits with ExpectedConditions.
29
+ - Do NOT mix Android and iOS selectors in the same method without platform-abstracted SOM classes.
30
+ - **Sibling Skill Boundaries:**
31
+ - clean-pom-crafter handles web POM; mobile-appium-som handles mobile Screen Object Model (Android/iOS).
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for creating, refactoring, and maintaining enterprise mobile automation test suites across **Android (UIAutomator2)** and **iOS (XCUITest)** using the **Screen Object Model (SOM)** and Clean Architecture.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Core Architectural Invariants
41
+ ### Core Architectural Invariants
13
42
 
14
43
  1. **Screen Object Model (SOM):**
15
44
  - Screen classes end with the `Screen` suffix (e.g., `LoginScreen.java`, `HomeScreen.ts`, `CheckoutScreen.py`) and extend `BaseScreen`.
@@ -24,7 +53,7 @@ Specialized skill for creating, refactoring, and maintaining enterprise mobile a
24
53
 
25
54
  ---
26
55
 
27
- ## 2. Native Mobile Locator Priority Hierarchy
56
+ ### Native Mobile Locator Priority Hierarchy
28
57
 
29
58
  All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
30
59
 
@@ -40,35 +69,38 @@ All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
40
69
 
41
70
  ---
42
71
 
43
- ## 3. Mobile Synchronization & Smart Scrolling
72
+ ### Mobile Synchronization & Smart Scrolling
44
73
 
45
74
  1. **Zero Static Delays:**
46
75
  - Static sleeps (`Thread.sleep()`, `time.sleep()`) are forbidden. Always use explicit dynamic waits via `WebDriverWait` with `ExpectedConditions` and defined timeout durations.
47
76
  2. **Smart Scrolling (Scroll-to-View):**
48
77
  - Never interact with off-screen elements without first scrolling them into view.
49
78
  - **Android:** Utilize native `UiScrollable` via `AppiumBy.androidUIAutomator`:
50
- ```java
79
+ <!-- classification: illustrative -->
80
+ ```java
51
81
  String scrollExpr = "new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text(\"Target Item\"))";
52
82
  driver.findElement(AppiumBy.androidUIAutomator(scrollExpr));
53
- ```
83
+ ```
54
84
  - **iOS:** Utilize native gesture commands:
55
- ```java
85
+ <!-- classification: illustrative -->
86
+ ```java
56
87
  Map<String, Object> params = new HashMap<>();
57
88
  params.put("direction", "down");
58
89
  params.put("predicateString", "label == 'Target Item'");
59
90
  driver.executeScript("mobile: scroll", params);
60
- ```
91
+ ```
61
92
  3. **Keyboard Management:**
62
93
  - Always dismiss the virtual on-screen keyboard prior to invoking taps or asserting UI state to avoid click interception:
63
- ```java
94
+ <!-- classification: illustrative -->
95
+ ```java
64
96
  if (driver.isKeyboardShown()) {
65
97
  driver.hideKeyboard();
66
98
  }
67
- ```
99
+ ```
68
100
 
69
101
  ---
70
102
 
71
- ## 4. Mobile Lifecycle & Resilience
103
+ ### Mobile Lifecycle & Resilience
72
104
 
73
105
  1. **System Permission Handling:**
74
106
  - Include `autoGrantPermissions: true` in Android capabilities to prevent unexpected system dialog popups from blocking automation pipelines.
@@ -81,8 +113,24 @@ All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
81
113
 
82
114
  ---
83
115
 
84
- ## 5. Implementation References & Examples
116
+ ### Implementation References & Examples
85
117
 
86
118
  - [**BaseScreen Standard Implementation**](examples/BaseScreen.java): Demonstrates explicit waits, `UiScrollable`, iOS gestures, keyboard dismissal, and safe click wrappers.
87
119
  - [**LoginScreen Implementation**](examples/LoginScreen.java): Demonstrates SOM encapsulation with Tier 1 and Tier 2 locators.
88
120
  - [**Standard Mobile Test Case**](examples/TC_MobileLogin.java): Demonstrates clean test script workflow without raw locators.
121
+
122
+ ---
123
+
124
+ ## 4. Verification Points & DoD
125
+
126
+ 1. Screen classes extend BaseScreen and encapsulate native mobile locators (AccessibilityID / UIAutomator).
127
+ 2. Touch and scroll gestures use dynamic smart wait polling.
128
+ 3. Zero hardcoded sleeps and zero raw locators in mobile test scripts.
129
+
130
+ ---
131
+
132
+ ## 5. Handoff Protocol
133
+
134
+ - **Deliverables:** Screen Object Classes, native test scripts, and mobile capability configuration profiles.
135
+ - **Next Subagent:** pom-crafter / test-runner
136
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,6 +1,6 @@
1
- // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
1
+ // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
2
2
  // SPDX-License-Identifier: MIT
3
- // Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
3
+ // Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
4
4
 
5
5
  package com.synapse.mobile.pages;
6
6
 
@@ -1,6 +1,6 @@
1
- // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
1
+ // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
2
2
  // SPDX-License-Identifier: MIT
3
- // Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
3
+ // Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
4
4
 
5
5
  package com.synapse.mobile.pages;
6
6
 
@@ -1,6 +1,6 @@
1
- // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
1
+ // SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee98). All rights reserved.
2
2
  // SPDX-License-Identifier: MIT
3
- // Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
3
+ // Project: Synapse-Hub (https://github.com/TeeVee98/Synapse-Hub)
4
4
 
5
5
  package com.synapse.mobile.tests;
6
6
 
@@ -1,56 +1,60 @@
1
1
  ---
2
2
  name: playwright-live-interaction
3
3
  description: "Probe live web DOM/AOM and verify selectors under 200ms using headless Playwright. Use when probing live DOM/AOM, verifying selectors, or debugging a live browser session."
4
+ category: test_automation_and_execution
5
+ version: "2.0.0"
6
+ policies:
7
+ network: localhost-only
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Playwright Live Interaction & Fast Debugging Handbook (Enterprise Web & Clean POM)
7
12
 
8
- Direct in-browser interaction and rapid debugging via **Playwright MCP Tools** (`browser_run_code_unsafe` / `call_mcp_tool`), executing live JavaScript/Playwright commands without rebuilding or restarting test runs.
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.
9
14
 
10
15
  ---
11
16
 
12
- ## 1. Scope & Enterprise Architecture Coverage
13
-
14
- All live web flows map strictly to the **Clean Page Object Model Architecture** (`BasePage` + Domain Page Classes in `Keywords/<project_namespace>/pages/` or `pages/*.ts`):
17
+ ## 1. Trigger & Activation
15
18
 
16
- 1. **Authentication & Session:** Login, multi-factor, session renewal, profile update, logout.
17
- 2. **Administration & RBAC:** User accounts, roles, permission matrices, tenant management.
18
- 3. **Master Data & System Catalogs:** Lookup dictionaries, unit definitions, category trees.
19
- 4. **Business Workflows & Approvals:** Multi-step submission, validation state gates, approval chains.
20
- 5. **Data Tables & Search:** Server-side pagination, two-phase search filtering, batch mutations.
21
- 6. **Reporting & Analytics:** Dashboard metrics, dynamic chart canvases, Excel/CSV exports.
22
- 7. **Integrations & API Tokens:** Token lifecycle management, webhook verification, data sharing.
19
+ - **Trigger Clause:** Use when probing live web DOM/AOM trees, interactively verifying locators and selectors, debugging in-flight browser sessions without test restarts, or extracting accessibility snapshots.
20
+ - **Activation Scope:**
21
+ - Headless or headed Playwright sessions via MCP tools (`browser_run_code_unsafe`, `browser_click`, `browser_snapshot`).
22
+ - Web applications with complex dynamic UI frameworks (Angular, PrimeNG, React, Vue).
23
+ - Fast-feedback exploratory probing and locator stabilization.
23
24
 
24
- ### 1.1. Cross-Harness Tool Mapping (Portability Matrix)
25
+ ---
25
26
 
26
- To ensure skills operate seamlessly across different AI agent environments:
27
+ ## 2. Non-Goals & Boundary Constraints
27
28
 
28
- | Action / Intent | Antigravity MCP | Claude Code / Cursor / Standard Playwright MCP | Vanilla Playwright Script |
29
- |---|---|---|---|
30
- | **Run JS in Browser** | `browser_run_code_unsafe` | `browser_evaluate` | `page.evaluate(...)` |
31
- | **Navigate to URL** | `browser_navigate` | `navigate_page` / `page.goto` | `page.goto(url)` |
32
- | **Click Element** | `browser_click` | `click_element` | `page.locator(sel).click()` |
33
- | **Inspect DOM/AOM** | `browser_snapshot` | `get_accessibility_tree` | `locator.ariaSnapshot()` (or `page.accessibility.snapshot()`) |
34
- | **Wait for State** | `browser_wait_for` | `wait_for_selector` | `page.waitForSelector(...)` |
29
+ - **What NOT to do:**
30
+ - Do NOT restart the browser from step 1 when a test step fails; inspect and debug at the current screen state.
31
+ - Do NOT commit unverified or fragile positional locators; verify selector stability before codifying into Page Classes.
32
+ - Do NOT use absolute claims ("100% hit rate in 200ms"); use empirical heuristics for locator responsiveness.
33
+ - **Sibling Skill Boundaries:**
34
+ - `clean-pom-crafter`: Codifies verified selectors into permanent Clean POM Page Classes.
35
+ - `playwright-webapp-testing`: Manages application server lifecycles and standard Playwright suite runner configs.
36
+ - `playwright-live-interaction` (this skill): Focuses exclusively on active in-browser probing, fast-loop debugging, and live AOM inspection.
35
37
 
36
38
  ---
37
39
 
38
- ## 2. Three-Stage Fast-Loop Workflow
40
+ ## 3. Ordered Execution Workflow
41
+
42
+ ### Phase 1: Fast-Loop Exploration Architecture
43
+
44
+ Direct in-browser interaction and rapid debugging via **Playwright MCP Tools** executing live commands:
39
45
 
40
46
  ```mermaid
41
47
  flowchart LR
42
- A["1. Flow Discovery<br/>Inspect live DOM & AOM"] --> B["2. Script Generation<br/>Verify 100% selector hit rate"]
48
+ A["1. Flow Discovery<br/>Inspect live DOM & AOM"] --> B["2. Script Generation<br/>Verify high-confidence selectors"]
43
49
  B --> C["3. In-Place Debugging<br/>Fix error at current screen"]
44
50
  C --> D["4. Codify Clean POM<br/>Package into Page Classes"]
45
51
  ```
46
52
 
47
- 1. **Flow Discovery:** Probe accessibility tree (`locator.ariaSnapshot()` or `page.accessibility.snapshot()`) or DOM to extract live URLs, menus, and dialogs in under 2 minutes.
48
- 2. **Script Generation:** Test selectors live (`await page.locator(...).count() > 0`). Only codify when the selector hits 100% in 200ms.
49
- 3. **In-Place Debugging:** When step $N$ fails, **keep the browser paused at that step**. Use `page.evaluate()` to diagnose disabled buttons, obscuring overlays, or validation errors. Fix in place; never re-run from step 1.
50
-
51
- ---
53
+ 1. **Flow Discovery:** Probe accessibility tree (`locator.ariaSnapshot()`) or DOM to extract live URLs, menus, and dialogs.
54
+ 2. **Script Generation:** Test selectors live (`await page.locator(...).count() > 0`). Codify when selectors demonstrate high-confidence, sub-second response.
55
+ 3. **In-Place Debugging:** When step $N$ fails, keep browser paused at that step. Use `page.evaluate()` to diagnose disabled buttons or obscuring overlays. Fix in place.
52
56
 
53
- ## 3. Mapping Matrix (Playwright Live Code ↔ Clean POM)
57
+ ### Phase 2: Action Mapping Matrix (Playwright Live Code ↔ Clean POM)
54
58
 
55
59
  | UI Action | Playwright Live Code (MCP) | Clean POM Groovy / Java Code | Clean POM TypeScript (Playwright) |
56
60
  |---|---|---|---|
@@ -59,73 +63,32 @@ flowchart LR
59
63
  | **Dropdown Selection** | `await page.locator('p-dropdown').click(); await page.locator('.p-dropdown-item:has-text("X")').click();` | `selectDropdownByText(dropdownEl, "X")` | `await this.dropdown.selectOption("X");` |
60
64
  | **Calendar Picker** | Synthetic `input` + `change` event | `jsSetInput(calendarInput, "25/10/2026")` | `await this.datePicker.fill("2026-10-25");` |
61
65
  | **Catch Success Toast** | `await page.waitForSelector('.toast-success')` | `verifyToastMessage("Success")` | `await expect(this.toast).toBeVisible();` |
62
- | **Two-Phase Search** | Click search icon -> Enter Keyword -> Enter | `searchRecord(keyword)` in Page Class | `await this.search(keyword);` |
63
- | **Delete & Confirm** | Click Trash -> Accept Confirm -> Verify Gone | `deleteRecord(keyword)` in Page Class | `await this.delete(keyword);` |
66
+
67
+ ### Phase 3: Observe → Act → Extract Triad
68
+
69
+ 1. **Observe before acting:** Snapshot current state (`window.__qa.ariaSnapshot()`) and select targets from evidence.
70
+ 2. **Act on one primitive at a time:** Click, fill, or press with atomic batching via `window.__qa.batch()`.
71
+ 3. **Extract to assert:** Extract resulting state back out of the page and assert on actual values.
72
+
73
+ ### Phase 4: Implementation References
74
+
75
+ - [**20 Complete UI Recipes**](references/recipes.md): Code recipes for Auth, Data Tables, Dropdowns, Modals, Confirm Dialogs, File Upload, Calendar, MultiSelect, Stale Retries, Form Audit, Smart Action Batching, and Self-Healing Locators.
76
+ - **Runtime Browser Helper (`tools/browser_helpers.js`):** Unified JavaScript module providing `window.__qa` (`batch`, `audit`, `heal`, `clickSafe`, `exportSession`).
77
+ - [**5 Superpowers & 5 AI Paradigms**](references/advanced_superpowers.md): Zero-Second Auth (`session.json`), Direct API Seeding, AOM Snapshots, Multi-Context Dual Role, Route Mocking, Self-Healing Locators, Fuzzing, CDP Profiling.
64
78
 
65
79
  ---
66
80
 
67
- ## 4. Pre-Codify Quality Checklist
81
+ ## 4. Verification Points & DoD
68
82
 
69
- Mandatory 5-point verification before committing POM code:
70
- - [x] **100% UTF-8 No BOM:** Must NOT contain `0xEF, 0xBB, 0xBF`.
71
- - [x] **Flat Architecture:** Zero raw XPaths or unencapsulated selectors in test scripts.
72
- - [x] **Dynamic Test Data:** Use `BasePage.uniqueCode("PREFIX_")`; no static colliding strings.
73
- - [x] **Truth Anchor (No Fake Pass):** Real toast assertions or live data table row verification.
74
- - [x] **Synthetic Event Dispatch:** 100% framework inputs trigger synthetic `input` and `change` events.
83
+ 1. **Selector Uniqueness:** Every codified locator matches exactly 1 target element in the active DOM/AOM.
84
+ 2. **Response Responsiveness:** Element interaction completes with sub-second verified latency under normal load.
85
+ 3. **Event Triggering:** Complex inputs correctly fire synthetic `input` and `change` events.
86
+ 4. **Encoding & Standards:** All generated test fixtures adhere to 100% UTF-8 No BOM.
75
87
 
76
88
  ---
77
89
 
78
- ## 5. Reference Documentation (Progressive Disclosure)
90
+ ## 5. Handoff Protocol
79
91
 
80
- - [**20 Complete UI Recipes**](references/recipes.md): Code recipes for Auth, Data Tables, Dropdowns, Modals, Confirm Dialogs, File Upload, Calendar, MultiSelect, Stale Retries, Form Audit, Smart Action Batching, and Self-Healing Locators.
81
- - [**Runtime Browser Helper (`tools/browser_helpers.js`)**](../../../tools/browser_helpers.js): Unified JavaScript module providing `window.__qa` (`batch`, `audit`, `heal`, `clickSafe`, `exportSession`).
82
- - [**5 Superpowers & 5 AI Paradigms**](references/advanced_superpowers.md): Zero-Second Auth (`session.json`), Direct API Seeding, AOM Snapshots, Multi-Context Dual Role, Route Mocking, Self-Healing Locators, Fuzzing, CDP Profiling.
83
- - [**Multi-Agent Swarm Orchestration**](references/swarm_orchestration.md): Specialized swarm roles and collaboration protocol.
84
-
85
- ## 6. Instant Action vs Auto-Planning Dispatch
86
-
87
- > *Borrowed and adapted from the Midscene.js prompting model (MIT license, web-infra-dev/midscene).*
88
-
89
- When driving the live browser through an AI vision model, choose the dispatch
90
- mode deliberately — the trade-off is control vs cost:
91
-
92
- | Mode | When to Use | Cost Profile |
93
- | :--- | :--- | :--- |
94
- | **Instant action** (`aiTap`, `aiInput`, `aiHover`, `aiQuery`) | You already know the exact single action; AI only locates the element | Faster and more accurate; deterministic control |
95
- | **Auto planning** (`aiAction("<full task>")`) | Multi-step flow not yet decomposed; you want the model to plan | Flexible but costs more time and tokens; plan can drift |
96
-
97
- Dispatch rules for agents:
98
-
99
- 1. **One task per call** — split "Click Login then fill the form" into separate
100
- calls; combined prompts produce messy plans.
101
- 2. **Describe position, not internals** — the model sees pixels/AOM only:
102
- prefer "the button at the top-right of the cart panel" over DOM properties.
103
- 3. **Assert only what is visible** — DOM internals, tab counts, or network
104
- state are invisible to the model; use `aiQuery` to extract data, then assert
105
- on the extracted value with a real assertion.
106
- 4. **Never trust the model's own success claim** — pair every instant action
107
- with an explicit `expect(...)`/`verify...` assertion (Truth Anchor).
108
- 5. **Debug failures in two layers** — wrong step count = planning failed (add
109
- flow detail); wrong element = locating failed (add spatial detail).
110
-
111
- ## 7. Observe → Act → Extract Triad & ARIA Snapshots
112
-
113
- > *Borrowed and adapted from the Stagehand primitives (MIT, browserbase/stagehand) and the Playwright MCP accessibility-snapshot contract (Apache-2.0, microsoft/playwright-mcp).*
114
-
115
- Structure every live-browser AI interaction as a three-primitive loop:
116
-
117
- 1. **Observe before acting** — snapshot the current state
118
- (`window.__qa.ariaSnapshot()` — Playwright-MCP-format ARIA tree with
119
- `[ref=eN]` refs — or `getCompactAOM()` for the compact variant) and pick the
120
- target from evidence, never from memory of what the page "should" contain.
121
- 2. **Act on one primitive at a time** — a click, a fill, a press. One action,
122
- one assertion of intent; batch related actions atomically via
123
- `window.__qa.batch()`.
124
- 3. **Extract to assert** — pull the resulting state back out of the page
125
- (ariaSnapshot / AOM / `aiQuery`-style extraction) and assert on the
126
- extracted value; an action without a post-state extraction is unverified.
127
-
128
- Cache-friendliness rule (Stagehand insight): identical observe/act/extract
129
- calls on an unchanged page should be replayable without re-reasoning — record
130
- snapshots and results into the hub memory cache (`cache_resolver`) so repeat
131
- runs cost zero tokens.
92
+ - **Deliverables:** Verified locator contracts, AOM accessibility snapshots, and in-place debug notes.
93
+ - **Next Subagent:** Pass verified locators to `pom-crafter` for Page Class codification or `failure-analyst` for root-cause healing.
94
+ - **Output Format:** Clean POM selector map and interactive action sequence log.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: playwright-webapp-testing
3
3
  description: "Drive Playwright test runs against a local web application with a managed server lifecycle: start, wait for readiness, run automation, and guarantee teardown. Use when verifying frontend functionality or debugging UI behavior of a dynamic webapp that must be started before testing."
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
4
10
  ---
5
-
6
11
  # Playwright Webapp Testing — Enterprise Server-Lifecycle Standard
7
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:** Drive Playwright test runs against a local web application with a managed server lifecycle: start, wait for readiness, run automation, and guarantee teardown. Use when verifying frontend functionality or debugging UI behavior of a dynamic webapp that must be started before testing.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `playwright-webapp-testing`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT leave dangling dev server background processes after test suite completion.
28
+ - Do NOT run headed browser tests in CI/CD environments; enforce headless execution.
29
+ - Do NOT hardcode fixed ports that collide during parallel CI runs.
30
+ - **Sibling Skill Boundaries:**
31
+ - playwright-live-interaction is for live in-session probing; playwright-webapp-testing manages full webapp test lifecycles and configs.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for testing local dynamic web applications with Playwright under Synapse Hub rules: managed server lifecycle, smart waits instead of static sleeps, and the 3-Stage Live Protocol for selector discovery.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Server Lifecycle Contract
41
+ ### Server Lifecycle Contract
13
42
 
14
43
  ```mermaid
15
44
  flowchart LR
@@ -23,12 +52,13 @@ flowchart LR
23
52
  - Multiple servers (backend + frontend): every server gets its own readiness poll; the suite starts only after ALL are ready.
24
53
  - Teardown is unconditional — a failed test run must still shut down spawned processes (driver/process cleanup mirrors `katalon-cli-runner` discipline).
25
54
 
26
- ## 2. Standard Configuration (Hub Baseline)
55
+ ### Standard Configuration (Hub Baseline)
27
56
 
28
57
  - **Headless mode, 1920x1080 Full HD viewport** — mandatory per `AGENTS.md` Section 2.
29
58
  - Chromium first; multi-browser coverage is governed by `e2e-testing-patterns`.
30
59
  - Launch pattern (Python):
31
60
 
61
+ <!-- classification: illustrative -->
32
62
  ```python
33
63
  from playwright.sync_api import sync_playwright
34
64
 
@@ -45,6 +75,7 @@ with sync_playwright() as p:
45
75
 
46
76
  - Launch pattern (TypeScript / Playwright Test):
47
77
 
78
+ <!-- classification: illustrative -->
48
79
  ```typescript
49
80
  import { test, expect } from '@playwright/test';
50
81
  import { LoginPage } from './pages/LoginPage';
@@ -60,9 +91,10 @@ test('TC-101 User Authentication Flow', async ({ page }) => {
60
91
  });
61
92
  ```
62
93
 
63
- ## 3. Decision Tree: Static vs Dynamic
94
+ ### Decision Tree: Static vs Dynamic
64
95
 
65
- ```
96
+ <!-- classification: illustrative -->
97
+ ```text
66
98
  Task -> Is the page static HTML?
67
99
  |- Yes -> Read the HTML directly to identify selectors, then script.
68
100
  |- No (dynamic webapp) -> Is the server already running?
@@ -70,7 +102,7 @@ Task -> Is the page static HTML?
70
102
  |- Yes -> Reconnaissance-then-action (section 4) on the live app.
71
103
  ```
72
104
 
73
- ## 4. Reconnaissance-Then-Action Pattern
105
+ ### Reconnaissance-Then-Action Pattern
74
106
 
75
107
  For a dynamic app, never guess selectors:
76
108
 
@@ -81,19 +113,19 @@ For a dynamic app, never guess selectors:
81
113
 
82
114
  **Common pitfall:** inspecting the DOM before rendering completes on dynamic apps. Always synchronize via web-first assertions or targeted selector waits; avoid unconditional `networkidle` on apps with continuous background polling or WebSocket traffic.
83
115
 
84
- ## 5. Smart Wait Rules (Zero Static Sleeps)
116
+ ### Smart Wait Rules (Zero Static Sleeps)
85
117
 
86
118
  - FORBIDDEN: `time.sleep()`, `Thread.sleep()`, fixed `wait_for_timeout` as a synchronization strategy (per `AGENTS.md` Section 1).
87
119
  - Required: `wait_for_selector`, `expect` web-first assertions with auto-retry, explicit condition polling, or `wait_for_load_state("networkidle")` with bounded timeout.
88
120
  - `wait_for_timeout` is tolerated only inside after-step settle windows where no condition is observable, and must carry a comment explaining why.
89
121
 
90
- ## 6. Evidence & Debugging Rules
122
+ ### Evidence & Debugging Rules
91
123
 
92
124
  - Capture console logs and failed-request events during runs; attach the distilled failure block to reports, not full logs (distill via `tools/distill_log.py`).
93
125
  - On failure: apply `systematic-debugging` — reproduce, isolate, root-cause — before touching selectors; broken locators heal via `self-healing-locator` with a live re-probe through Stage 1 of the Live Protocol.
94
126
  - Claims of "suite passes" follow `verification-before-completion`: quote the fresh run output.
95
127
 
96
- ## 7. Boundary vs Sibling Skills (Do Not Confuse)
128
+ ### Boundary vs Sibling Skills (Do Not Confuse)
97
129
 
98
130
  | Sibling | Owns | Hand-off |
99
131
  |---|---|---|
@@ -101,12 +133,28 @@ For a dynamic app, never guess selectors:
101
133
  | `e2e-testing-patterns` | Multi-browser architecture, sharding, retry governance | This skill owns the single-run server lifecycle; suite topology stays with e2e patterns |
102
134
  | `auth-session-and-cookie-manager` | Login states, storageState, multi-role sessions | Complex auth flows inject their storageState before this skill's run starts |
103
135
 
104
- ## 8. Reference Documentation
136
+ ### Reference Documentation
105
137
 
106
138
  - [Server lifecycle example (`server_lifecycle_playwright.py`)](examples/server_lifecycle_playwright.py): readiness-polling wrapper + minimal automation script.
107
139
  - `tools/browser_helpers.js` — in-browser validation engine (safe clicks, form audits, batch verification).
108
140
  - `tools/distill_log.py` — distill verbose run logs by ~95% before attaching to reports.
109
141
 
110
- ## 9. Attribution
142
+ ### Attribution
111
143
 
112
144
  Adapted from **webapp-testing** in anthropics/skills (https://github.com/anthropics/skills) — Apache License 2.0, Copyright 2026 Anthropic, PBC. The server-lifecycle contract, decision tree, and reconnaissance-then-action pattern are re-scoped to Synapse Hub standards (headless 1920x1080, smart waits, hub tool wiring); this is a rewritten derivative, not a verbatim copy.
145
+
146
+ ---
147
+
148
+ ## 4. Verification Points & DoD
149
+
150
+ 1. Web server lifecycle (setup, health check, teardown) is strictly managed.
151
+ 2. Configuration files (`playwright.config.ts`) enforce retries, traces, and screenshot captures on failure.
152
+ 3. Tests execute cleanly in headless mode with exit code 0.
153
+
154
+ ---
155
+
156
+ ## 5. Handoff Protocol
157
+
158
+ - **Deliverables:** Playwright configuration files, web server lifecycle scripts, and execution reports.
159
+ - **Next Subagent:** test-runner
160
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.