@teevee98/synapse-hub 4.2.0 → 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 (107) hide show
  1. package/.agents/skills/01-web-automation/auth-session-and-cookie-manager/SKILL.md +46 -2
  2. package/.agents/skills/01-web-automation/bats-testing-patterns/SKILL.md +49 -4
  3. package/.agents/skills/01-web-automation/clean-pom-crafter/SKILL.md +56 -66
  4. package/.agents/skills/01-web-automation/e2e-testing-patterns/SKILL.md +48 -3
  5. package/.agents/skills/01-web-automation/katalon-cli-runner/SKILL.md +56 -11
  6. package/.agents/skills/01-web-automation/lam-script-generator/SKILL.md +49 -7
  7. package/.agents/skills/01-web-automation/mobile-appium-som/SKILL.md +54 -11
  8. package/.agents/skills/01-web-automation/playwright-live-interaction/SKILL.md +48 -90
  9. package/.agents/skills/01-web-automation/playwright-webapp-testing/SKILL.md +53 -10
  10. package/.agents/skills/01-web-automation/web-agent-gym-benchmarking/SKILL.md +44 -3
  11. package/.agents/skills/02-test-design/architecture-decision-records/SKILL.md +49 -8
  12. package/.agents/skills/02-test-design/gherkin-to-suite/SKILL.md +49 -8
  13. package/.agents/skills/02-test-design/rbt-manual-testing/SKILL.md +49 -7
  14. package/.agents/skills/02-test-design/review-spec/SKILL.md +46 -5
  15. package/.agents/skills/02-test-design/tot-exploratory-testing/SKILL.md +44 -3
  16. package/.agents/skills/03-api-and-contracts/api-network-mocking-interception/SKILL.md +50 -4
  17. package/.agents/skills/03-api-and-contracts/api-spec-to-e2e-matrix/SKILL.md +47 -6
  18. package/.agents/skills/03-api-and-contracts/consumer-driven-contract-testing/SKILL.md +79 -34
  19. package/.agents/skills/04-performance-and-load/backend-load-and-stress-patterns/SKILL.md +47 -4
  20. package/.agents/skills/04-performance-and-load/lean-impact-scoreboard/SKILL.md +46 -5
  21. package/.agents/skills/04-performance-and-load/web-vitals-and-performance-profiler/SKILL.md +44 -2
  22. package/.agents/skills/05-security-and-compliance/security-dast-sentinel/SKILL.md +57 -13
  23. package/.agents/skills/05-security-and-compliance/skillspector-security-guard/SKILL.md +45 -4
  24. package/.agents/skills/05-security-and-compliance/wcag-audit-patterns/SKILL.md +48 -3
  25. package/.agents/skills/06-healing-and-resilience/agentless-qa-repair/SKILL.md +45 -4
  26. package/.agents/skills/06-healing-and-resilience/antigravity-test-sentinel/SKILL.md +47 -5
  27. package/.agents/skills/06-healing-and-resilience/failure-autopsy-and-healing/SKILL.md +48 -7
  28. package/.agents/skills/06-healing-and-resilience/flaky-test-sentinel-and-quarantine/SKILL.md +54 -23
  29. package/.agents/skills/06-healing-and-resilience/self-healing-locator/SKILL.md +46 -5
  30. package/.agents/skills/06-healing-and-resilience/systematic-debugging/SKILL.md +50 -9
  31. package/.agents/skills/06-healing-and-resilience/test-driven-development/SKILL.md +52 -11
  32. package/.agents/skills/06-healing-and-resilience/verification-before-completion/SKILL.md +52 -11
  33. package/.agents/skills/06-healing-and-resilience/visual-regression-sentinel/SKILL.md +47 -4
  34. package/.agents/skills/07-data-and-state/db-state-verifier-and-seeder/SKILL.md +50 -4
  35. package/.agents/skills/07-data-and-state/file-and-report-validator/SKILL.md +47 -3
  36. package/.agents/skills/07-data-and-state/synthetic-test-data-generator/SKILL.md +52 -4
  37. package/.agents/skills/08-code-quality/code-refactoring-refactor-clean/SKILL.md +51 -10
  38. package/.agents/skills/08-code-quality/graphify-impact-analyzer/SKILL.md +78 -34
  39. package/.agents/skills/08-code-quality/graphify-impact-analyzer/examples/dependency_blast_radius.json +3 -4
  40. package/.agents/skills/08-code-quality/lean-code-ladder/SKILL.md +49 -9
  41. package/.agents/skills/08-code-quality/repo-quality-audit/SKILL.md +45 -5
  42. package/.agents/skills/08-code-quality/senior-code-review/SKILL.md +48 -6
  43. package/.agents/skills/08-code-quality/surgical-coding-principles/SKILL.md +49 -9
  44. package/.agents/skills/08-code-quality/technical-debt-harvester/SKILL.md +47 -4
  45. package/.agents/skills/09-ci-and-devops/github-actions-templates/SKILL.md +48 -16
  46. package/.agents/skills/09-ci-and-devops/github-actions-templates/examples/matrix_test_pipeline.yml +2 -1
  47. package/.agents/skills/10-agent-orchestration/actor-qa-swarm/SKILL.md +44 -3
  48. package/.agents/skills/10-agent-orchestration/agent-orchestration-multi-agent-optimize/SKILL.md +47 -6
  49. package/.agents/skills/10-agent-orchestration/event-stream-qa-orchestrator/SKILL.md +44 -3
  50. package/.agents/skills/10-agent-orchestration/persistent-planning-files/SKILL.md +52 -12
  51. package/.agents/skills/10-agent-orchestration/qa-memory-os/SKILL.md +45 -4
  52. package/.agents/skills/11-ai-and-prompting/meta-prompt-crafter/SKILL.md +51 -9
  53. package/.agents/skills/11-ai-and-prompting/mipro-prompt-compiler/SKILL.md +44 -3
  54. package/.agents/skills/11-ai-and-prompting/qa-aci-interface/SKILL.md +44 -3
  55. package/.agents/skills/11-ai-and-prompting/token-and-context-optimizer/SKILL.md +49 -8
  56. package/.cursor/rules/synapse-qa.mdc +20 -7
  57. package/.cursorrules +19 -5
  58. package/.windsurfrules +18 -3
  59. package/AGENTS.md +51 -65
  60. package/CLAUDE.md +38 -24
  61. package/README.en.md +2 -2
  62. package/README.md +2 -2
  63. package/agentskills.json +1 -1
  64. package/docs/ARCHITECTURE.en.md +1 -1
  65. package/docs/ARCHITECTURE.md +1 -1
  66. package/docs/CLIENT_SUPPORT_MATRIX.md +44 -0
  67. package/docs/SIDE_EFFECTING_TOOLS_INVENTORY.md +233 -0
  68. package/package.json +1 -1
  69. package/plugin.json +1 -1
  70. package/skills_manifest.json +1 -1
  71. package/synapse.config.json +1 -1
  72. package/templates/ai_bridges/CLAUDE.md +29 -26
  73. package/templates/ai_bridges/copilot-instructions.md +14 -5
  74. package/templates/ai_bridges/cursor_synapse_qa.mdc +16 -7
  75. package/templates/ai_bridges/windsurfrules +14 -3
  76. package/tools/TOOLS_RUNBOOK.md +1 -1
  77. package/tools/__init__.py +1 -1
  78. package/tools/api_fuzzer.py +295 -41
  79. package/tools/benchmark_swarm_context.py +11 -4
  80. package/tools/browser_helpers.js +2 -2
  81. package/tools/cli.py +4 -4
  82. package/tools/core/bm25_retriever.py +1 -1
  83. package/tools/core/i18n.py +1 -1
  84. package/tools/core/provider_usage_adapter.py +66 -0
  85. package/tools/core/token_estimator.py +39 -1
  86. package/tools/count_tokens.py +2 -2
  87. package/tools/dashboard_generator.py +8 -8
  88. package/tools/db_sandbox.py +182 -43
  89. package/tools/distill_log.py +1 -1
  90. package/tools/distill_skill.py +17 -2
  91. package/tools/git_pre_commit_guard.py +190 -1
  92. package/tools/mcp_docx_server.py +1 -1
  93. package/tools/mcp_excel_server.py +1 -1
  94. package/tools/mcp_server.py +33 -5
  95. package/tools/micro_mutator.py +30 -1
  96. package/tools/pentest_scope_guard.py +288 -15
  97. package/tools/project_state.py +29 -5
  98. package/tools/reversible_sandbox.py +58 -13
  99. package/tools/rules_router.py +80 -27
  100. package/tools/skill_canonical_digest.py +60 -2
  101. package/tools/sync_agent_rules.py +187 -61
  102. package/tools/task_memory_manager.py +16 -1
  103. package/tools/ui_server.py +3 -1
  104. package/tools/update_sentinel.py +3 -3
  105. package/tools/validate_skills_schema.py +349 -56
  106. package/tools/verify_all.py +96 -2
  107. package/tools/welcome_page.py +1 -1
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # LAM Script Generator — Large Action Model for Test Automation
12
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
+
13
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.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. The Dual-Engine LAM Architecture
41
+ ### The Dual-Engine LAM Architecture
18
42
 
19
43
  ```mermaid
20
44
  flowchart TD
@@ -22,7 +46,7 @@ flowchart TD
22
46
 
23
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"]
24
48
 
25
- 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"]
26
50
  ```
27
51
 
28
52
  1. **World Model (Reasoning Engine):**
@@ -31,15 +55,16 @@ flowchart TD
31
55
  2. **Action Engine (Code Generator):**
32
56
  - Instead of speculative coordinates, Action Engine queries the project Knowledge Graph to select existing Page Classes and standardized methods.
33
57
  - Generates clean, robust test scripts adhering strictly to Clean POM.
34
- 3. **Zero-Token Replayability:**
58
+ 3. **Deterministic Replayability:**
35
59
  - Once verified, the generated script is committed to the test suite on disk.
36
60
  - All subsequent CI/CD pipeline runs execute deterministically without consuming any LLM tokens.
37
61
 
38
62
  ---
39
63
 
40
- ## 2. Transformation Workflow: User Story to Clean POM
64
+ ### Transformation Workflow: User Story to Clean POM
41
65
 
42
66
  ### Input (User Story):
67
+ <!-- classification: illustrative -->
43
68
  ```text
44
69
  "Verify adding a new Industry record:
45
70
  1. Login as system administrator.
@@ -51,6 +76,7 @@ flowchart TD
51
76
  ```
52
77
 
53
78
  ### Output (Clean POM Groovy Script):
79
+ <!-- classification: illustrative -->
54
80
  ```groovy
55
81
  import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
56
82
  import internal.GlobalVariable as GlobalVariable
@@ -81,12 +107,12 @@ IndustryDataPage.deleteRecordByCode(uniqueCode)
81
107
 
82
108
  ---
83
109
 
84
- ## 3. Mandatory Generation Constraints
110
+ ### Mandatory Generation Constraints
85
111
  - Zero raw XPaths, CSS selectors, or `findTestObject` in the generated script.
86
112
  - Always generate dynamic identifiers with prefixes via `BasePage.uniqueCode()`.
87
113
  - Always generate mandatory teardown cleanup for created entities.
88
114
 
89
- ## 4. Proven-vs-Owed Traceability Pipeline
115
+ ### Proven-vs-Owed Traceability Pipeline
90
116
 
91
117
  > *Borrowed and adapted from the Kane CLI generate→execute→prove workflow (Apache-2.0, lambdatest/kane-cli).*
92
118
 
@@ -116,7 +142,7 @@ Rules:
116
142
 
117
143
  ---
118
144
 
119
- ## 5. Boundary vs `clean-pom-crafter` and `gherkin-to-suite`
145
+ ### Boundary vs `clean-pom-crafter` and `gherkin-to-suite`
120
146
 
121
147
  - **This skill** = natural-language story → action-sequence script skeleton
122
148
  (the "what steps, in what order" reasoning layer).
@@ -126,3 +152,19 @@ Rules:
126
152
  - **`gherkin-to-suite`** is the deterministic (0-token) alternative when
127
153
  requirements already exist as `.feature` files; use it first, and feed its
128
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.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Mobile Appium Screen Object Model (SOM) — Enterprise Architecture Standards
12
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
+
13
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.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Core Architectural Invariants
41
+ ### Core Architectural Invariants
18
42
 
19
43
  1. **Screen Object Model (SOM):**
20
44
  - Screen classes end with the `Screen` suffix (e.g., `LoginScreen.java`, `HomeScreen.ts`, `CheckoutScreen.py`) and extend `BaseScreen`.
@@ -29,7 +53,7 @@ Specialized skill for creating, refactoring, and maintaining enterprise mobile a
29
53
 
30
54
  ---
31
55
 
32
- ## 2. Native Mobile Locator Priority Hierarchy
56
+ ### Native Mobile Locator Priority Hierarchy
33
57
 
34
58
  All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
35
59
 
@@ -45,35 +69,38 @@ All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
45
69
 
46
70
  ---
47
71
 
48
- ## 3. Mobile Synchronization & Smart Scrolling
72
+ ### Mobile Synchronization & Smart Scrolling
49
73
 
50
74
  1. **Zero Static Delays:**
51
75
  - Static sleeps (`Thread.sleep()`, `time.sleep()`) are forbidden. Always use explicit dynamic waits via `WebDriverWait` with `ExpectedConditions` and defined timeout durations.
52
76
  2. **Smart Scrolling (Scroll-to-View):**
53
77
  - Never interact with off-screen elements without first scrolling them into view.
54
78
  - **Android:** Utilize native `UiScrollable` via `AppiumBy.androidUIAutomator`:
55
- ```java
79
+ <!-- classification: illustrative -->
80
+ ```java
56
81
  String scrollExpr = "new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text(\"Target Item\"))";
57
82
  driver.findElement(AppiumBy.androidUIAutomator(scrollExpr));
58
- ```
83
+ ```
59
84
  - **iOS:** Utilize native gesture commands:
60
- ```java
85
+ <!-- classification: illustrative -->
86
+ ```java
61
87
  Map<String, Object> params = new HashMap<>();
62
88
  params.put("direction", "down");
63
89
  params.put("predicateString", "label == 'Target Item'");
64
90
  driver.executeScript("mobile: scroll", params);
65
- ```
91
+ ```
66
92
  3. **Keyboard Management:**
67
93
  - Always dismiss the virtual on-screen keyboard prior to invoking taps or asserting UI state to avoid click interception:
68
- ```java
94
+ <!-- classification: illustrative -->
95
+ ```java
69
96
  if (driver.isKeyboardShown()) {
70
97
  driver.hideKeyboard();
71
98
  }
72
- ```
99
+ ```
73
100
 
74
101
  ---
75
102
 
76
- ## 4. Mobile Lifecycle & Resilience
103
+ ### Mobile Lifecycle & Resilience
77
104
 
78
105
  1. **System Permission Handling:**
79
106
  - Include `autoGrantPermissions: true` in Android capabilities to prevent unexpected system dialog popups from blocking automation pipelines.
@@ -86,8 +113,24 @@ All mobile Screen classes **MUST** adhere to this 5-tier selector priority:
86
113
 
87
114
  ---
88
115
 
89
- ## 5. Implementation References & Examples
116
+ ### Implementation References & Examples
90
117
 
91
118
  - [**BaseScreen Standard Implementation**](examples/BaseScreen.java): Demonstrates explicit waits, `UiScrollable`, iOS gestures, keyboard dismissal, and safe click wrappers.
92
119
  - [**LoginScreen Implementation**](examples/LoginScreen.java): Demonstrates SOM encapsulation with Tier 1 and Tier 2 locators.
93
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.
@@ -10,52 +10,51 @@ policies:
10
10
  ---
11
11
  # Playwright Live Interaction & Fast Debugging Handbook (Enterprise Web & Clean POM)
12
12
 
13
- 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.
14
14
 
15
15
  ---
16
16
 
17
- ## 1. Scope & Enterprise Architecture Coverage
17
+ ## 1. Trigger & Activation
18
18
 
19
- 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`):
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.
20
24
 
21
- 1. **Authentication & Session:** Login, multi-factor, session renewal, profile update, logout.
22
- 2. **Administration & RBAC:** User accounts, roles, permission matrices, tenant management.
23
- 3. **Master Data & System Catalogs:** Lookup dictionaries, unit definitions, category trees.
24
- 4. **Business Workflows & Approvals:** Multi-step submission, validation state gates, approval chains.
25
- 5. **Data Tables & Search:** Server-side pagination, two-phase search filtering, batch mutations.
26
- 6. **Reporting & Analytics:** Dashboard metrics, dynamic chart canvases, Excel/CSV exports.
27
- 7. **Integrations & API Tokens:** Token lifecycle management, webhook verification, data sharing.
28
-
29
- ### 1.1. Cross-Harness Tool Mapping (Portability Matrix)
25
+ ---
30
26
 
31
- To ensure skills operate seamlessly across different AI agent environments:
27
+ ## 2. Non-Goals & Boundary Constraints
32
28
 
33
- | Action / Intent | Antigravity MCP | Claude Code / Cursor / Standard Playwright MCP | Vanilla Playwright Script |
34
- |---|---|---|---|
35
- | **Run JS in Browser** | `browser_run_code_unsafe` | `browser_evaluate` | `page.evaluate(...)` |
36
- | **Navigate to URL** | `browser_navigate` | `navigate_page` / `page.goto` | `page.goto(url)` |
37
- | **Click Element** | `browser_click` | `click_element` | `page.locator(sel).click()` |
38
- | **Inspect DOM/AOM** | `browser_snapshot` | `get_accessibility_tree` | `locator.ariaSnapshot()` (or `page.accessibility.snapshot()`) |
39
- | **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.
40
37
 
41
38
  ---
42
39
 
43
- ## 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:
44
45
 
45
46
  ```mermaid
46
47
  flowchart LR
47
- 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"]
48
49
  B --> C["3. In-Place Debugging<br/>Fix error at current screen"]
49
50
  C --> D["4. Codify Clean POM<br/>Package into Page Classes"]
50
51
  ```
51
52
 
52
- 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.
53
- 2. **Script Generation:** Test selectors live (`await page.locator(...).count() > 0`). Only codify when the selector hits 100% in 200ms.
54
- 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.
55
-
56
- ---
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.
57
56
 
58
- ## 3. Mapping Matrix (Playwright Live Code ↔ Clean POM)
57
+ ### Phase 2: Action Mapping Matrix (Playwright Live Code ↔ Clean POM)
59
58
 
60
59
  | UI Action | Playwright Live Code (MCP) | Clean POM Groovy / Java Code | Clean POM TypeScript (Playwright) |
61
60
  |---|---|---|---|
@@ -64,73 +63,32 @@ flowchart LR
64
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");` |
65
64
  | **Calendar Picker** | Synthetic `input` + `change` event | `jsSetInput(calendarInput, "25/10/2026")` | `await this.datePicker.fill("2026-10-25");` |
66
65
  | **Catch Success Toast** | `await page.waitForSelector('.toast-success')` | `verifyToastMessage("Success")` | `await expect(this.toast).toBeVisible();` |
67
- | **Two-Phase Search** | Click search icon -> Enter Keyword -> Enter | `searchRecord(keyword)` in Page Class | `await this.search(keyword);` |
68
- | **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.
69
78
 
70
79
  ---
71
80
 
72
- ## 4. Pre-Codify Quality Checklist
81
+ ## 4. Verification Points & DoD
73
82
 
74
- Mandatory 5-point verification before committing POM code:
75
- - [x] **100% UTF-8 No BOM:** Must NOT contain `0xEF, 0xBB, 0xBF`.
76
- - [x] **Flat Architecture:** Zero raw XPaths or unencapsulated selectors in test scripts.
77
- - [x] **Dynamic Test Data:** Use `BasePage.uniqueCode("PREFIX_")`; no static colliding strings.
78
- - [x] **Truth Anchor (No Fake Pass):** Real toast assertions or live data table row verification.
79
- - [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.
80
87
 
81
88
  ---
82
89
 
83
- ## 5. Reference Documentation (Progressive Disclosure)
90
+ ## 5. Handoff Protocol
84
91
 
85
- - [**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.
86
- - [**Runtime Browser Helper (`tools/browser_helpers.js`)**](../../../../tools/browser_helpers.js): Unified JavaScript module providing `window.__qa` (`batch`, `audit`, `heal`, `clickSafe`, `exportSession`).
87
- - [**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.
88
- - [**Multi-Agent Swarm Orchestration**](references/swarm_orchestration.md): Specialized swarm roles and collaboration protocol.
89
-
90
- ## 6. Instant Action vs Auto-Planning Dispatch
91
-
92
- > *Borrowed and adapted from the Midscene.js prompting model (MIT license, web-infra-dev/midscene).*
93
-
94
- When driving the live browser through an AI vision model, choose the dispatch
95
- mode deliberately — the trade-off is control vs cost:
96
-
97
- | Mode | When to Use | Cost Profile |
98
- | :--- | :--- | :--- |
99
- | **Instant action** (`aiTap`, `aiInput`, `aiHover`, `aiQuery`) | You already know the exact single action; AI only locates the element | Faster and more accurate; deterministic control |
100
- | **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 |
101
-
102
- Dispatch rules for agents:
103
-
104
- 1. **One task per call** — split "Click Login then fill the form" into separate
105
- calls; combined prompts produce messy plans.
106
- 2. **Describe position, not internals** — the model sees pixels/AOM only:
107
- prefer "the button at the top-right of the cart panel" over DOM properties.
108
- 3. **Assert only what is visible** — DOM internals, tab counts, or network
109
- state are invisible to the model; use `aiQuery` to extract data, then assert
110
- on the extracted value with a real assertion.
111
- 4. **Never trust the model's own success claim** — pair every instant action
112
- with an explicit `expect(...)`/`verify...` assertion (Truth Anchor).
113
- 5. **Debug failures in two layers** — wrong step count = planning failed (add
114
- flow detail); wrong element = locating failed (add spatial detail).
115
-
116
- ## 7. Observe → Act → Extract Triad & ARIA Snapshots
117
-
118
- > *Borrowed and adapted from the Stagehand primitives (MIT, browserbase/stagehand) and the Playwright MCP accessibility-snapshot contract (Apache-2.0, microsoft/playwright-mcp).*
119
-
120
- Structure every live-browser AI interaction as a three-primitive loop:
121
-
122
- 1. **Observe before acting** — snapshot the current state
123
- (`window.__qa.ariaSnapshot()` — Playwright-MCP-format ARIA tree with
124
- `[ref=eN]` refs — or `getCompactAOM()` for the compact variant) and pick the
125
- target from evidence, never from memory of what the page "should" contain.
126
- 2. **Act on one primitive at a time** — a click, a fill, a press. One action,
127
- one assertion of intent; batch related actions atomically via
128
- `window.__qa.batch()`.
129
- 3. **Extract to assert** — pull the resulting state back out of the page
130
- (ariaSnapshot / AOM / `aiQuery`-style extraction) and assert on the
131
- extracted value; an action without a post-state extraction is unverified.
132
-
133
- Cache-friendliness rule (Stagehand insight): identical observe/act/extract
134
- calls on an unchanged page should be replayable without re-reasoning — record
135
- snapshots and results into the hub memory cache (`cache_resolver`) so repeat
136
- 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.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Playwright Webapp Testing — Enterprise Server-Lifecycle Standard
12
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
+
13
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.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Server Lifecycle Contract
41
+ ### Server Lifecycle Contract
18
42
 
19
43
  ```mermaid
20
44
  flowchart LR
@@ -28,12 +52,13 @@ flowchart LR
28
52
  - Multiple servers (backend + frontend): every server gets its own readiness poll; the suite starts only after ALL are ready.
29
53
  - Teardown is unconditional — a failed test run must still shut down spawned processes (driver/process cleanup mirrors `katalon-cli-runner` discipline).
30
54
 
31
- ## 2. Standard Configuration (Hub Baseline)
55
+ ### Standard Configuration (Hub Baseline)
32
56
 
33
57
  - **Headless mode, 1920x1080 Full HD viewport** — mandatory per `AGENTS.md` Section 2.
34
58
  - Chromium first; multi-browser coverage is governed by `e2e-testing-patterns`.
35
59
  - Launch pattern (Python):
36
60
 
61
+ <!-- classification: illustrative -->
37
62
  ```python
38
63
  from playwright.sync_api import sync_playwright
39
64
 
@@ -50,6 +75,7 @@ with sync_playwright() as p:
50
75
 
51
76
  - Launch pattern (TypeScript / Playwright Test):
52
77
 
78
+ <!-- classification: illustrative -->
53
79
  ```typescript
54
80
  import { test, expect } from '@playwright/test';
55
81
  import { LoginPage } from './pages/LoginPage';
@@ -65,9 +91,10 @@ test('TC-101 User Authentication Flow', async ({ page }) => {
65
91
  });
66
92
  ```
67
93
 
68
- ## 3. Decision Tree: Static vs Dynamic
94
+ ### Decision Tree: Static vs Dynamic
69
95
 
70
- ```
96
+ <!-- classification: illustrative -->
97
+ ```text
71
98
  Task -> Is the page static HTML?
72
99
  |- Yes -> Read the HTML directly to identify selectors, then script.
73
100
  |- No (dynamic webapp) -> Is the server already running?
@@ -75,7 +102,7 @@ Task -> Is the page static HTML?
75
102
  |- Yes -> Reconnaissance-then-action (section 4) on the live app.
76
103
  ```
77
104
 
78
- ## 4. Reconnaissance-Then-Action Pattern
105
+ ### Reconnaissance-Then-Action Pattern
79
106
 
80
107
  For a dynamic app, never guess selectors:
81
108
 
@@ -86,19 +113,19 @@ For a dynamic app, never guess selectors:
86
113
 
87
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.
88
115
 
89
- ## 5. Smart Wait Rules (Zero Static Sleeps)
116
+ ### Smart Wait Rules (Zero Static Sleeps)
90
117
 
91
118
  - FORBIDDEN: `time.sleep()`, `Thread.sleep()`, fixed `wait_for_timeout` as a synchronization strategy (per `AGENTS.md` Section 1).
92
119
  - Required: `wait_for_selector`, `expect` web-first assertions with auto-retry, explicit condition polling, or `wait_for_load_state("networkidle")` with bounded timeout.
93
120
  - `wait_for_timeout` is tolerated only inside after-step settle windows where no condition is observable, and must carry a comment explaining why.
94
121
 
95
- ## 6. Evidence & Debugging Rules
122
+ ### Evidence & Debugging Rules
96
123
 
97
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`).
98
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.
99
126
  - Claims of "suite passes" follow `verification-before-completion`: quote the fresh run output.
100
127
 
101
- ## 7. Boundary vs Sibling Skills (Do Not Confuse)
128
+ ### Boundary vs Sibling Skills (Do Not Confuse)
102
129
 
103
130
  | Sibling | Owns | Hand-off |
104
131
  |---|---|---|
@@ -106,12 +133,28 @@ For a dynamic app, never guess selectors:
106
133
  | `e2e-testing-patterns` | Multi-browser architecture, sharding, retry governance | This skill owns the single-run server lifecycle; suite topology stays with e2e patterns |
107
134
  | `auth-session-and-cookie-manager` | Login states, storageState, multi-role sessions | Complex auth flows inject their storageState before this skill's run starts |
108
135
 
109
- ## 8. Reference Documentation
136
+ ### Reference Documentation
110
137
 
111
138
  - [Server lifecycle example (`server_lifecycle_playwright.py`)](examples/server_lifecycle_playwright.py): readiness-polling wrapper + minimal automation script.
112
139
  - `tools/browser_helpers.js` — in-browser validation engine (safe clicks, form audits, batch verification).
113
140
  - `tools/distill_log.py` — distill verbose run logs by ~95% before attaching to reports.
114
141
 
115
- ## 9. Attribution
142
+ ### Attribution
116
143
 
117
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.
@@ -10,12 +10,36 @@ policies:
10
10
  ---
11
11
  # Web Agent Gym Benchmarking Skill — Empirical Interaction & PageClass Certification
12
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:** Empirical benchmark harness evaluating web agents and Page Classes against standardized enterprise tasks with headless <200ms latency budgets and ground-truth DB state verification. Use when benchmarking web agents or certifying Page Classes.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `web-agent-gym-benchmarking`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT benchmark unconstrained web agents on live production environments without safety sandboxes.
28
+ - Do NOT report synthetic benchmark metrics without recording task provenance and execution metadata.
29
+ - Do NOT alter baseline benchmark scorecards without empirical run data.
30
+ - **Sibling Skill Boundaries:**
31
+ - lean-impact-scoreboard displays consolidated scorecards; web-agent-gym-benchmarking executes the live navigation evaluation benchmarks.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
13
37
  > **Paradigm Attribution:** Inspired by **ServiceNow Research BrowserGym & CMU WebArena**.
14
38
  > **Core Principle:** Move beyond static assertions and text-only tool tests. Measure real agent navigation efficiency, enforce < 200ms headless step latency, and confirm that UI actions trigger ground-truth database mutations (eliminating fake passes).
15
39
 
16
40
  ---
17
41
 
18
- ## 1. The Benchmark Architecture
42
+ ### The Benchmark Architecture
19
43
 
20
44
  ```mermaid
21
45
  flowchart TD
@@ -41,10 +65,11 @@ flowchart TD
41
65
 
42
66
  ---
43
67
 
44
- ## 2. CLI Tool Usage
68
+ ### CLI Tool Usage
45
69
 
46
70
  Autonomous commands via `tools/browsergym_eval.py`:
47
71
 
72
+ <!-- classification: illustrative -->
48
73
  ```bash
49
74
  # 1. Run full benchmark suite in headless mode
50
75
  python tools/browsergym_eval.py run-suite \
@@ -60,8 +85,24 @@ python tools/browsergym_eval.py evaluate-pageclass \
60
85
 
61
86
  ---
62
87
 
63
- ## 3. Strict Operating Invariants
88
+ ### Strict Operating Invariants
64
89
 
65
90
  - **Headless Latency Ceiling:** Average action step latency must remain below **200ms**.
66
91
  - **No Static Sleep:** Any Page Class with `sleep()` calls is automatically flagged as `REJECTED`.
67
92
  - **Clean POM:** Strictly prohibits hardcoded selectors outside Page Classes.
93
+
94
+ ---
95
+
96
+ ## 4. Verification Points & DoD
97
+
98
+ 1. Benchmark tasks execute in isolated sandbox browser environments.
99
+ 2. Run provenance (timestamp, model, task ID, steps taken, success rate) is recorded.
100
+ 3. Output benchmark metrics parse into valid structured JSON.
101
+
102
+ ---
103
+
104
+ ## 5. Handoff Protocol
105
+
106
+ - **Deliverables:** Benchmark execution logs, trajectory recordings, and score summary reports.
107
+ - **Next Subagent:** perf-engineer / orchestrator
108
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.