synapse-hub 0.0.0-stage → 2.0.0

package/.agents/skills/bats-testing-patterns/resources/implementation-playbook.md

@@ -0,0 +1,614 @@
+# Bats Testing Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+## Bats Fundamentals
+
+### What is Bats?
+
+Bats (Bash Automated Testing System) is a TAP (Test Anything Protocol) compliant testing framework for shell scripts that provides:
+- Simple, natural test syntax
+- TAP output format compatible with CI systems
+- Fixtures and setup/teardown support
+- Assertion helpers
+- Parallel test execution
+
+### Installation
+
+```bash
+# macOS with Homebrew
+brew install bats-core
+
+# Ubuntu/Debian
+git clone https://github.com/bats-core/bats-core.git
+cd bats-core
+./install.sh /usr/local
+
+# From npm (Node.js)
+npm install --global bats
+
+# Verify installation
+bats --version
+```
+
+### File Structure
+
+```
+project/
+├── bin/
+│   ├── script.sh
+│   └── helper.sh
+├── tests/
+│   ├── test_script.bats
+│   ├── test_helper.sh
+│   ├── fixtures/
+│   │   ├── input.txt
+│   │   └── expected_output.txt
+│   └── helpers/
+│       └── mocks.bash
+└── README.md
+```
+
+## Basic Test Structure
+
+### Simple Test File
+
+```bash
+#!/usr/bin/env bats
+
+# Load test helper if present
+load test_helper
+
+# Setup runs before each test
+setup() {
+    export TMPDIR=$(mktemp -d)
+}
+
+# Teardown runs after each test
+teardown() {
+    rm -rf "$TMPDIR"
+}
+
+# Test: simple assertion
+@test "Function returns 0 on success" {
+    run my_function "input"
+    [ "$status" -eq 0 ]
+}
+
+# Test: output verification
+@test "Function outputs correct result" {
+    run my_function "test"
+    [ "$output" = "expected output" ]
+}
+
+# Test: error handling
+@test "Function returns 1 on missing argument" {
+    run my_function
+    [ "$status" -eq 1 ]
+}
+```
+
+## Assertion Patterns
+
+### Exit Code Assertions
+
+```bash
+#!/usr/bin/env bats
+
+@test "Command succeeds" {
+    run true
+    [ "$status" -eq 0 ]
+}
+
+@test "Command fails as expected" {
+    run false
+    [ "$status" -ne 0 ]
+}
+
+@test "Command returns specific exit code" {
+    run my_function --invalid
+    [ "$status" -eq 127 ]
+}
+
+@test "Can capture command result" {
+    run echo "hello"
+    [ $status -eq 0 ]
+    [ "$output" = "hello" ]
+}
+```
+
+### Output Assertions
+
+```bash
+#!/usr/bin/env bats
+
+@test "Output matches string" {
+    result=$(echo "hello world")
+    [ "$result" = "hello world" ]
+}
+
+@test "Output contains substring" {
+    result=$(echo "hello world")
+    [[ "$result" == *"world"* ]]
+}
+
+@test "Output matches pattern" {
+    result=$(date +%Y)
+    [[ "$result" =~ ^[0-9]{4}$ ]]
+}
+
+@test "Multi-line output" {
+    run printf "line1\nline2\nline3"
+    [ "$output" = "line1
+line2
+line3" ]
+}
+
+@test "Lines variable contains output" {
+    run printf "line1\nline2\nline3"
+    [ "${lines[0]}" = "line1" ]
+    [ "${lines[1]}" = "line2" ]
+    [ "${lines[2]}" = "line3" ]
+}
+```
+
+### File Assertions
+
+```bash
+#!/usr/bin/env bats
+
+@test "File is created" {
+    [ ! -f "$TMPDIR/output.txt" ]
+    my_function > "$TMPDIR/output.txt"
+    [ -f "$TMPDIR/output.txt" ]
+}
+
+@test "File contents match expected" {
+    my_function > "$TMPDIR/output.txt"
+    [ "$(cat "$TMPDIR/output.txt")" = "expected content" ]
+}
+
+@test "File is readable" {
+    touch "$TMPDIR/test.txt"
+    [ -r "$TMPDIR/test.txt" ]
+}
+
+@test "File has correct permissions" {
+    touch "$TMPDIR/test.txt"
+    chmod 644 "$TMPDIR/test.txt"
+    [ "$(stat -f %OLp "$TMPDIR/test.txt")" = "644" ]
+}
+
+@test "File size is correct" {
+    echo -n "12345" > "$TMPDIR/test.txt"
+    [ "$(wc -c < "$TMPDIR/test.txt")" -eq 5 ]
+}
+```
+
+## Setup and Teardown Patterns
+
+### Basic Setup and Teardown
+
+```bash
+#!/usr/bin/env bats
+
+setup() {
+    # Create test directory
+    TEST_DIR=$(mktemp -d)
+    export TEST_DIR
+
+    # Source script under test
+    source "${BATS_TEST_DIRNAME}/../bin/script.sh"
+}
+
+teardown() {
+    # Clean up temporary directory
+    rm -rf "$TEST_DIR"
+}
+
+@test "Test using TEST_DIR" {
+    touch "$TEST_DIR/file.txt"
+    [ -f "$TEST_DIR/file.txt" ]
+}
+```
+
+### Setup with Resources
+
+```bash
+#!/usr/bin/env bats
+
+setup() {
+    # Create directory structure
+    mkdir -p "$TMPDIR/data/input"
+    mkdir -p "$TMPDIR/data/output"
+
+    # Create test fixtures
+    echo "line1" > "$TMPDIR/data/input/file1.txt"
+    echo "line2" > "$TMPDIR/data/input/file2.txt"
+
+    # Initialize environment
+    export DATA_DIR="$TMPDIR/data"
+    export INPUT_DIR="$DATA_DIR/input"
+    export OUTPUT_DIR="$DATA_DIR/output"
+}
+
+teardown() {
+    rm -rf "$TMPDIR/data"
+}
+
+@test "Processes input files" {
+    run my_process_script "$INPUT_DIR" "$OUTPUT_DIR"
+    [ "$status" -eq 0 ]
+    [ -f "$OUTPUT_DIR/file1.txt" ]
+}
+```
+
+### Global Setup/Teardown
+
+```bash
+#!/usr/bin/env bats
+
+# Load shared setup from test_helper.sh
+load test_helper
+
+# setup_file runs once before all tests
+setup_file() {
+    export SHARED_RESOURCE=$(mktemp -d)
+    echo "Expensive setup" > "$SHARED_RESOURCE/data.txt"
+}
+
+# teardown_file runs once after all tests
+teardown_file() {
+    rm -rf "$SHARED_RESOURCE"
+}
+
+@test "First test uses shared resource" {
+    [ -f "$SHARED_RESOURCE/data.txt" ]
+}
+
+@test "Second test uses shared resource" {
+    [ -d "$SHARED_RESOURCE" ]
+}
+```
+
+## Mocking and Stubbing Patterns
+
+### Function Mocking
+
+```bash
+#!/usr/bin/env bats
+
+# Mock external command
+my_external_tool() {
+    echo "mocked output"
+    return 0
+}
+
+@test "Function uses mocked tool" {
+    export -f my_external_tool
+    run my_function
+    [[ "$output" == *"mocked output"* ]]
+}
+```
+
+### Command Stubbing
+
+```bash
+#!/usr/bin/env bats
+
+setup() {
+    # Create stub directory
+    STUBS_DIR="$TMPDIR/stubs"
+    mkdir -p "$STUBS_DIR"
+
+    # Add to PATH
+    export PATH="$STUBS_DIR:$PATH"
+}
+
+create_stub() {
+    local cmd="$1"
+    local output="$2"
+    local code="${3:-0}"
+
+    cat > "$STUBS_DIR/$cmd" <<EOF
+#!/bin/bash
+echo "$output"
+exit $code
+EOF
+    chmod +x "$STUBS_DIR/$cmd"
+}
+
+@test "Function works with stubbed curl" {
+    create_stub curl "{ \"status\": \"ok\" }" 0
+    run my_api_function
+    [ "$status" -eq 0 ]
+}
+```
+
+### Variable Stubbing
+
+```bash
+#!/usr/bin/env bats
+
+@test "Function handles environment override" {
+    export MY_SETTING="override_value"
+    run my_function
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"override_value"* ]]
+}
+
+@test "Function uses default when var unset" {
+    unset MY_SETTING
+    run my_function
+    [ "$status" -eq 0 ]
+    [[ "$output" == *"default"* ]]
+}
+```
+
+## Fixture Management
+
+### Using Fixture Files
+
+```bash
+#!/usr/bin/env bats
+
+# Fixture directory: tests/fixtures/
+
+setup() {
+    FIXTURES_DIR="${BATS_TEST_DIRNAME}/fixtures"
+    WORK_DIR=$(mktemp -d)
+    export WORK_DIR
+}
+
+teardown() {
+    rm -rf "$WORK_DIR"
+}
+
+@test "Process fixture file" {
+    # Copy fixture to work directory
+    cp "$FIXTURES_DIR/input.txt" "$WORK_DIR/input.txt"
+
+    # Run function
+    run my_process_function "$WORK_DIR/input.txt"
+
+    # Compare output
+    diff "$WORK_DIR/output.txt" "$FIXTURES_DIR/expected_output.txt"
+}
+```
+
+### Dynamic Fixture Generation
+
+```bash
+#!/usr/bin/env bats
+
+generate_fixture() {
+    local lines="$1"
+    local file="$2"
+
+    for i in $(seq 1 "$lines"); do
+        echo "Line $i content" >> "$file"
+    done
+}
+
+@test "Handle large input file" {
+    generate_fixture 1000 "$TMPDIR/large.txt"
+    run my_function "$TMPDIR/large.txt"
+    [ "$status" -eq 0 ]
+    [ "$(wc -l < "$TMPDIR/large.txt")" -eq 1000 ]
+}
+```
+
+## Advanced Patterns
+
+### Testing Error Conditions
+
+```bash
+#!/usr/bin/env bats
+
+@test "Function fails with missing file" {
+    run my_function "/nonexistent/file.txt"
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"not found"* ]]
+}
+
+@test "Function fails with invalid input" {
+    run my_function ""
+    [ "$status" -ne 0 ]
+}
+
+@test "Function fails with permission denied" {
+    touch "$TMPDIR/readonly.txt"
+    chmod 000 "$TMPDIR/readonly.txt"
+    run my_function "$TMPDIR/readonly.txt"
+    [ "$status" -ne 0 ]
+    chmod 644 "$TMPDIR/readonly.txt"  # Cleanup
+}
+
+@test "Function provides helpful error message" {
+    run my_function --invalid-option
+    [ "$status" -ne 0 ]
+    [[ "$output" == *"Usage:"* ]]
+}
+```
+
+### Testing with Dependencies
+
+```bash
+#!/usr/bin/env bats
+
+setup() {
+    # Check for required tools
+    if ! command -v jq &>/dev/null; then
+        skip "jq is not installed"
+    fi
+
+    export SCRIPT="${BATS_TEST_DIRNAME}/../bin/script.sh"
+}
+
+@test "JSON parsing works" {
+    skip_if ! command -v jq &>/dev/null
+    run my_json_parser '{"key": "value"}'
+    [ "$status" -eq 0 ]
+}
+```
+
+### Testing Shell Compatibility
+
+```bash
+#!/usr/bin/env bats
+
+@test "Script works in bash" {
+    bash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
+}
+
+@test "Script works in sh (POSIX)" {
+    sh "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
+}
+
+@test "Script works in dash" {
+    if command -v dash &>/dev/null; then
+        dash "${BATS_TEST_DIRNAME}/../bin/script.sh" arg1
+    else
+        skip "dash not installed"
+    fi
+}
+```
+
+### Parallel Execution
+
+```bash
+#!/usr/bin/env bats
+
+@test "Multiple independent operations" {
+    run bash -c 'for i in {1..10}; do
+        my_operation "$i" &
+    done
+    wait'
+    [ "$status" -eq 0 ]
+}
+
+@test "Concurrent file operations" {
+    for i in {1..5}; do
+        my_function "$TMPDIR/file$i" &
+    done
+    wait
+    [ -f "$TMPDIR/file1" ]
+    [ -f "$TMPDIR/file5" ]
+}
+```
+
+## Test Helper Pattern
+
+### test_helper.sh
+
+```bash
+#!/usr/bin/env bash
+
+# Source script under test
+export SCRIPT_DIR="${BATS_TEST_DIRNAME%/*}/bin"
+
+# Common test utilities
+assert_file_exists() {
+    if [ ! -f "$1" ]; then
+        echo "Expected file to exist: $1"
+        return 1
+    fi
+}
+
+assert_file_equals() {
+    local file="$1"
+    local expected="$2"
+
+    if [ ! -f "$file" ]; then
+        echo "File does not exist: $file"
+        return 1
+    fi
+
+    local actual=$(cat "$file")
+    if [ "$actual" != "$expected" ]; then
+        echo "File contents do not match"
+        echo "Expected: $expected"
+        echo "Actual: $actual"
+        return 1
+    fi
+}
+
+# Create temporary test directory
+setup_test_dir() {
+    export TEST_DIR=$(mktemp -d)
+}
+
+cleanup_test_dir() {
+    rm -rf "$TEST_DIR"
+}
+```
+
+## Integration with CI/CD
+
+### GitHub Actions Workflow
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install Bats
+        run: |
+          npm install --global bats
+
+      - name: Run Tests
+        run: |
+          bats tests/*.bats
+
+      - name: Run Tests with Tap Reporter
+        run: |
+          bats tests/*.bats --tap | tee test_output.tap
+```
+
+### Makefile Integration
+
+```makefile
+.PHONY: test test-verbose test-tap
+
+test:
+	bats tests/*.bats
+
+test-verbose:
+	bats tests/*.bats --verbose
+
+test-tap:
+	bats tests/*.bats --tap
+
+test-parallel:
+	bats tests/*.bats --parallel 4
+
+coverage: test
+	# Optional: Generate coverage reports
+```
+
+## Best Practices
+
+1. **Test one thing per test** - Single responsibility principle
+2. **Use descriptive test names** - Clearly states what is being tested
+3. **Clean up after tests** - Always remove temporary files in teardown
+4. **Test both success and failure paths** - Don't just test happy path
+5. **Mock external dependencies** - Isolate unit under test
+6. **Use fixtures for complex data** - Makes tests more readable
+7. **Run tests in CI/CD** - Catch regressions early
+8. **Test across shell dialects** - Ensure portability
+9. **Keep tests fast** - Run in parallel when possible
+10. **Document complex test setup** - Explain unusual patterns
+
+## Resources
+
+- **Bats GitHub**: https://github.com/bats-core/bats-core
+- **Bats Documentation**: https://bats-core.readthedocs.io/
+- **TAP Protocol**: https://testanything.org/
+- **Test-Driven Development**: https://en.wikipedia.org/wiki/Test-driven_development

package/.agents/skills/clean-pom-crafter/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: clean-pom-crafter
+description: >-
+  Standardized Clean Page Object Model (POM) development and Flat Architecture enforcement across enterprise automation test suites.
+  Ensures 100% UTF-8 No BOM, zero hardcoded XPaths in scripts, dynamic test data generation via uniqueCode,
+  and standardized two-phase search, edit, calendar, multiselect, and deletion behaviors.
+---
+
+# Clean POM Crafter — Enterprise Clean POM Architecture Standards
+
+Specialized skill for creating, refactoring, and standardizing test automation scripts using **Clean Page Object Model (POM)** and **Flat Architecture** across enterprise test suites.
+
+---
+
+## 1. Core Architectural Principles
+
+1. **Flat Architecture:**
+   - All `Test Cases/`, `Scripts/`, and `Test Suites/` reside directly in their parent directory (no module subfolders).
+   - Naming convention: `TC-<Number>_<FeatureName>`, e.g. `TC-101_CreateUserAccount.groovy` or `tc-101-create-user.spec.ts`.
+2. **Unified Inheritance from `BasePage`:**
+   - All Page Classes in `Keywords/<project_namespace>/pages/` (or `pages/*.ts` in Playwright/TS) inherit from `BasePage`.
+3. **Zero Raw XPaths in Test Scripts:**
+   - Scripts (`Scripts/TC-xxx_*.groovy` or `tests/*.spec.ts`) only orchestrate business workflows. All locators and UI interactions are encapsulated in Page Classes.
+4. **Mandatory 100% UTF-8 No BOM:**
+   - All `.groovy`, `.java`, `.ts`, `.tc` files must NEVER contain UTF-8 BOM bytes (`0xEF, 0xBB, 0xBF`).
+5. **Context Window Protection (Zero-Token Economy):**
+   - 🚫 **NEVER read entire monolithic Page Class files (> 100KB) into LLM context.**
+   - Always use `python3 tools/lookup_xpath.py <keyword>` or line-range targeted reads (`read_file` with `StartLine`/`EndLine`) to find selectors and methods on demand.
+
+---
+
+## 2. Master Locator Priority Map (6 Tiers)
+
+All Page Classes **MUST** follow this strict locator hierarchy:
+1. **Tier 1 — Angular Semantic / ARIA:** `[formcontrolname="..."]`, `[aria-label="..."]`, `[role="..."]`.
+2. **Tier 2 — Dedicated Test Attributes:** `[data-testid="..."]`, `[data-test="..."]`.
+3. **Tier 3 — HTML Identifier:** `id`, `name`.
+4. **Tier 4 — PrimeNG Business Attributes:** `p-dropdown[formcontrolname="..."]`, `button[icon*="pencil"]`.
+5. **Tier 5 — Resilient CSS Selectors:** `.card.popup-data input.p-inputtext`.
+6. **Tier 6 — Relative XPath (Last Resort):** `//div[contains(@class, 'card')]//button[contains(., 'Confirm')]`.
+
+> 🚫 **FORBIDDEN:** Absolute positional XPaths (`//tbody/tr[1]/td[6]/button[2]`) and dynamic hash classes (`.p-element-1n2xyz`).
+
+---
+
+## 3. Test Data Management & Cross-Module Data Chain
+
+- **Supporting Field:** Generate dynamically using `BasePage.uniqueCode(prefix)` (e.g. `BasePage.uniqueCode("AUTO_")`).
+- **Dimension Field:** Fixed category values selected from dropdowns (`"Active"`, `"Standard"`).
+- **Reference Field:** Pass output records from prior TCs into subsequent TCs (Create -> Edit -> Delete).
+- **Computed Field:** Auto-calculated system metrics; assert 100% exact match.
+
+---
+
+## 4. Universal Page Object Architecture Model
+
+| No. | Page Class Role | Functional Module | Typical Test Scope | Core Methods & Responsibilities |
+|:---:|---|---|:---:|---|
+| 1 | `BasePage` | Core Engine, Driver, JS Helpers, Smart Wait | Global | `openUrl()`, `smartWait()`, `clickSafe()`, `uniqueCode()` |
+| 2 | `LoginPage` | Authentication & User Profile | Auth & Session | `login()`, `logout()`, `verifyUserProfile()` |
+| 3 | `UserAdminPage` | System Administration & Users | Admin / RBAC | `createUser()`, `assignRole()`, `filterUsers()` |
+| 4 | `CommonCategoryPage` | Common Categories & System Catalogs | Catalogs & Lookups | `addCategory()`, `editCategory()`, `verifyCatalog()` |
+| 5 | `WorkflowPlanningPage`| Sector Planning & Approvals | Workflows & Approvals | `createPlan()`, `submitForReview()`, `approvePlan()` |
+| 6 | `DataManagementPage` | Enterprise CRUD & Search Tables | Master Data | `searchRecord()`, `editRecord()`, `deleteRecord()` |
+| 7 | `ReportAnalyticsPage` | Statistical Reporting & Dashboards | Reporting | `generateReport()`, `exportExcel()`, `verifyKPI()` |
+| 8 | `ApiTokenMgmtPage` | Data Sharing & API Tokens | API & Integration | `generateToken()`, `revokeToken()`, `verifyScopes()` |
+
+---
+
+## 5. Implementation References & Examples
+
+- [**Standard Clean POM Methods (`pom_patterns.groovy`)**](references/pom_patterns.groovy): Full implementation of `searchRecord`, `editRecord`, `deleteRecord`, `setCalendarDate`, `selectMultiOptions`, `verifyRecordExists`, `verifyRecordNotExists`, `jsSetInput`.
+- [**Standard Test Script Template (`standard_test_case.groovy`)**](examples/standard_test_case.groovy): 7-step complete script template from Login -> Create -> Search -> Edit -> Delete.
+- [**Zero-Token XPath Lookup (`tools/lookup_xpath.py`)**](tools/lookup_xpath.py): Command `python3 tools/lookup_xpath.py <PageClass>` returns exact locators in <200 tokens without parsing full files.
+- [**Browser Runtime Helper (`tools/browser_helpers.js`)**](tools/browser_helpers.js): In-browser validation engine for form audits, safe clicks, and batch verification.

package/.agents/skills/clean-pom-crafter/examples/standard_test_case.groovy

@@ -0,0 +1,28 @@
+import com.enterprise.pages.BasePage
+import com.enterprise.pages.LoginPage
+import com.enterprise.pages.DataMiningPage
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+
+// Bước 1: Đảm bảo phiên đăng nhập hợp lệ
+LoginPage.ensureLoggedIn()
+
+// Bước 2: Điều hướng đến phân hệ mục tiêu
+DataMiningPage.navigateToCumCongNghiep()
+
+// Bước 3: Chuẩn bị dữ liệu kiểm thử duy nhất
+String testCode = BasePage.uniqueCode("CCN_")
+String testName = "CCN Thử Nghiệm " + testCode
+
+// Bước 4: Thực thi tạo mới
+DataMiningPage.createCluster(testCode, testName, "Hà Nội", "Đang hoạt động")
+
+// Bước 5: Tìm kiếm 2 pha và xác thực theo Mã
+DataMiningPage.searchRecord(testCode)
+DataMiningPage.verifyRecordExists(testCode)
+
+// Bước 6: Chỉnh sửa và xác thực cập nhật
+String updatedName = testName + " [ĐÃ CẬP NHẬT]"
+DataMiningPage.editRecord(testCode, updatedName)
+
+// Bước 7: Dọn dẹp dữ liệu (Xóa & Verify Không còn tồn tại)
+DataMiningPage.deleteRecord(testCode)