@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
  # Auth Session & Cookie Manager Skill
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:** 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
+
13
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.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Core Principles
41
+ ### Core Principles
18
42
 
19
43
  1. **Zero-Second Auth Protocol:**
20
44
  - Execute UI authentication once to produce a verified `session.json` / `storageState.json`.
@@ -33,9 +57,10 @@ policies:
33
57
 
34
58
  ---
35
59
 
36
- ## 2. Standard Playwright Implementation Patterns
60
+ ### Standard Playwright Implementation Patterns
37
61
 
38
62
  ### Pattern A: Generating and Reusing Storage State
63
+ <!-- classification: illustrative -->
39
64
  ```typescript
40
65
  // 1. One-time Setup fixture (e.g. auth.setup.ts)
41
66
  import { test as setup, expect } from '@playwright/test';
@@ -54,6 +79,7 @@ setup('authenticate as admin', async ({ page }) => {
54
79
  ```
55
80
 
56
81
  ### Pattern B: Injecting Session Directly (Zero-Second Login)
82
+ <!-- classification: illustrative -->
57
83
  ```typescript
58
84
  // Reusing authenticated session without loading login form
59
85
  import { test } from '@playwright/test';
@@ -67,6 +93,7 @@ test('access protected admin table directly', async ({ page }) => {
67
93
  ```
68
94
 
69
95
  ### Pattern C: Multi-Context Dual Role Testing (Maker vs Checker)
96
+ <!-- classification: illustrative -->
70
97
  ```typescript
71
98
  test('dual-role transaction approval', async ({ browser }) => {
72
99
  // Context 1: Staff creates proposal
@@ -84,6 +111,7 @@ test('dual-role transaction approval', async ({ browser }) => {
84
111
  ```
85
112
 
86
113
  ### Pattern D: Automated Session Teardown & Invalidation
114
+ <!-- classification: illustrative -->
87
115
  ```typescript
88
116
  // auth.teardown.ts / global teardown fixture
89
117
  import { test as teardown } from '@playwright/test';
@@ -98,3 +126,19 @@ teardown('purge ephemeral session states', async () => {
98
126
  }
99
127
  });
100
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.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Bats Testing Patterns (Bash Automated Testing System)
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:** 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
+
13
37
  Comprehensive test engineering standard for validating shell scripts, CI/CD scripts (`.sh`), CLI wrappers, and DevOps automation using Bats-core.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Core Principles
41
+ ### Core Principles
18
42
 
19
43
  1. **Deterministic Exit Codes:** Every script assertion must explicitly assert `$status` (0 for success, non-zero for explicit failure vectors).
20
44
  2. **Standard Output & Error Isolation:** Assert exact error strings in `${lines[@]}` or `$output`.
@@ -23,8 +47,9 @@ Comprehensive test engineering standard for validating shell scripts, CI/CD scri
23
47
 
24
48
  ---
25
49
 
26
- ## 2. Standard Test Architecture & Setup
50
+ ### Standard Test Architecture & Setup
27
51
 
52
+ <!-- classification: illustrative -->
28
53
  ```bash
29
54
  #!/usr/bin/env bats
30
55
 
@@ -47,9 +72,10 @@ teardown() {
47
72
 
48
73
  ---
49
74
 
50
- ## 3. Production Test Patterns
75
+ ### Production Test Patterns
51
76
 
52
77
  ### Pattern A: Exit Code and Output Verification
78
+ <!-- classification: illustrative -->
53
79
  ```bash
54
80
  @test "script fails gracefully when required parameter is missing" {
55
81
  run ./scripts/deploy.sh
@@ -65,6 +91,7 @@ teardown() {
65
91
  ```
66
92
 
67
93
  ### Pattern B: Mocking Destructive CLI Tools
94
+ <!-- classification: illustrative -->
68
95
  ```bash
69
96
  @test "mock curl API failure triggers automatic retry loop" {
70
97
  MOCK_DIR="${TEST_DIR}/bin"
@@ -86,6 +113,7 @@ EOF
86
113
  ```
87
114
 
88
115
  ### Pattern C: File Creation & Mutation Verification
116
+ <!-- classification: illustrative -->
89
117
  ```bash
90
118
  @test "script generates valid JSON report on completion" {
91
119
  run ./scripts/generate_report.sh --output "${TEST_DIR}/summary.json"
@@ -98,8 +126,25 @@ EOF
98
126
 
99
127
  ---
100
128
 
101
- ## 4. CI/CD Pipeline Execution
129
+ ### CI/CD Pipeline Execution
130
+ <!-- classification: illustrative -->
102
131
  ```bash
103
132
  # Execute full Bats test suite with JUnit report output for CI
104
133
  bats test/*.bats --formatter junit > test-results.xml
105
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.
@@ -10,32 +10,49 @@ policies:
10
10
  ---
11
11
  # Clean POM Crafter — Enterprise Clean POM Architecture Standards
12
12
 
13
- 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
14
 
15
- > 💡 **Skill Boundary Clarification:**
16
- > - **`clean-pom-crafter`** (this skill): Focuses on the **Page Class Layer** — designing `BasePage` subclasses, enforcing the 6-tier locator hierarchy, and encapsulating UI selectors.
17
- > - **`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.
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
28
+
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.
18
38
 
19
39
  ---
20
40
 
21
- ## 1. Core Architectural Principles
41
+ ## 3. Ordered Execution Workflow
42
+
43
+ ### Phase 1: Core Architectural Principles
22
44
 
23
45
  1. **Flat Architecture:**
24
- - All `Test Cases/`, `Scripts/`, and `Test Suites/` reside directly in their parent directory (no module subfolders).
25
- - 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`).
26
48
  2. **Unified Inheritance from `BasePage`:**
27
- - All Page Classes in `Keywords/<project_namespace>/pages/` (or `pages/*.ts` in Playwright/TS) inherit from `BasePage`.
28
- 3. **Zero Raw XPaths in Test Scripts:**
29
- - 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.
30
52
  4. **Mandatory 100% UTF-8 No BOM:**
31
- - All `.groovy`, `.java`, `.ts`, `.tc` files must NEVER contain UTF-8 BOM bytes (`0xEF, 0xBB, 0xBF`).
32
- 5. **Context Window Protection (Zero-Token Economy):**
33
- - 🚫 **NEVER read entire monolithic Page Class files (> 100KB) into LLM context.**
34
- - 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.
53
+ - Zero BOM bytes (`0xEF, 0xBB, 0xBF`) across all test files.
35
54
 
36
- ---
37
-
38
- ## 2. Master Locator Priority Map (6 Tiers)
55
+ ### Phase 2: Master Locator Priority Map (6 Tiers)
39
56
 
40
57
  All Page Classes **MUST** follow this strict locator hierarchy:
41
58
  1. **Tier 1 — Angular Semantic / ARIA:** `[formcontrolname="..."]`, `[aria-label="..."]`, `[role="..."]`.
@@ -45,20 +62,7 @@ All Page Classes **MUST** follow this strict locator hierarchy:
45
62
  5. **Tier 5 — Resilient CSS Selectors:** `.card.popup-data input.p-inputtext`.
46
63
  6. **Tier 6 — Relative XPath (Last Resort):** `//div[contains(@class, 'card')]//button[contains(., 'Confirm')]`.
47
64
 
48
- > 🚫 **FORBIDDEN:** Absolute positional XPaths (`//tbody/tr[1]/td[6]/button[2]`) and dynamic hash classes (`.p-element-1n2xyz`).
49
-
50
- ---
51
-
52
- ## 3. Test Data Management & Cross-Module Data Chain
53
-
54
- - **Supporting Field:** Generate dynamically using `BasePage.uniqueCode(prefix)` (e.g. `BasePage.uniqueCode("AUTO_")`).
55
- - **Dimension Field:** Fixed category values selected from dropdowns (`"Active"`, `"Standard"`).
56
- - **Reference Field:** Pass output records from prior TCs into subsequent TCs (Create -> Edit -> Delete).
57
- - **Computed Field:** Auto-calculated system metrics; assert 100% exact match.
58
-
59
- ---
60
-
61
- ## 4. Universal Page Object Architecture Model
65
+ ### Phase 3: Universal Page Object Model Reference
62
66
 
63
67
  | No. | Page Class Role | Functional Module | Typical Test Scope | Core Methods & Responsibilities |
64
68
  |:---:|---|---|:---:|---|
@@ -66,50 +70,36 @@ All Page Classes **MUST** follow this strict locator hierarchy:
66
70
  | 2 | `LoginPage` | Authentication & User Profile | Auth & Session | `login()`, `logout()`, `verifyUserProfile()` |
67
71
  | 3 | `UserAdminPage` | System Administration & Users | Admin / RBAC | `createUser()`, `assignRole()`, `filterUsers()` |
68
72
  | 4 | `CommonCategoryPage` | Common Categories & System Catalogs | Catalogs & Lookups | `addCategory()`, `editCategory()`, `verifyCatalog()` |
69
- | 5 | `WorkflowPlanningPage`| Sector Planning & Approvals | Workflows & Approvals | `createPlan()`, `submitForReview()`, `approvePlan()` |
70
- | 6 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
71
- | 7 | `ReportAnalyticsPage` | Statistical Reporting & Dashboards | Reporting | `generateReport()`, `exportExcel()`, `verifyKPI()` |
72
- | 8 | `ApiTokenMgmtPage` | Data Sharing & API Tokens | API & Integration | `generateToken()`, `revokeToken()`, `verifyScopes()` |
73
-
74
- ---
73
+ | 5 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
75
74
 
76
- ## 5. Implementation References & Examples
75
+ ### Phase 4: Implementation References
77
76
 
78
- - [**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`.
79
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.
80
- - [**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.
81
- - [**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.
82
81
 
83
- ---
82
+ ### Phase 5: Anti-Junk Test Protocol & Authoring Gate
84
83
 
85
- ## 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?
86
89
 
87
- `clean-pom-crafter` is the codification layer — it owns Page Class design and
88
- the zero-raw-locator discipline. Test *sources* arrive from three siblings and
89
- must not be re-invented here:
90
+ ---
90
91
 
91
- | Source skill | Input | Hands over |
92
- | :--- | :--- | :--- |
93
- | `gherkin-to-suite` | `.feature` BDD specs | Test matrix + Universal IR |
94
- | `lam-script-generator` | User stories / acceptance criteria | Action-sequence script skeletons |
95
- | `playwright-live-interaction` | Live DOM/AOM survey | Verified selector contracts |
92
+ ## 4. Verification Points & DoD
96
93
 
97
- Rule: upstream skills produce intents and IR; **only this skill** turns them
98
- into Page Classes with real locators (with `playwright-live-interaction`
99
- 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`).
100
98
 
101
99
  ---
102
100
 
103
- ## 7. Anti-Junk Test Protocol & Authoring Gate (Inspired by test-audit)
104
-
105
- Before authoring or modifying any automated test script or Page Class, pass this **4-Question Authoring Gate**:
106
- 1. **Observable Contract:** Does this test protect an observable user/business behavior, invariant, or independent contract?
107
- 2. **Credible Regression:** Is there a credible, realistic regression scenario that causes this test to fail?
108
- 3. **Primary Boundary:** Why does existing proof miss it? Every contract belongs to one primary owner at the strongest boundary.
109
- 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
110
102
 
111
- ### Strict Junk Patterns Blacklist
112
- - 🚫 **Mocks Asserting Mocks:** Verifying that a mocked service returned the mock data that the test itself injected.
113
- - 🚫 **Implementation Coupling:** Tests asserting internal method call sequences or private helpers that fail during behavior-preserving refactoring.
114
- - 🚫 **Duplicate Contracts:** Replaying the exact same contract validation across multiple crossed layers without distinct transport/lifecycle risk.
115
- - 🚫 **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.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # E2E Testing Architectural Patterns
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:** 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
+
13
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).
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Test Pyramid & E2E Scope Boundary
41
+ ### Test Pyramid & E2E Scope Boundary
18
42
 
19
43
  ```mermaid
20
44
  flowchart TD
@@ -30,9 +54,10 @@ flowchart TD
30
54
 
31
55
  ---
32
56
 
33
- ## 2. Core Operational Patterns
57
+ ### Core Operational Patterns
34
58
 
35
59
  ### Pattern A: Clean Page Object Model (POM) with Typed Interfaces
60
+ <!-- classification: illustrative -->
36
61
  ```typescript
37
62
  // pages/base.page.ts
38
63
  import { Page, Locator, expect } from '@playwright/test';
@@ -51,6 +76,7 @@ export abstract class BasePage {
51
76
  }
52
77
  ```
53
78
 
79
+ <!-- classification: illustrative -->
54
80
  ```typescript
55
81
  // pages/checkout.page.ts
56
82
  import { Locator, expect } from '@playwright/test';
@@ -68,6 +94,7 @@ export class CheckoutPage extends BasePage {
68
94
  ```
69
95
 
70
96
  ### Pattern B: Isolated Storage State Fixture (Zero Login Repetition)
97
+ <!-- classification: illustrative -->
71
98
  ```typescript
72
99
  // fixtures/auth.fixture.ts
73
100
  import { test as base, Page } from '@playwright/test';
@@ -83,6 +110,7 @@ export const test = base.extend<{ authedPage: Page }>({
83
110
  ```
84
111
 
85
112
  ### Pattern C: Resilient Synchronization (No Static Delays)
113
+ <!-- classification: illustrative -->
86
114
  ```typescript
87
115
  // ANTI-PATTERN:
88
116
  // await page.waitForTimeout(5000); // Flaky and slow!
@@ -99,10 +127,27 @@ await expect(page.getByText('Order Created')).toBeVisible();
99
127
 
100
128
  ---
101
129
 
102
- ## 3. Parallel Sharding & CI/CD Governance
130
+ ### Parallel Sharding & CI/CD Governance
131
+ <!-- classification: illustrative -->
103
132
  ```bash
104
133
  # Run test suite sharded across 4 parallel CI workers
105
134
  npx playwright test --shard=1/4 --reporter=html,junit:results.xml
106
135
  ```
107
136
  - **Retries:** Maximum 1 retry on CI, 0 retries locally. Never rely on retries to mask structural flakiness.
108
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.
@@ -10,11 +10,35 @@ policies:
10
10
  ---
11
11
  # Katalon CLI & Enterprise Runner — Dual-Mode Execution Management
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:** 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
+
13
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.
14
38
 
15
39
  ---
16
40
 
17
- ## 1. Adaptive Dual-Mode Execution Strategy
41
+ ### Adaptive Dual-Mode Execution Strategy
18
42
 
19
43
  | Licensing State | Recommended Mode | Response Time | Licensing Cost |
20
44
  |---|---|:---:|:---:|
@@ -24,9 +48,10 @@ Specialized skill for managing, dispatching, and monitoring enterprise Katalon t
24
48
 
25
49
  ---
26
50
 
27
- ## 2. Pre-Flight Quality Check
51
+ ### Pre-Flight Quality Check
28
52
 
29
53
  Before launching heavy CLI runs, execute fast pre-flight verification:
54
+ <!-- classification: illustrative -->
30
55
  ```bash
31
56
  python3 -c "
32
57
  import glob
@@ -39,24 +64,27 @@ print('[PASS] Pre-flight passed: 100% UTF-8 No BOM')
39
64
 
40
65
  ---
41
66
 
42
- ## 3. License Recovery & Process Cleanup
67
+ ### License Recovery & Process Cleanup
43
68
 
44
69
  1. **License Expiration Handling:** When `License quota exceeded` occurs, halt batch retries immediately and switch to Playwright live validation or local GUI.
45
70
  2. **Zombie Chromedriver & Java Process Termination:**
46
- ```powershell
71
+ <!-- classification: illustrative -->
72
+ ```powershell
47
73
  # Windows process cleanup
48
74
  Get-Process -Name "chromedriver", "katalon" -ErrorAction SilentlyContinue | Stop-Process -Force
49
- ```
50
- ```bash
75
+ ```
76
+ <!-- classification: illustrative -->
77
+ ```bash
51
78
  # Unix process cleanup
52
79
  pkill -f chromedriver || true
53
80
  pkill -f katalon || true
54
- ```
81
+ ```
55
82
 
56
83
  ---
57
84
 
58
- ## 4. Standard Headless Execution Commands
85
+ ### Standard Headless Execution Commands
59
86
 
87
+ <!-- classification: illustrative -->
60
88
  ```bash
61
89
  # Execute specific Test Suite via KRE CLI in pure headless mode
62
90
  katalonc -noSplash -runMode=console \
@@ -70,12 +98,29 @@ katalonc -noSplash -runMode=console \
70
98
 
71
99
  ---
72
100
 
73
- ## 5. Definition of Done (DoD)
101
+ ### Definition of Done (DoD)
74
102
 
75
103
  1. **Exit Code = 0:** Runner completes cleanly without runtime crash.
76
104
  2. **Clean JUnit XML:** Results XML contains 0 `<failure>` or `<error>` tags.
77
105
  3. **Compile Allure Report:** `allure generate ./allure-results -o ./Reports/allure-report --clean`.
78
106
  4. If failures occur, immediately dispatch failure autopsy:
79
- ```bash
107
+ <!-- classification: illustrative -->
108
+ ```bash
80
109
  python tools/pinpoint_failure.py
81
- ```
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.