create-pats

Bootstrap package for Playwright API testing workflows.

This initializer copies two folders into your target repo:

• .github (skill definitions)
• scripts (automation utilities)

The copied skills are designed for a structured API QE lifecycle that keeps tests traceable from planning to execution and healing.

Required companion toolkit

Use this package together with:

npm install @msalaam/xray-qe-toolkit@latest

Quick start

Initialize a repository with the skills and scripts:

npm init pats

Alternative:

npx create-pats

If installed as a dependency, this shorthand is available:

npx pats

What this package is about

It provides a complete, skill-driven workflow for API test engineering:

1. Plan tests from OpenAPI and optional business rules.
2. Add new test cases safely through tests.json.
3. Sync definitions and mappings with Xray.
4. Generate Playwright suite artifacts from tests.json.
5. Heal failures after execution with targeted remediation.

Included skills and how to use them

Skill reference map

• test-adder > references > .github/skills/test-adder/references/generate-tests.mjs
• test-adder > references > .github/skills/test-adder/references/generate-playwright-tests.mjs
• test-adder > references > .github/skills/test-adder/references/import-results-om-xray.js
• test-planner > references > .github/skills/test-planner/references/generate-tests.mjs
• test-generator > references > .github/skills/test-generator/references/generate-playwright-tests.mjs
• test-xray-sync > references > .github/skills/test-xray-sync/references/import-results-om-xray.js
• test-healer > references > .github/skills/test-healer/references/run-healer.mjs

1) test-planner

Purpose:

• Generates or updates tests.json from OpenAPI and optional business-rules.yaml.
• Produces dual-track coverage: contract tests and business-rule tests.

Use when:

• You need initial planning.
• You need to regenerate authoritative tests.json coverage.

Expected outcome:

• A deterministic tests.json ready for generation and Xray mapping.

2) test-adder

Purpose:

• Adds new coverage requests (single scenario, table, or acceptance criteria) by updating tests.json through the approved flow.
• Orchestrates planner -> xray sync -> generator.

Use when:

• You need to add new tests without manually editing spec files.

Expected outcome:

• New tests are added with preserved traceability and generated into the suite.

3) test-xray-sync

Purpose:

• Validates tests.json.
• Pushes test definitions to Xray.
• Refreshes xray-mapping.json.
• Imports execution results via OM integration.

Use when:

• tests.json changed and you need fresh Xray mapping.
• You need to import execution outcomes to Xray.

Typical commands:

npx xqt validate
npx xqt push-tests
npm run xray:import:om

4) test-generator

Purpose:

• Generates Playwright API suite files from tests.json and mapping.
• Produces models, services, fixtures, and specs with one-to-one traceability.

Use when:

• You need to materialize planned tests into executable Playwright specs.

Expected outcome:

• Consistent outputs under tests/models, tests/services, tests/fixtures, and tests/specs.

5) test-healer

Purpose:

• Diagnoses and repairs post-execution failures.
• Handles contract mismatches, data/config/auth defects, flaky tests, and traceability gaps.

Use when:

• Playwright or pipeline runs fail and you need minimal, root-cause fixes.

Expected outcome:

• Stabilized test suite with validated fixes and preserved contract intent.

Recommended workflow

1. Run planner to produce or refresh tests.json.
2. Run Xray sync to validate and push mappings.
3. Run generator to produce Playwright tests.
4. Execute tests.
5. Run healer if failures occur, then re-sync and re-run.

Notes

• Existing files are not overwritten by the initializer; conflicts are skipped.
• tests.json is the source of truth for planned coverage and traceability.