0xHanniba1/python-qa-automation

Python QA Automation

Outcome Contract

• Treat this skill as the QA inner loop after the business expectation is clear.
• Complete one immediate deliverable per invocation. Do not move automatically from design to implementation, integration, or failure repair.
• Keep API and UI as separate modes. In UI mode, use API calls only for setup, cleanup, or post-condition checks tied to the UI scenario.
• Pass Clarified, Ready, and Verified gates with evidence; invoking the skill is not evidence of completion.

Preflight

1. Read references/common-rules.md.
2. Resolve <skill-dir> to the directory containing this SKILL.md; run bundled scripts from that directory, not from the target project.
3. Identify the target project root and read its instructions, manifests, relevant tests, and git status before editing.
4. Identify the source material, expected result, environment boundary, data ownership, and verification method; require a command for code-producing routes.
5. If an expected result cannot be found or confirmed, stop at test design and mark the scenario exploratory/manual instead of inventing an assertion.

Select One Route

Choose exactly one delivery route from the user's immediate requested outcome. Treat source material and API/UI mode as inputs to the route, not additional routes.

Route	Use when the immediate deliverable is	Required reference	Done when
test-design	A coverage matrix or automation recommendation, without code	references/test-design.md	Expected results, layer, priority, data, and automation decision are explicit
new-project	A runnable minimal pytest scaffold in an empty/new target	Selected mode guide	Scaffold validates and one meaningful smoke test collects or runs
existing-project	The smallest compatible test change in an existing repository	references/existing-project.md plus selected mode guide	Project conventions are preserved and affected verification passes
delivery-integration	CI, Jenkins, reports, release gates, or performance smoke	references/delivery-integrations.md	Requested integration is added and locally checkable parts are verified
failure-analysis	Evidence-based classification or repair of a failed test	references/failure-analysis.md	Root cause is supported, or the next missing probe is named

Do not combine routes merely because one task contains a requirement, an existing repo, and a UI flow. For example, adding checkout coverage to an existing Playwright project is existing-project in ui mode; load test-design.md as supporting guidance when test points are not already approved.

Select A Mode When Needed

• For test-design, let the matrix select the lowest reliable layer; do not force API or UI before that decision.
• Select api for endpoint behavior, contracts, auth, validation, state, and integrations. Read references/api-mode.md.
• Select ui for browser behavior, client validation, layout-dependent interaction, and critical user journeys. Read references/ui-mode.md.
• Do not require a mode for delivery-only work or failure analysis when the existing project and evidence already determine the stack.
• If the requested deliverable would create parallel API and UI suites, ask the user to choose one. UI setup/cleanup API calls do not count as a parallel API suite.

Load Conditional References

• Read references/test-design.md for requirements, user stories, bug tickets, release scope, screenshots, or any change whose test points are not approved.
• Read references/test-data.md for login, create/update/delete, uploads, seed data, setup/cleanup, or server-side state checks.
• Read references/flaky-diagnosis.md for intermittent failures, timing, waits, retries, polling, dynamic UI, or parallel interference.
• Read references/api-contracts.md for schemas, contracts, compatibility, permissions, roles, tenants, ownership, or error-code coverage.
• Read references/advanced-ui.md for Appium/mobile, visual regression, multi-tab/window, downloads, uploads, dialogs, iframes, or complex browser state.

Gates And Project Assets

Pass these gates in order:

• Clarified: source, owner or authority, expected result, scope, and non-scope are explicit.
• Ready: route, mode when needed, target files for code-producing work, data/cleanup boundary, environment safety, and verification method are explicit.
• Verified: code-producing routes ran the target command and relevant regression; design-only routes trace every expected result to an approved source. State every unverified part and reason.

If the target project has TEST_PLAN.md or its instructions require one, read it before selecting coverage, set the active scenario to In Progress before implementation, and mark it Automated only after verification. Do not introduce TEST_PLAN.md into projects that do not use it unless the user or project rules require it.

Execute The Selected Route

1. For existing-project, inspect the repository and read the reported files before editing.
2. State the selected route, mode, immediate deliverable, target files, and explicit non-scope.
3. Produce or confirm test points before code when the expected behavior is not already approved.
4. Make the smallest change that completes the selected route; preserve existing project structure and avoid adjacent backlog work.
5. Run the narrow target verification first, then the relevant regression command.
6. Update project test-plan status only after the matching gate is passed.
7. Stop at the selected route's done condition and return the handoff. Do not invoke another skill or route automatically.

For test-design, do not edit automation code. For failure-analysis, do not edit when the requested outcome is diagnosis only; repair only when the user requested a fix and evidence supports the root cause.

Bundled Tools

Replace <skill-dir> with this skill's absolute directory.

Inspect an existing project:

python "<skill-dir>/scripts/inspect_project.py" "<project-dir>"

Scaffold only into a new or empty target:

python "<skill-dir>/scripts/scaffold.py" --mode api --out "<output-dir>" --project-name "<name>"
python "<skill-dir>/scripts/scaffold.py" --mode ui --out "<output-dir>" --project-name "<name>"

The scaffold refuses to overwrite existing files. Do not pass --force unless the user explicitly asks to replace generated files.

Validate generated or edited Python/TOML:

python "<skill-dir>/scripts/validate_generated.py" "<project-dir>"
python "<skill-dir>/scripts/validate_generated.py" "<project-dir>" --collect

Use the target project's own test command as the primary verification for existing projects. Treat validator status partial as unverified; install dependencies in the target project's environment before claiming collection passed. For UI execution, ensure the required Playwright browser is installed.

Handoff

Report:

• selected route and mode;
• requirement source and expected result used as the oracle;
• files changed, plus TEST_PLAN.md status when applicable;
• verification commands and exact pass, fail, partial, or skipped result;
• unverified work, remaining risk, and the next decision if another route is needed.

Non-Scope

• Do not build hybrid API+UI frameworks by default.
• In UI mode, do not add broad API endpoint coverage; API calls are only for setup, cleanup, or post-condition checks tied to the UI scenario.
• Do not add CI, Jenkins, Allure, Appium, desktop automation, visual regression, or performance testing by default; add them only when explicitly requested and scoped.
• Do not create .env, store credentials, call production systems, or invent real tokens.
• Do not add an LLM API dependency inside the generated test project. The host agent performs reasoning and repair.