--- name: qa_skill description: "Skill and agent index for crest (API), celium (UI), pixify (VD), and appium (Mobile) — load qa_common as the universal entry point or use individual skills (api, ui, vd, app) directly for single-layer tasks." version: 1.6.13 license: MIT testingTypes: [API, E2E, Mobile, Integration, Performance] frameworks: [RestAssured, Selenium, Playwright, Appium, Cucumber, TestNG, Gatling] languages: [Java] agents: [claude-code, cursor, copilot, windsurf] repos: - unified-qa-framework # shared core library - crest # API / backend automation - celium # Web UI automation - pixify # Visual Diff (VD) automation - appium # Mobile app automation entry-point: qa/common/skill/SKILL.md full-reference: qa/qa.md --- # Headout Unified QA Framework — Skill Index This file is the canonical skill index for AI agents. - **Start every QA task from**: `qa/common/skill/SKILL.md` (auto-routes to the right layer) - **Full reference** (agents + skills + prompts + patterns): `qa/qa.md` --- ## WHEN INVOKED — Display This Greeting When this skill is loaded (e.g. via `/qa`), output the following greeting exactly, then wait for user input: --- ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ QA SKILL · Ready to generate tests ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1 cURL → crest (API) 2 HTML / Live URL → celium (UI) + pixify (VD if applicable) 3 Appium XML → appium (Mobile) 4 Pod + VD request → pixify (Visual Diff) 5 PR / PRD / EDD → auto-detects all layers 6 Description → I'll confirm repo, then generate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Paste input · mode is auto-detected Type "help" for examples & templates ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` --- ## Repository Map | Repo | Testing Layer | Primary Tool | Config / Data | UQF Version | |------------------------|--------------|-------------|---------------|-------------| | `unified-qa-framework` | Core shared library | All layers | — | `1.6.13` | | `crest` | API / Backend | RestAssured + Cucumber | `src/test/resources/ResponseSchema/` + `configuration.properties` | `1.2` | | `celium` | Web UI (desktop + mobile web) | Selenium 4 / Playwright + Cucumber | `src/test/resources/configuration.properties` | `1.1-alpha` | | `pixify` *(VD layer)* | Visual Diff (pixel regression) | pixify engine (`com.headout.common.visual.*` in UQF) | `src/test/resources/vd/{podName}/` — 3 JSON files per pod (see below) | `1.1-alpha` | | `appium` | Native mobile (Android + iOS) | Appium 9 + Cucumber | `src/test/resources/configuration.properties` + `appium-config.json` | `1.6-beta-3` | ### Visual Diff (VD) — Pod Config Files All VD config lives in `src/test/resources/vd/{podName}/` (one folder per pod): | JSON File | Purpose | Key Format | |-----------|---------|-----------| | `visual-diff-action.json` | Maps snapshot names → pre-capture actions | `{snapshotName}.ACTION.{ACTION_KEY}` | | `visual-diff-version-1.json` | Maps snapshot path → S3 baseline URL | `{BROWSER}.{SERVICE_TYPE}.{SNAPSHOT_NAME}.{MODE_TYPE}.{LANGUAGE}` | | `upload-snapshot-{browser}-on-s3.json` | Defines pages/elements to capture and push to S3 | `snapshotName`, `url`, `captureElement`, `action[]` | **S3 baseline URL pattern:** ``` https://headout-testing.s3.{region}.amazonaws.com/ui-automation/{version}/{serviceType_lower}/{modeType_lower}/{browser_lower}/{env}/{snapshotName}_{lang_lower}.png ``` **VD engine classes** (all in `unified-qa-framework`): | Class | Package | Role | |-------|---------|------| | `ScreenshotComparison` | `com.headout.common.visual.core` | Takes screenshots (ThreadLocal singleton) | | `CaptureElement` | `com.headout.common.visual.core` | Enum: `FULL_PAGE` / `VIEWPORT` / `ELEMENT` | | `NewImageComparison` | `com.headout.common.visual` | Pixel diff engine (2 % tolerance default) | | `UploadSnapshotToS3` | `com.headout.common.visual.action` | Uploads new baselines to S3 | | `VisualDiffReader` | `com.headout.utility.visualdiff` | Reads `visual-diff-action.json` | | `VisualDiffReaderVersion` | `com.headout.utility.visualdiff` | Reads `visual-diff-version-1.json` | **Supported action types** (usable in both `visual-diff-action.json` and inline `action[]`): | Type key | Effect | |----------|--------| | `STOP_ALL_PLAY` | Pause all auto-playing media | | `SCROLL_DOWN_PAGE` | Scroll to bottom of page | | `DOM_DELETE` | Remove XPath-targeted elements from DOM | | `CLICK` | Click XPath-targeted element | | `WAIT` | Hard wait (seconds) | | `WAIT_UNIT_ELEMENT_DISPLAY` | Wait for element visibility | | `SEND_KEYS` | Type text into element | | `CUSTOM_SCRIPT` | Execute inline JS strings | --- ## Entry Point — Common Skill > **Always load this first.** It auto-detects the input type, assigns layer(s), and > routes to the correct individual skill(s) automatically. **File**: `qa/common/skill/SKILL.md` ### How the Common Skill Routes ``` Your input │ ├─ curl -X / HTTP verb + URL + -d → API (crest) │ loads: qa/api/skill/SKILL.md │ + document_driven_test_generation.skill.md │ ├─ //` 6. **Step definitions** → `src/test/java/com/headout/stepdefinitions/` 7. **Search before creating** — grep stepdefs + POs before writing new ones 8. **Data setup** → `DataSetup` classes and `@After` hooks, not step defs 9. **No `Thread.sleep()`** → `wait.waitForVisibilityOfElement()` or VD `WAIT` action 10. **No `By.*`** in celium/appium → `ByBuilder` instance fields in Page Objects only 11. **`softAssertionUtil.get().assertAll()`** at end of every `@Then` in API + App tests 12. **URLBuilders** → `endpointMap.put("key-v2", baseUrl + "/path")` — no static constants --- ## Quick-Start Per Layer ### API (crest) ```bash git clone git@github.com:headout/crest.git && cd crest mvn --global-settings settings.xml clean install -DskipTests=true mvn test -Dcucumber.filter.tags="@test" -DthreadCount=5 ``` ### Web UI (celium) ```bash git clone git@github.com:headout/celium.git && cd celium mvn --global-settings settings.xml clean install mvn test -Dcucumber.filter.tags="@test" -DBROWSER=chrome ``` ### Mobile App (appium) ```bash git clone git@github.com:headout/appium.git && cd appium mvn --global-settings settings.xml clean install ./android-script/setup_android_emulators.sh && ./android-script/create_avds.sh mvn test -Dcucumber.filter.tags="@test" -DDEVICE_TYPE=android ``` --- ## Requirements ### System Tools | Tool | Version | Notes | |------|---------|-------| | Java (JDK) | 21 | `brew install openjdk@21` on macOS | | Maven | 3.9.x | `brew install maven` | | Node.js | 16 | Required by some CI workflows | | Android SDK + ADB | latest | appium only | | Xcode / iOS toolchain | latest | appium iOS only | | WireGuard | latest | crest test/live environments | | Python | 3.9+ | Utility scripts | ### Python Dependencies ``` selenium==4.22.0 gherkin-official==28.0.0 requests==2.32.3 gitpython ``` Install: `pip install -r requirements.txt` ### Maven Authentication (`settings.xml`) ```xml github YOUR_GITHUB_USERNAME YOUR_GITHUB_PAT ``` --- ## Script Reference ### `scripts/` (all repos) | Script | Purpose | |--------|---------| | `automation_tracker.py` | Count `@pending`/`@manual`/`@revamp` scenarios; post to Slack/QA portal | | `count_scenarios_by_tags.py` | Count BDD scenarios by tag; supports Scenario Outlines | | `jacoco/collect-jacoco-coverage.sh` | Collect JaCoCo `.exec` files from services | | `jacoco/process-jacoco-coverage.sh` | Generate HTML/XML coverage reports | ```bash python scripts/automation_tracker.py --repo crest --env test python scripts/count_scenarios_by_tags.py --target-tags test live ode-regression ``` ### `android-script/` (appium only) | Script | Purpose | |--------|---------| | `setup_android_emulators.sh` | Bootstrap Android SDK + emulators | | `create_avds.sh` | Create named AVD instances | | `start-emulator.sh` / `stop-emulator.sh` | Start / stop emulator | | `delete-emulator.sh` | Remove AVD from registry | | `get-result.py` | Fetch and format CI run results | ```bash # Reset UiAutomator between runs adb uninstall io.appium.uiautomator2.server adb uninstall io.appium.uiautomator2.server.test ``` --- ## CI/CD Workflow Reference ### unified-qa-framework | Workflow | Trigger | Action | |----------|---------|--------| | `maven-auto-release.yml` | Push to `main` | Auto-version bump + publish JAR | | `publish-release.yml` | Manual | Manual Maven registry publish | ### crest | Workflow | Trigger | Action | |----------|---------|--------| | `get-automation-report.yml` | `workflow_dispatch` | Run API suite; post Slack report | | `get-automation-count-details.yml` | Schedule / PR | Upload scenario counts | | `vpn-setup.yml` | Called by others | WireGuard VPN for test/live | ### celium | Workflow | Trigger | Action | |----------|---------|--------| | `get-automation-report.yml` | `workflow_dispatch` | Run UI suite; post Slack report | | `visual-diff-ode.yml` | PR / manual | Visual regression vs ODE envs | | `pr_review.yml` | PR | Automated PR checks | | `stale-branch.yml` | Schedule | Clean stale branches | ### appium | Workflow | Trigger | Action | |----------|---------|--------| | `automation-suite.yml` | `workflow_dispatch` | Full mobile test suite | | `common-automation-suite.yml` | `workflow_dispatch` | Common Android + iOS suite | | `get-e2e-automation-suite.yml` | `workflow_dispatch` | End-to-end journey suite | | `pr-automation-trigger.yml` | PR | Smoke tests on PRs | | `build-check.yml` | PR / push | Maven compile validation | | `lint-check.yml` | PR / push | Code style checks | | `performance-check.yml` | Schedule / manual | Gatling load tests | | `feature-file-upload.yml` | Push to main | Upload feature files to QA portal | --- ## New Test Authoring Checklist - [ ] Used `qa/common/skill/SKILL.md` as the entry point (or the correct individual skill) - [ ] `qa/common/agent/_PRAETORIAN_CONSTITUTION.md` referenced in the prompt - [ ] Existing stepdefs and POs scanned with `grep -rn` before writing anything - [ ] Test Case Matrix produced before any code - [ ] Feature file under `src/test/java/com/headout/features///` - [ ] All scenarios tagged with `@test`/`@live` plus functional tags - [ ] `Scenario Outline` + `Examples` used for 2+ data-driven rows - [ ] Correct base class per layer (see Universal Rules above) - [ ] No hardcoded credentials — uses `PropertyUtils.get(ConfigMap.*)` - [ ] `softAssertionUtil.get().assertAll()` at end of every `@Then` (API + App) - [ ] All locators are `ByBuilder` instance fields in Page Objects - [ ] `wait.waitForVisibilityOfElement()` before every UI interaction (no Thread.sleep) - [ ] `@manual` scenarios include `# STEP N:` and `# EXPECTED:` lines - [ ] `@pending` scenarios include a comment with the blocking reason - [ ] CI workflow tag options updated if new tags introduced