@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
@@ -28,6 +28,6 @@ When working inside the Hub repository and the user requests *"push lên"*, *"pu
28
28
  - `major`: Breaking changes, major architectural redesigns (`X.0.0`).
29
29
  - **5-Step Autonomous Release Pipeline:**
30
30
  ```bash
31
- python tools/hub_publisher.py
31
+ python tools/hub_publisher.py -y
32
32
  ```
33
- *(Executes: 1. Push to main -> 2. Create & push tag vX.Y.Z -> 3. Create GitHub Release via API -> 4. Build GitHub Package -> 5. Publish & verify NPM registry).*
33
+ *(Executes: 1. Push to main -> 2. Create & push tag vX.Y.Z -> 3. Create GitHub Release via API -> 4. Build GitHub Package -> 5. Publish & verify NPM registry. Use `-y` to confirm non-interactively without stalling).*
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: auth-session-and-cookie-manager
3
3
  description: "Manage browser authentication sessions, storageState, JWT tokens, and multi-role state. Use when managing login sessions, storage state, or cookie reuse across tests."
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
  # Auth Session & Cookie Manager Skill
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:** Manage browser authentication sessions, storageState, JWT tokens, and multi-role state. Use when managing login sessions, storage state, or cookie reuse across tests.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `auth-session-and-cookie-manager`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT store raw plaintext credentials or sensitive auth tokens in version-controlled files.
28
+ - Do NOT execute full UI login journeys repeatedly in every test; use cached session state (`session.json`).
29
+ - Do NOT bypass token expiry checks; validate session freshness before dispatching suites.
30
+ - **Sibling Skill Boundaries:**
31
+ - clean-pom-crafter provides Page Classes; this skill manages session storage, auth cookies, and state caching.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  > **Target:** Eliminate repetitive, slow UI login forms by saving, refreshing, and injecting browser storage states, cookies, and JWT bearer tokens directly into execution contexts.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Core Principles
41
+ ### Core Principles
13
42
 
14
43
  1. **Zero-Second Auth Protocol:**
15
44
  - Execute UI authentication once to produce a verified `session.json` / `storageState.json`.
@@ -28,9 +57,10 @@ description: "Manage browser authentication sessions, storageState, JWT tokens,
28
57
 
29
58
  ---
30
59
 
31
- ## 2. Standard Playwright Implementation Patterns
60
+ ### Standard Playwright Implementation Patterns
32
61
 
33
62
  ### Pattern A: Generating and Reusing Storage State
63
+ <!-- classification: illustrative -->
34
64
  ```typescript
35
65
  // 1. One-time Setup fixture (e.g. auth.setup.ts)
36
66
  import { test as setup, expect } from '@playwright/test';
@@ -49,6 +79,7 @@ setup('authenticate as admin', async ({ page }) => {
49
79
  ```
50
80
 
51
81
  ### Pattern B: Injecting Session Directly (Zero-Second Login)
82
+ <!-- classification: illustrative -->
52
83
  ```typescript
53
84
  // Reusing authenticated session without loading login form
54
85
  import { test } from '@playwright/test';
@@ -62,6 +93,7 @@ test('access protected admin table directly', async ({ page }) => {
62
93
  ```
63
94
 
64
95
  ### Pattern C: Multi-Context Dual Role Testing (Maker vs Checker)
96
+ <!-- classification: illustrative -->
65
97
  ```typescript
66
98
  test('dual-role transaction approval', async ({ browser }) => {
67
99
  // Context 1: Staff creates proposal
@@ -79,6 +111,7 @@ test('dual-role transaction approval', async ({ browser }) => {
79
111
  ```
80
112
 
81
113
  ### Pattern D: Automated Session Teardown & Invalidation
114
+ <!-- classification: illustrative -->
82
115
  ```typescript
83
116
  // auth.teardown.ts / global teardown fixture
84
117
  import { test as teardown } from '@playwright/test';
@@ -93,3 +126,19 @@ teardown('purge ephemeral session states', async () => {
93
126
  }
94
127
  });
95
128
  ```
129
+
130
+ ---
131
+
132
+ ## 4. Verification Points & DoD
133
+
134
+ 1. Session storage state (`session.json`) is captured and validated with valid expiry.
135
+ 2. Auth cookie headers adhere to security standards (HttpOnly, SameSite).
136
+ 3. Zero plaintext credentials committed in test scripts.
137
+
138
+ ---
139
+
140
+ ## 5. Handoff Protocol
141
+
142
+ - **Deliverables:** Saved session state files (`session.json`), reusable auth fixtures, and cookie validation helpers.
143
+ - **Next Subagent:** pom-crafter / test-runner
144
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: bats-testing-patterns
3
3
  description: "Test bash/sh scripts, CLI tools, and CI/CD pipelines with Bats. Use when writing Bash automation tests with the BATS framework."
4
+ category: test_automation_and_execution
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Bats Testing Patterns (Bash Automated Testing System)
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:** Test bash/sh scripts, CLI tools, and CI/CD pipelines with Bats. Use when writing Bash automation tests with the BATS framework.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `bats-testing-patterns`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT use BATS for deep browser UI testing; BATS is strictly for CLI, shell scripts, and system utilities.
28
+ - Do NOT rely on persistent local host environment state; all test fixtures must run in sandbox subshells.
29
+ - Do NOT suppress shell exit codes; assert on exact exit codes ($status) and command output ($output).
30
+ - **Sibling Skill Boundaries:**
31
+ - katalon-cli-runner and playwright-webapp-testing handle web automation; bats-testing-patterns handles shell and CLI automation.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Comprehensive test engineering standard for validating shell scripts, CI/CD scripts (`.sh`), CLI wrappers, and DevOps automation using Bats-core.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Core Principles
41
+ ### Core Principles
13
42
 
14
43
  1. **Deterministic Exit Codes:** Every script assertion must explicitly assert `$status` (0 for success, non-zero for explicit failure vectors).
15
44
  2. **Standard Output & Error Isolation:** Assert exact error strings in `${lines[@]}` or `$output`.
@@ -18,8 +47,9 @@ Comprehensive test engineering standard for validating shell scripts, CI/CD scri
18
47
 
19
48
  ---
20
49
 
21
- ## 2. Standard Test Architecture & Setup
50
+ ### Standard Test Architecture & Setup
22
51
 
52
+ <!-- classification: illustrative -->
23
53
  ```bash
24
54
  #!/usr/bin/env bats
25
55
 
@@ -42,9 +72,10 @@ teardown() {
42
72
 
43
73
  ---
44
74
 
45
- ## 3. Production Test Patterns
75
+ ### Production Test Patterns
46
76
 
47
77
  ### Pattern A: Exit Code and Output Verification
78
+ <!-- classification: illustrative -->
48
79
  ```bash
49
80
  @test "script fails gracefully when required parameter is missing" {
50
81
  run ./scripts/deploy.sh
@@ -60,6 +91,7 @@ teardown() {
60
91
  ```
61
92
 
62
93
  ### Pattern B: Mocking Destructive CLI Tools
94
+ <!-- classification: illustrative -->
63
95
  ```bash
64
96
  @test "mock curl API failure triggers automatic retry loop" {
65
97
  MOCK_DIR="${TEST_DIR}/bin"
@@ -81,6 +113,7 @@ EOF
81
113
  ```
82
114
 
83
115
  ### Pattern C: File Creation & Mutation Verification
116
+ <!-- classification: illustrative -->
84
117
  ```bash
85
118
  @test "script generates valid JSON report on completion" {
86
119
  run ./scripts/generate_report.sh --output "${TEST_DIR}/summary.json"
@@ -93,8 +126,25 @@ EOF
93
126
 
94
127
  ---
95
128
 
96
- ## 4. CI/CD Pipeline Execution
129
+ ### CI/CD Pipeline Execution
130
+ <!-- classification: illustrative -->
97
131
  ```bash
98
132
  # Execute full Bats test suite with JUnit report output for CI
99
133
  bats test/*.bats --formatter junit > test-results.xml
100
134
  ```
135
+
136
+ ---
137
+
138
+ ## 4. Verification Points & DoD
139
+
140
+ 1. All BATS test files (`.bats`) pass syntax check (`bats -c`).
141
+ 2. Tests execute hermetically within temporary sandbox directories.
142
+ 3. Exit status and stdout assertions validate real command behavior.
143
+
144
+ ---
145
+
146
+ ## 5. Handoff Protocol
147
+
148
+ - **Deliverables:** BATS test suites (`tests/*.bats`), helper libraries, and CI execution scripts.
149
+ - **Next Subagent:** test-runner / quality-gatekeeper
150
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,36 +1,58 @@
1
1
  ---
2
2
  name: clean-pom-crafter
3
3
  description: "Build and refactor Clean POM Page Classes adhering to Flat Architecture standards. Use when designing Clean POM page classes or enforcing zero-locator discipline in scripts."
4
+ category: test_automation_and_execution
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # Clean POM Crafter — Enterprise Clean POM Architecture Standards
7
12
 
8
- Specialized skill for creating, refactoring, and standardizing test automation scripts using **Clean Page Object Model (POM)** and **Flat Architecture** across enterprise test suites.
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 creating, refactoring, or standardizing test automation Page Classes, enforcing Clean Page Object Model (POM) separation, or applying the 6-tier locator hierarchy.
20
+ - **Activation Scope:**
21
+ - Page Classes in `pages/*.ts`, `pages/*.py`, or `Keywords/<namespace>/pages/*.groovy`.
22
+ - Elimination of raw XPaths and CSS selectors from test scripts (`tests/`, `Scripts/`).
23
+ - BasePage inheritance and smart wait encapsulation.
24
+
25
+ ---
26
+
27
+ ## 2. Non-Goals & Boundary Constraints
9
28
 
10
- > 💡 **Skill Boundary Clarification:**
11
- > - **`clean-pom-crafter`** (this skill): Focuses on the **Page Class Layer** — designing `BasePage` subclasses, enforcing the 6-tier locator hierarchy, and encapsulating UI selectors.
12
- > - **`lam-script-generator`**: Focuses on the **Test Script Workflow Layer** — transforming User Stories and Acceptance Criteria into high-level business workflow test scripts (`TC-xxx`) calling Page Classes.
29
+ - **What NOT to do:**
30
+ - Do NOT place raw XPaths, CSS selectors, or `findTestObject` calls inside test scripts.
31
+ - Do NOT create deep Page Object inheritance hierarchies; keep inheritance flat (maximum 1 level from `BasePage`).
32
+ - Do NOT use absolute positional XPaths (`//tbody/tr[1]/td[6]/button[2]`) or dynamic hash classes (`.p-element-1n2xyz`).
33
+ - Do NOT read monolithic Page Class files (> 100KB) into LLM context; use line-range targeted reads or `tools/lookup_xpath.py`.
34
+ - **Sibling Skill Boundaries:**
35
+ - `clean-pom-crafter` (this skill): Focuses on the **Page Class Layer** — designing `BasePage` subclasses, enforcing locator hierarchy, and encapsulating UI selectors.
36
+ - `lam-script-generator`: Focuses on the **Test Script Workflow Layer** — transforming User Stories into business workflow test scripts (`TC-xxx`) calling Page Classes.
37
+ - `playwright-live-interaction`: Probes live DOM/AOM to discover verified selector contracts.
13
38
 
14
39
  ---
15
40
 
16
- ## 1. Core Architectural Principles
41
+ ## 3. Ordered Execution Workflow
42
+
43
+ ### Phase 1: Core Architectural Principles
17
44
 
18
45
  1. **Flat Architecture:**
19
- - All `Test Cases/`, `Scripts/`, and `Test Suites/` reside directly in their parent directory (no module subfolders).
20
- - Naming convention: `TC-<Number>_<FeatureName>`, e.g. `TC-101_CreateUserAccount.groovy` or `tc-101-create-user.spec.ts`.
46
+ - All test cases and scripts reside directly in their parent directory (no nested module subfolders).
47
+ - Naming convention: `TC-<Number>_<FeatureName>` (e.g. `TC-101_CreateUserAccount.groovy` or `tc-101-create-user.spec.ts`).
21
48
  2. **Unified Inheritance from `BasePage`:**
22
- - All Page Classes in `Keywords/<project_namespace>/pages/` (or `pages/*.ts` in Playwright/TS) inherit from `BasePage`.
23
- 3. **Zero Raw XPaths in Test Scripts:**
24
- - Scripts (`Scripts/TC-xxx_*.groovy` or `tests/*.spec.ts`) only orchestrate business workflows. All locators and UI interactions are encapsulated in Page Classes.
49
+ - All Page Classes inherit from `BasePage`.
50
+ 3. **Zero Raw Locators in Scripts:**
51
+ - Scripts only orchestrate business workflows. All locators and UI interactions are encapsulated in Page Classes.
25
52
  4. **Mandatory 100% UTF-8 No BOM:**
26
- - All `.groovy`, `.java`, `.ts`, `.tc` files must NEVER contain UTF-8 BOM bytes (`0xEF, 0xBB, 0xBF`).
27
- 5. **Context Window Protection (Zero-Token Economy):**
28
- - 🚫 **NEVER read entire monolithic Page Class files (> 100KB) into LLM context.**
29
- - Always use `python tools/lookup_xpath.py <keyword>` or line-range targeted reads (`read_file` with `StartLine`/`EndLine`) to find selectors and methods on demand.
30
-
31
- ---
53
+ - Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all test files.
32
54
 
33
- ## 2. Master Locator Priority Map (6 Tiers)
55
+ ### Phase 2: Master Locator Priority Map (6 Tiers)
34
56
 
35
57
  All Page Classes **MUST** follow this strict locator hierarchy:
36
58
  1. **Tier 1 — Angular Semantic / ARIA:** `[formcontrolname="..."]`, `[aria-label="..."]`, `[role="..."]`.
@@ -40,20 +62,7 @@ All Page Classes **MUST** follow this strict locator hierarchy:
40
62
  5. **Tier 5 — Resilient CSS Selectors:** `.card.popup-data input.p-inputtext`.
41
63
  6. **Tier 6 — Relative XPath (Last Resort):** `//div[contains(@class, 'card')]//button[contains(., 'Confirm')]`.
42
64
 
43
- > 🚫 **FORBIDDEN:** Absolute positional XPaths (`//tbody/tr[1]/td[6]/button[2]`) and dynamic hash classes (`.p-element-1n2xyz`).
44
-
45
- ---
46
-
47
- ## 3. Test Data Management & Cross-Module Data Chain
48
-
49
- - **Supporting Field:** Generate dynamically using `BasePage.uniqueCode(prefix)` (e.g. `BasePage.uniqueCode("AUTO_")`).
50
- - **Dimension Field:** Fixed category values selected from dropdowns (`"Active"`, `"Standard"`).
51
- - **Reference Field:** Pass output records from prior TCs into subsequent TCs (Create -> Edit -> Delete).
52
- - **Computed Field:** Auto-calculated system metrics; assert 100% exact match.
53
-
54
- ---
55
-
56
- ## 4. Universal Page Object Architecture Model
65
+ ### Phase 3: Universal Page Object Model Reference
57
66
 
58
67
  | No. | Page Class Role | Functional Module | Typical Test Scope | Core Methods & Responsibilities |
59
68
  |:---:|---|---|:---:|---|
@@ -61,50 +70,36 @@ All Page Classes **MUST** follow this strict locator hierarchy:
61
70
  | 2 | `LoginPage` | Authentication & User Profile | Auth & Session | `login()`, `logout()`, `verifyUserProfile()` |
62
71
  | 3 | `UserAdminPage` | System Administration & Users | Admin / RBAC | `createUser()`, `assignRole()`, `filterUsers()` |
63
72
  | 4 | `CommonCategoryPage` | Common Categories & System Catalogs | Catalogs & Lookups | `addCategory()`, `editCategory()`, `verifyCatalog()` |
64
- | 5 | `WorkflowPlanningPage`| Sector Planning & Approvals | Workflows & Approvals | `createPlan()`, `submitForReview()`, `approvePlan()` |
65
- | 6 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
66
- | 7 | `ReportAnalyticsPage` | Statistical Reporting & Dashboards | Reporting | `generateReport()`, `exportExcel()`, `verifyKPI()` |
67
- | 8 | `ApiTokenMgmtPage` | Data Sharing & API Tokens | API & Integration | `generateToken()`, `revokeToken()`, `verifyScopes()` |
68
-
69
- ---
73
+ | 5 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
70
74
 
71
- ## 5. Implementation References & Examples
75
+ ### Phase 4: Implementation References
72
76
 
73
- - [**Standard Clean POM Methods (`pom_patterns.groovy`)**](references/pom_patterns.groovy): Full implementation of `searchRecord`, `editRecord`, `deleteRecord`, `setCalendarDate`, `selectMultiOptions`, `verifyRecordExists`, `verifyRecordNotExists`, `jsSetInput`.
77
+ - [**Standard Clean POM Methods (`pom_patterns.groovy`)**](references/pom_patterns.groovy): Full implementation of `searchRecord`, `editRecord`, `deleteRecord`, `setCalendarDate`, `selectMultiOptions`.
74
78
  - [**Standard Test Script Template (`standard_test_case.groovy`)**](examples/standard_test_case.groovy): 7-step complete script template from Login -> Create -> Search -> Edit -> Delete.
75
- - [**Zero-Token XPath Lookup (`tools/lookup_xpath.py`)**](../../../tools/lookup_xpath.py): Command `python tools/lookup_xpath.py <PageClass>` returns exact locators in <200 tokens without parsing full files.
76
- - [**Browser Runtime Helper (`tools/browser_helpers.js`)**](../../../tools/browser_helpers.js): In-browser validation engine for form audits, safe clicks, and batch verification.
79
+ - **Zero-Token XPath Lookup (`tools/lookup_xpath.py`):** Targeted locator retrieval in under 200 tokens.
80
+ - **Browser Runtime Helper (`tools/browser_helpers.js`):** In-browser validation engine for form audits, safe clicks, and batch verification.
77
81
 
78
- ---
82
+ ### Phase 5: Anti-Junk Test Protocol & Authoring Gate
79
83
 
80
- ## 6. Boundary: Three Ingress Points, One Codification Target
84
+ Before authoring or modifying any automated test script or Page Class, pass this **4-Question Authoring Gate**:
85
+ 1. **Observable Contract:** Does this test protect an observable user/business behavior, invariant, or independent contract?
86
+ 2. **Credible Regression:** Is there a credible, realistic regression scenario that causes this test to fail?
87
+ 3. **Primary Boundary:** Why does existing proof miss it? Every contract belongs to one primary owner at the strongest boundary.
88
+ 4. **Zero Test-Only Seams:** Does this test require synthetic flags, wrappers, or public methods in Page Classes that have no real production caller?
81
89
 
82
- `clean-pom-crafter` is the codification layer — it owns Page Class design and
83
- the zero-raw-locator discipline. Test *sources* arrive from three siblings and
84
- must not be re-invented here:
90
+ ---
85
91
 
86
- | Source skill | Input | Hands over |
87
- | :--- | :--- | :--- |
88
- | `gherkin-to-suite` | `.feature` BDD specs | Test matrix + Universal IR |
89
- | `lam-script-generator` | User stories / acceptance criteria | Action-sequence script skeletons |
90
- | `playwright-live-interaction` | Live DOM/AOM survey | Verified selector contracts |
92
+ ## 4. Verification Points & DoD
91
93
 
92
- Rule: upstream skills produce intents and IR; **only this skill** turns them
93
- into Page Classes with real locators (with `playwright-live-interaction`
94
- supplying the verified selectors).
94
+ 1. **Zero Raw Locators:** 0 occurrences of XPaths or CSS selectors inside test scripts (`tests/`, `Scripts/`).
95
+ 2. **Inheritance Depth:** Page Classes extend `BasePage` directly with inheritance depth $\le 1$.
96
+ 3. **Encoding:** 100% UTF-8 No BOM across all generated Page Classes and scripts.
97
+ 4. **Smart Waits:** 0 static sleeps (`Thread.sleep`, `time.sleep`).
95
98
 
96
99
  ---
97
100
 
98
- ## 7. Anti-Junk Test Protocol & Authoring Gate (Inspired by test-audit)
99
-
100
- Before authoring or modifying any automated test script or Page Class, pass this **4-Question Authoring Gate**:
101
- 1. **Observable Contract:** Does this test protect an observable user/business behavior, invariant, or independent contract?
102
- 2. **Credible Regression:** Is there a credible, realistic regression scenario that causes this test to fail?
103
- 3. **Primary Boundary:** Why does existing proof miss it? Every contract belongs to one primary owner at the strongest boundary.
104
- 4. **Zero Test-Only Seams:** Does this test require synthetic flags, wrappers, or public methods in Page Classes that have no real production caller? If so, move proof to the real boundary.
101
+ ## 5. Handoff Protocol
105
102
 
106
- ### Strict Junk Patterns Blacklist
107
- - 🚫 **Mocks Asserting Mocks:** Verifying that a mocked service returned the mock data that the test itself injected.
108
- - 🚫 **Implementation Coupling:** Tests asserting internal method call sequences or private helpers that fail during behavior-preserving refactoring.
109
- - 🚫 **Duplicate Contracts:** Replaying the exact same contract validation across multiple crossed layers without distinct transport/lifecycle risk.
110
- - 🚫 **Test-Only Seams:** Polluting Page Classes with backdoor test methods not reflective of real user journeys.
103
+ - **Deliverables:** Clean POM Page Classes extending `BasePage` with encapsulated locators and business methods.
104
+ - **Next Subagent:** Pass to `lam-script-generator` for test script authoring or `test-runner` for execution.
105
+ - **Output Format:** Clean Page Class source file (`.ts`, `.groovy`, `.py`) with complete method docstrings.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: e2e-testing-patterns
3
3
  description: "Design robust multi-browser E2E test architectures, parallel sharding, and retry governance. Use when designing end-to-end test suites for web applications."
4
+ category: test_automation_and_execution
5
+ version: "2.0.0"
6
+ policies:
7
+ network: none
8
+ shell: workspace-sandbox
9
+ filesystem: workspace-sandbox
4
10
  ---
5
-
6
11
  # E2E Testing Architectural Patterns
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:** Design robust multi-browser E2E test architectures, parallel sharding, and retry governance. Use when designing end-to-end test suites for web applications.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `e2e-testing-patterns`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT duplicate unit or integration test coverage in end-to-end suites (respect the test pyramid).
28
+ - Do NOT write monolithic multi-feature test scripts; keep scenarios focused on single business journeys.
29
+ - Do NOT permit arbitrary static delays (`Thread.sleep`, `time.sleep`).
30
+ - **Sibling Skill Boundaries:**
31
+ - api-spec-to-e2e-matrix owns API contract matrices; e2e-testing-patterns owns full-stack user journeys across browser harnesses.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Engineering standard for structuring, scaling, and maintaining large-scale End-to-End (E2E) test automation suites across modern web frameworks (React, Angular, Vue, Next.js).
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Test Pyramid & E2E Scope Boundary
41
+ ### Test Pyramid & E2E Scope Boundary
13
42
 
14
43
  ```mermaid
15
44
  flowchart TD
@@ -25,9 +54,10 @@ flowchart TD
25
54
 
26
55
  ---
27
56
 
28
- ## 2. Core Operational Patterns
57
+ ### Core Operational Patterns
29
58
 
30
59
  ### Pattern A: Clean Page Object Model (POM) with Typed Interfaces
60
+ <!-- classification: illustrative -->
31
61
  ```typescript
32
62
  // pages/base.page.ts
33
63
  import { Page, Locator, expect } from '@playwright/test';
@@ -46,6 +76,7 @@ export abstract class BasePage {
46
76
  }
47
77
  ```
48
78
 
79
+ <!-- classification: illustrative -->
49
80
  ```typescript
50
81
  // pages/checkout.page.ts
51
82
  import { Locator, expect } from '@playwright/test';
@@ -63,6 +94,7 @@ export class CheckoutPage extends BasePage {
63
94
  ```
64
95
 
65
96
  ### Pattern B: Isolated Storage State Fixture (Zero Login Repetition)
97
+ <!-- classification: illustrative -->
66
98
  ```typescript
67
99
  // fixtures/auth.fixture.ts
68
100
  import { test as base, Page } from '@playwright/test';
@@ -78,6 +110,7 @@ export const test = base.extend<{ authedPage: Page }>({
78
110
  ```
79
111
 
80
112
  ### Pattern C: Resilient Synchronization (No Static Delays)
113
+ <!-- classification: illustrative -->
81
114
  ```typescript
82
115
  // ANTI-PATTERN:
83
116
  // await page.waitForTimeout(5000); // Flaky and slow!
@@ -94,10 +127,27 @@ await expect(page.getByText('Order Created')).toBeVisible();
94
127
 
95
128
  ---
96
129
 
97
- ## 3. Parallel Sharding & CI/CD Governance
130
+ ### Parallel Sharding & CI/CD Governance
131
+ <!-- classification: illustrative -->
98
132
  ```bash
99
133
  # Run test suite sharded across 4 parallel CI workers
100
134
  npx playwright test --shard=1/4 --reporter=html,junit:results.xml
101
135
  ```
102
136
  - **Retries:** Maximum 1 retry on CI, 0 retries locally. Never rely on retries to mask structural flakiness.
103
137
  - **Trace on Failure:** Always configure `trace: 'retain-on-failure'` and `screenshot: 'only-on-failure'`.
138
+
139
+ ---
140
+
141
+ ## 4. Verification Points & DoD
142
+
143
+ 1. Test scenarios map to critical business user journeys with explicit assertions.
144
+ 2. Test data is dynamic, randomized, and paired with automated cleanup.
145
+ 3. Zero raw XPaths or CSS locators inside test scripts (Clean POM adherence).
146
+
147
+ ---
148
+
149
+ ## 5. Handoff Protocol
150
+
151
+ - **Deliverables:** End-to-end test specs, test suite configurations, and parallel execution matrix.
152
+ - **Next Subagent:** test-runner / quality-gatekeeper
153
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.
@@ -1,15 +1,44 @@
1
1
  ---
2
2
  name: katalon-cli-runner
3
3
  description: "Execute headless Katalon and Gradle test runners with automatic driver cleanup. Use when running Katalon suites headless or integrating KRE into CI/CD."
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
  # Katalon CLI & Enterprise Runner — Dual-Mode Execution Management
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:** Execute headless Katalon and Gradle test runners with automatic driver cleanup. Use when running Katalon suites headless or integrating KRE into CI/CD.
20
+ - **Activation Scope:** Domain workflows for `01-web-automation` involving `katalon-cli-runner`.
21
+
22
+ ---
23
+
24
+ ## 2. Non-Goals & Boundary Constraints
25
+
26
+ - **What NOT to do:**
27
+ - Do NOT leave orphaned Katalon or browser driver processes running after execution.
28
+ - Do NOT commit hardcoded license API keys in command scripts; read from secure environment variables.
29
+ - Do NOT bypass pre-flight health checks before launching headless runs.
30
+ - **Sibling Skill Boundaries:**
31
+ - playwright-webapp-testing handles Playwright harnesses; katalon-cli-runner handles Katalon Studio engine CLI execution.
32
+
33
+ ---
34
+
35
+ ## 3. Ordered Execution Workflow
36
+
8
37
  Specialized skill for managing, dispatching, and monitoring enterprise Katalon test runs across different licensing states (**Licensed Headless KRE** vs **Free Community Mode**), integrated with Allure reporting and automated driver cleanup.
9
38
 
10
39
  ---
11
40
 
12
- ## 1. Adaptive Dual-Mode Execution Strategy
41
+ ### Adaptive Dual-Mode Execution Strategy
13
42
 
14
43
  | Licensing State | Recommended Mode | Response Time | Licensing Cost |
15
44
  |---|---|:---:|:---:|
@@ -19,9 +48,10 @@ Specialized skill for managing, dispatching, and monitoring enterprise Katalon t
19
48
 
20
49
  ---
21
50
 
22
- ## 2. Pre-Flight Quality Check
51
+ ### Pre-Flight Quality Check
23
52
 
24
53
  Before launching heavy CLI runs, execute fast pre-flight verification:
54
+ <!-- classification: illustrative -->
25
55
  ```bash
26
56
  python3 -c "
27
57
  import glob
@@ -34,24 +64,27 @@ print('[PASS] Pre-flight passed: 100% UTF-8 No BOM')
34
64
 
35
65
  ---
36
66
 
37
- ## 3. License Recovery & Process Cleanup
67
+ ### License Recovery & Process Cleanup
38
68
 
39
69
  1. **License Expiration Handling:** When `License quota exceeded` occurs, halt batch retries immediately and switch to Playwright live validation or local GUI.
40
70
  2. **Zombie Chromedriver & Java Process Termination:**
41
- ```powershell
71
+ <!-- classification: illustrative -->
72
+ ```powershell
42
73
  # Windows process cleanup
43
74
  Get-Process -Name "chromedriver", "katalon" -ErrorAction SilentlyContinue | Stop-Process -Force
44
- ```
45
- ```bash
75
+ ```
76
+ <!-- classification: illustrative -->
77
+ ```bash
46
78
  # Unix process cleanup
47
79
  pkill -f chromedriver || true
48
80
  pkill -f katalon || true
49
- ```
81
+ ```
50
82
 
51
83
  ---
52
84
 
53
- ## 4. Standard Headless Execution Commands
85
+ ### Standard Headless Execution Commands
54
86
 
87
+ <!-- classification: illustrative -->
55
88
  ```bash
56
89
  # Execute specific Test Suite via KRE CLI in pure headless mode
57
90
  katalonc -noSplash -runMode=console \
@@ -65,12 +98,29 @@ katalonc -noSplash -runMode=console \
65
98
 
66
99
  ---
67
100
 
68
- ## 5. Definition of Done (DoD)
101
+ ### Definition of Done (DoD)
69
102
 
70
103
  1. **Exit Code = 0:** Runner completes cleanly without runtime crash.
71
104
  2. **Clean JUnit XML:** Results XML contains 0 `<failure>` or `<error>` tags.
72
105
  3. **Compile Allure Report:** `allure generate ./allure-results -o ./Reports/allure-report --clean`.
73
106
  4. If failures occur, immediately dispatch failure autopsy:
74
- ```bash
107
+ <!-- classification: illustrative -->
108
+ ```bash
75
109
  python tools/pinpoint_failure.py
76
- ```
110
+ ```
111
+
112
+ ---
113
+
114
+ ## 4. Verification Points & DoD
115
+
116
+ 1. Katalon execution command builds with valid CLI parameters and dynamic retry count.
117
+ 2. Pre-flight environment validation confirms binary and license availability.
118
+ 3. Process cleanup traps terminate hanging child processes on exit.
119
+
120
+ ---
121
+
122
+ ## 5. Handoff Protocol
123
+
124
+ - **Deliverables:** Katalon CLI execution scripts, execution profiles, and JUnit/Allure report artifacts.
125
+ - **Next Subagent:** test-runner
126
+ - **Output Format:** Clean POM code, structured JSON telemetry, or validated markdown handoff.