testeiya 0.2.0

package/skills/testomatio/test-automation/debug-fix-failed-flaky-autotests/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: debug-fix-failed-flaky-autotests
+description: Diagnose and fix failing automated tests. Analyzes failures, inspects DOM, identifies root causes, and applies targeted fixes using framework tools and MCP/CLI debug modes. Use when tests fail, are flaky, or behave inconsistently (e.g., pass locally but fail in CI).
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+# Debug and Fix Failing Autotests
+
+Diagnose failing automated tests and apply targeted fixes.
+Follow the four steps in order.
+Detailed fixes and code examples: [references/DEBUGGING_QUICK_REFERENCE.md](references/DEBUGGING_QUICK_REFERENCE.md).
+
+## Step 1: Analyze Failure
+
+- Identify the framework. It determines the debug tools:
+  - Playwright: CLI debug, trace viewer, MCP snapshots.
+  - CodeceptJS: `--steps` mode, CDP inspection.
+  - Cypress: devTools, screenshots on failure.
+  - WebdriverIO: Selenium logs.
+- Categorize the error:
+  - Locator (element missing/unreachable).
+  - Timing (timeout/race).
+  - Assertion (expected ≠ actual).
+  - Flow (navigation, preconditions).
+  - Infrastructure (CI/browser/network).
+- End with a hypothesis: root cause + fix category.
+
+## Step 2: Inspect and Diagnose
+
+- DOM inspection:
+  - Playwright: `page.locator('selector').evaluate(el => el.outerHTML)`.
+  - CodeceptJS: `I.executeScript(() => document.querySelector('.selector').outerHTML)`.
+  - MCP snapshot: capture live DOM state for complex elements.
+- Console and network logs:
+  - Console: `page.on('console', msg => console.log(msg.text()))`.
+  - Failed requests: `page.on('requestfailed', r => console.log(r.failure().errorText))`.
+- Trace analysis (Playwright): `npx playwright show-trace trace.zip`.
+  - Inspect timing and order of clicks, navigation, network requests.
+
+## Step 3: Apply Fix
+
+**Fix in priority order: locators → timing → assertions → flow.**
+
+- Locators: use stable selectors (`data-testid` → `aria-label` → `role` → `id` → `text` → CSS/XPath).
+  - Re-fetch stale elements, scroll hidden elements into view, use `.first()` for multiple matches.
+- Timing: use framework-native waits (`waitFor`, `waitForNavigation`, `waitForLoadState('networkidle')`).
+  - **No hard sleeps** like `sleep(5000)` or `wait(2)`.
+- Assertions: use contains/regex for flexible matching.
+  - Verify expected values against the test spec, not assumptions.
+- Flow: ensure preconditions (login, navigation order, test data).
+  - Isolate test state from prior runs.
+
+Before/after examples for each category: [references/DEBUGGING_QUICK_REFERENCE.md](references/DEBUGGING_QUICK_REFERENCE.md).
+
+## Step 4: Verify and Stabilize
+
+Re-run the test:
+
+```bash
+npx playwright test path/to/test.spec.ts
+npx codeceptjs run path/to/test.js
+```
+
+Test is stable when:
+- Passes 2 consecutive runs.
+- Uses resilient locators.
+- Waits properly for dynamic content.
+
+**Max 3 healing attempts total.** After 3 failed attempts: stop, document what was tried, ask the user for guidance.
+
+Document the fix: root cause, applied fix, verification result.
+
+## MCP Debug Tools (Optional)
+
+Use MCP when standard fixes fail, the UI is complex (dropdowns, modals, dynamic content), or live DOM inspection is needed:
+- Playwright MCP: live snapshots, element counts, DOM inspection after each action.
+- CodeceptJS MCP: CDP-based inspection, `--steps` mode for live debugging.
+
+## User Interaction
+
+Ask when unclear:
+
+```
+❓ Which element should I target for this action?
+
+Options:
+1. Submit button (data-testid="submit")
+2. Save button (aria-label="Save")
+3. Other (specify)
+```
+
+Report progress:
+
+```
+🔍 Analyzing failure...
+  - Error: Element not found
+  - Context: Login test, line 42
+
+🔧 Applying fix...
+  - Issue: Selector too broad
+  - Fix: Using getByRole('button', { name: 'Login' })
+
+✅ Test passed! (Run 1/2)
+```

package/skills/testomatio/test-automation/debug-fix-failed-flaky-autotests/references/DEBUGGING_QUICK_REFERENCE.md

@@ -0,0 +1,113 @@
+# Debugging Quick Reference
+
+Fix in priority order: locators → timing → assertions → flow.
+
+---
+
+## Locator Fixes
+
+| Problem | Avoid | Prefer |
+|---------|-------|--------|
+| Deep nesting | `.parent .child .grandchild` | `[data-testid="target"]` |
+| Index-based | `button:nth-child(2)` | `getByRole('button', { name: 'Submit' })` |
+| Partial text | `button:contains("Save")` | `getByText('Save', { exact: true })` |
+| Dynamic classes | `.btn-primary-123` | `[data-testid="save-btn"]` |
+
+Element state issues:
+
+- Not found => wait for element before action.
+- Not visible => scroll into view.
+- Not clickable => wait for enabled state; check overlays.
+- Stale element => re-fetch element before action.
+- Multiple matches => filter or use `.first()`.
+
+---
+
+## Timing Fixes
+
+Use framework-native waits instead of hard sleeps.
+
+- Avoid hard sleeps (`sleep(5000)`, `wait(2)`) => flaky.
+- Avoid implicit short waits => unreliable.
+- Works locally, fails in CI => CI is slower; increase timeouts and add explicit waits.
+
+**Playwright:**
+```typescript
+await page.getByTestId('loader').waitFor({ state: 'hidden' });
+await page.waitForURL('/dashboard/**');
+await page.waitForResponse(r => r.status() === 200);
+```
+
+**CodeceptJS:**
+```javascript
+I.waitForNavigationVisible();
+I.waitForResponse(response => response.status() === 200);
+```
+
+### Fix Race Conditions
+
+Ensure assertions happen after dynamic content updates.
+Use `expect` with Playwright's built-in waiting, or `locator.waitFor()` only if needed.
+
+```typescript
+// Click triggers dynamic update
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Wait for result text to appear (optional, only if dynamically loaded)
+await expect(page.getByTestId('result')).toHaveText('Success'); // automatically waits
+```
+
+---
+
+## Assertion Fixes
+
+- Exact match too strict => use `toContain()` or regex.
+- Wrong expected value => verify against test spec.
+- Timing issues => wait before assertion.
+- Multiple elements => use `.first()` or `.nth(0)`.
+
+Examples:
+
+```typescript
+// Before: exact match fails on whitespace
+expect(await page.locator('.title').textContent()).toBe('Hello World');
+
+// After: contains check
+await expect(page.locator('.title')).toContainText('Hello');
+
+// Better: trim if exact needed
+const text = (await page.locator('.title').textContent()).trim();
+expect(text).toBe('Hello World');
+```
+
+---
+
+## Flow Fixes
+
+- Missing preconditions => ensure login, proper navigation, and required test data.
+- Fails on 2nd run => add cleanup hooks.
+- Depends on order => use `beforeEach` for fresh state.
+- Shared state => isolate per test worker.
+
+---
+
+## Framework-Specific Commands
+
+**Playwright:**
+- Show trace: `npx playwright show-trace trace.zip`
+- Run single file: `npx playwright test path/to/test.spec.ts`
+
+**CodeceptJS:**
+- Steps mode: `npx codeceptjs run --steps`
+- Verbose: `npx codeceptjs run --verbose`
+- Single file: `npx codeceptjs run path/to/test.js`
+
+---
+
+## Max 3 Healing Attempts
+
+1. Attempt 1: apply fix based on initial diagnosis.
+2. Attempt 2: if still fails, re-diagnose with new info.
+3. Attempt 3: last try with an alternative approach.
+
+If still failing => STOP, document what was tried, ask the user for guidance.

package/skills/testomatio/test-automation/qa-automation-test-consolidation/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: qa-automation-test-consolidation
+description: Detect redundant tests, duplicated test logic, semantic overlaps, and parameterization opportunities across the entire test suite. Present recommendations and request user approval before refactoring.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.0.0
+---
+
+## Summary
+
+This skill analyzes an entire test suite to identify duplicate tests, semantic overlaps, duplicated test logic, parameterization opportunities, and overlapping business-rule validations. It prioritizes behavioral similarity over code similarity and recommends refactorings that reduce maintenance effort while preserving test coverage and business intent. No changes are applied without explicit user approval.
+
+## How the Loop Works
+
+- Analyze the entire test suite for consolidation opportunities;
+- Group findings by type and confidence level;
+- Present a summary of the proposed changes and request user approval;
+- Apply the approved refactorings;
+- Re-analyze the updated test suite to identify newly exposed consolidation opportunities;
+- Repeat until no additional consolidation opportunities with a confidence level greater than 80% remain.
+
+## Definition of Done
+
+- The entire test suite has been analyzed;
+- All consolidation opportunities have been presented to the user;
+- All approved refactorings have been applied;
+- The test suite has been re-analyzed after each iteration;
+- No duplicate tests, duplicated test logic, parameterization opportunities, or business-rule overlaps with a confidence level greater than 80% remain.

package/skills/testomatio/test-automation/run-tests-with-testomatio-reporter/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: run-tests-with-testomatio-reporter
+description: Create and launch Testomat.io test runs with the `@testomatio/reporter` CLI. Covers manual runs for testers, mixed manual+automated runs, local test execution with reported results, and remote launches through a Testomat.io CI profile (`--remote`). Runs can include the whole suite or be filtered by tag, plan, label, Jira ticket, or changed source files. Use when the user asks to start or create a test run from the command line, run a filtered group of tests, launch tests remotely, or report results into an existing run.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.1.0
+---
+
+# Run Tests with Testomat.io Reporter
+
+`npx @testomatio/reporter` creates test runs in Testomat.io and launches groups of tests — locally or remotely through a Testomat.io CI profile. Every command requires the `TESTOMATIO` env var (the project API key, `tstmt_*`) and exits 1 without it. Every value in angle brackets is a placeholder.
+
+## Pick the command by intent
+
+| Intent                                              | Command                                     |
+| --------------------------------------------------- | ------------------------------------------- |
+| Create a run, execute nothing — testers start on it | `start`                                     |
+| Execute tests locally and report results            | `run "<runner command>"`                    |
+| Launch tests remotely via a Testomat.io CI profile  | `run --remote <profile-name>`               |
+| List which tests a filter matches, run nothing      | `run --filter-list "<filter>" --format ids` |
+| Close a run created earlier                         | `finish` (run id via `TESTOMATIO_RUN`)      |
+
+## Run kinds
+
+`--kind` declares what the run contains:
+
+| Kind      | Flag            | Behavior                                                                                        |
+| --------- | --------------- | ----------------------------------------------------------------------------------------------- |
+| manual    | `--kind manual` | manual cases only — pending for testers, complete without any launch                            |
+| mixed     | `--kind mixed`  | manual + automated in one run — testers work it while the automated part is launched separately |
+| automated | *(no flag)*     | automated tests only                                                                            |
+
+A run created with `start` executes nothing: manual cases are pending immediately; an automated part stays scheduled until launched. `--format id` prints only the run id to stdout (banner and logs go to stderr), so capture is clean:
+
+```bash
+RUN_ID=$(npx @testomatio/reporter start --kind manual --format id)
+```
+
+## What goes into the run
+
+Without a filter, nothing is scoped:
+
+- `start` creates a run with no predefined test list — results land in it later, when tests report with `TESTOMATIO_RUN=<run-id>`.
+- `run "<runner command>"` executes the full suite and reports every result.
+- `run --remote <profile-name>` dispatches the Testomat.io CI profile with its default scope.
+
+`--filter "<pipe>:<criteria>"` narrows the run to the matching tests instead. Two filter pipes exist — `testomatio:` (match by test metadata stored in the project) and `coverage:` (match by changed source files); any other prefix is rejected. `start` and `run` accept the same filters, so a filtered run can be prepared first and launched later.
+
+### Filter by tag, plan, label, or Jira ticket (`testomatio:`)
+
+| Criteria                   | Filter                                       |
+| -------------------------- | -------------------------------------------- |
+| tag                        | `"testomatio:tag-name=<tag>"`                |
+| plan (Testomat.io plan id) | `"testomatio:plan=<plan-id>"`                |
+| label                      | `"testomatio:label=<label>"`                 |
+| label with value           | `"testomatio:label=<label>:<value>"`         |
+| Jira ticket                | `"testomatio:jira-ticket=<ticket-id>"`       |
+
+- The value must match exactly — the tag name, plan id, label, or ticket as stored in the project.
+- Works with every test framework whose runner accepts `--grep` (Playwright, CodeceptJS, Cypress, etc.) — the filter resolves to a grep pattern the runner consumes.
+
+### Filter by changed source files (`coverage:`)
+
+```
+--filter "coverage:file=<path-to-coverage-map>,diff=<git-ref>"
+```
+
+This is how "run only the tests affected by a code change" works — and it needs a **coverage map**: a YAML file mapping source files/globs to test IDs and tags. The reporter cannot know by itself which tests cover which code; the map provides that link, and the diff selects which of its entries are affected. Create the map with the `qa-test-code-coverage` skill (default `coverage.tests.yml`, one file serving both manual and automated tests).
+
+- `file=` — path to the coverage map. May be absolute; it is read with `fs`, independent of the working directory.
+- `diff=` — git ref to diff against; defaults to `master`. The reporter runs `git diff <ref> --name-only` **in `process.cwd()`** — launch it from inside the repo whose changes are being detected.
+- Changed files are mapped through the YAML; the matching suite/test IDs and tags become the run's scope.
+- Zero matching tests → no run is created (`No tests found.`); treat that as success in scripts and CI jobs.
+
+#### Picking the diff base
+
+- Changes on a branch → diff against its target branch (e.g. `origin/<default-branch>`). Full git history must be available (`fetch-depth: 0` or the CI's equivalent).
+- After a merge the target branch equals `HEAD`, so diffing against it yields nothing — use the previous mainline tip: `HEAD~1` for squash merges, `HEAD^1` for merge commits.
+
+### List matching tests without running (`--filter-list`)
+
+`--filter-list` resolves a filter and prints the matching test IDs — nothing executes, no run is created. `--format` picks the encoding: `ids` (comma-separated, default), `grep` (alternation pattern), `json`, `newline`. Exit code 0 when at least one test matched, 1 when nothing did — scripts can branch on it:
+
+```bash
+GREP=$(npx @testomatio/reporter run --filter-list "coverage:file=<coverage-map>" --format grep)
+[ -n "$GREP" ] && npx playwright test --grep "$GREP"
+```
+
+Cannot be combined with `--remote`.
+
+## Name and group the run
+
+- `TESTOMATIO_TITLE` — the run title (e.g. `PR <number>: <title>`).
+- `TESTOMATIO_RUNGROUP_TITLE` — groups related runs (per week / release / milestone).
+- `TESTOMATIO_ENV` — optional environment labels.
+
+## Report into an existing run
+
+- `TESTOMATIO_RUN=<run-id>` — the command reports or launches into that run instead of creating a new one. Works across pipelines and even across repos — pass it (with `TESTOMATIO` and the title env) into whatever process executes the tests.
+- No id at hand → shared-run title matching. Set on both sides:
+  - `TESTOMATIO_SHARED_RUN=1` — match the run by `TESTOMATIO_TITLE` instead of creating a new one;
+  - `TESTOMATIO_TITLE` — the match key, identical on both sides;
+  - `TESTOMATIO_SHARED_RUN_TIMEOUT` — minutes the title stays matchable, **default 20**; size it to the expected gap between create and launch.
+
+## Remote launch (`run --remote`)
+
+`--remote <profile-name>` asks Testomat.io to dispatch a **Testomat.io CI profile** — a CI workflow configuration saved on the project (Settings → CI) — instead of executing tests locally. Testomat.io triggers that workflow, and its results report back into the run:
+
+```bash
+TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run --remote <profile-name> \
+  --filter "coverage:file=<coverage-map>,diff=<git-ref>"
+```
+
+- With `TESTOMATIO_RUN`, the Testomat.io CI profile is triggered for that run; without it, a new run is created.
+- Works with every filter form — the resolved test ids are forwarded to the CI workflow as a grep pattern. No filter → no grep; the workflow runs its default scope, or a prepared run's stored scope from creation time. A fresh `--filter` at launch replaces the stored scope.
+- `--remote-param <key>=<value>` forwards a parameter to the Testomat.io CI profile config (repeat for several) — e.g. a preview URL or target branch.
+- Guards: cannot combine with `--filter-list`; any positional command is ignored with a warning; a missing Testomat.io CI profile fails with `CI launch failed: <message>` and exit 1.
+
+### Choosing the Testomat.io CI profile
+
+Profiles differ by workflow, job names, and parameters — never guess one. When talking to the user, always say "Testomat.io CI profile" in full and explain what it is; the bare word "profile" means nothing to them.
+
+- Testomat.io MCP connected → fetch the Testomat.io CI profiles, present the list, and ask the user to choose (see `testomatio-mcp` to connect).
+- No MCP → ask the user for the Testomat.io CI profile name.
+- None exists yet → the user must create one in Testomat.io (Settings → CI) first.
+
+## Local execution (`run "<runner command>"`)
+
+Wrap the runner and results report into the run as they come. Without a filter the whole suite runs; with one, the filter generates the grep the runner consumes:
+
+```bash
+TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run "<runner command>" \
+  --filter "testomatio:tag-name=<tag>"
+```
+
+## PR/MR comments
+
+When results report, the reporter posts and updates the PR/MR summary comment itself — never script a comment API call. Enable the pipe by setting its token:
+
+| Platform  | Env var                  | Note                                               |
+| --------- | ------------------------ | -------------------------------------------------- |
+| GitHub    | `GH_PAT`                 | the workflow's built-in token works inside PR runs |
+| GitLab    | `GITLAB_PAT`             | access token with `api` scope                      |
+| Bitbucket | `BITBUCKET_ACCESS_TOKEN` | repository access token                            |
+
+No pipe for the platform (e.g. Azure DevOps) → no comment; results remain visible in Testomat.io.
+
+## Related skills
+
+`qa-test-code-coverage` (creates the coverage map the `coverage:` filter needs), `setup-pr-testing` (wires these commands into a CI pipeline), `qa-e2e-tests-reporting` (install and configure the reporter in an automation project).

package/skills/testomatio/test-automation/setup-pr-testing/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: setup-pr-testing
+description: Set up CI so pull requests drive selective testing with Testomat.io. When a PR opens, a test run scoped to its changes is created for testers. The affected automated tests launch after a preview deploy or on merge. Use when the user wants to integrate Testomat.io runs into a CI pipeline, create test runs per pull request, or trigger affected tests from CI events.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 2.1.0
+---
+
+# Setup PR Testing
+
+I set up a project's CI for PR-driven testing. What gets wired depends on the project's tests:
+
+- manual — testers get a run to start on Testomat.io the moment the PR opens; nothing to execute.
+- automated — an execution mode must be chosen: inline in the pipeline, a Testomat.io CI profile, or another workflow/repo.
+- mixed — both, sharing one run per PR.
+
+Every reporter command the jobs execute is documented in `run-tests-with-testomatio-reporter` — read it before wiring.
+
+> **GOAL: a working pipeline committed to the project's own CI system.** That CI configuration is the one and only finished result. I run locally to author it — I am never part of CI. Do not execute reporter commands while authoring; the one exception is the final battle-test (Step 7), on a PR the user picked.
+
+## Possible flows
+
+Post this diagram as a chat message before the first question — never open with a question; it frames everything that follows. When questions go through a form or tool, the diagram must already be on screen in an earlier message. Render diagrams as Mermaid when the environment displays it; fall back to ASCII otherwise.
+
+Never post a diagram bare — follow it immediately with one short paragraph explaining it: this is the general schema of PR testing, for the user to examine before anything is implemented; a run is created when a PR opens, and the user will now choose which types of tests execute (manual, automated, or both) and how the automated ones run — inline in the pipeline, through a Testomat.io CI profile, or by dispatching another repo — and when they launch (preview deploy or merge).
+
+```mermaid
+flowchart LR
+    PR([PR opened]) --> RUN[Create a run scoped<br/>to the PR changes]
+    RUN -->|manual / mixed| TESTERS[Testers execute manual cases<br/>on Testomat.io]
+    RUN -->|automated / mixed| SCHED[Schedule automated tests —<br/>nothing runs yet]
+    SCHED --> TRIG{When to launch?}
+    TRIG -->|preview deployed| MODE{How to execute?}
+    TRIG -->|PR merged| MODE
+    MODE -->|via a Testomat.io CI profile| RES
+    MODE -->|inline in this pipeline| RES
+    MODE -->|by dispatching another repo| RES
+    RES[Run the affected automated tests —<br/>results land in the PR run]
+```
+
+Keep every diagram clear: verb-first action blocks ("Create a run", "Testers execute manual cases"), decisions as questions, configuration details in the text below — never as blocks, and end at an outcome.
+
+- Manual-only project → only the top branch: the run is complete at creation, testers execute it on Testomat.io, nothing launches.
+- Automated-only project → only the bottom branch: the scheduled run launches on a trigger through the chosen mode.
+- Mixed project → both branches share one run per PR.
+
+## The coverage map drives everything
+
+A coverage map maps source files/globs to test identifiers; the reporter filters it by the diff so only impacted tests are prepared and run. It is produced by the `qa-test-code-coverage` skill — default `coverage.tests.yml`, one file serving both manual and automated tests. Missing map → delegate to `qa-test-code-coverage`; never hand-write one here. Without a map nothing can be filtered and no pipeline can be wired.
+
+## Method, not snippets
+
+The valuable knowledge here is the flow model and the decisions to confirm with the user. The reporter commands come from `run-tests-with-testomatio-reporter`; translating triggers into a specific CI's YAML/Groovy is yours — you already know how every CI expresses "on PR open", "after deploy finished", "on merge", "carry a value between pipelines", and "don't fail the pipeline". Write that config for the CI in front of you; never bake per-CI workflow files into this skill.
+
+## Critical Constraints
+
+- **Never execute the reporter while authoring — the deliverable is committed CI config.** Sole exception: the user-approved battle-test (Step 7).
+- **Battle-test executes tests only for an already-merged PR**; an open PR only gets a run created.
+- **Only touch CI config files** — never source or test files.
+- Diagrams gate the dialogue: flows diagram before the first question, selected-flow diagram approved before wiring (Step 3), every diagram followed by a one-paragraph explanation.
+- Discovery first — delegate to `scan-automation-project` before writing anything.
+- Never assume or hardcode the CI system; read the repo, ask if unclear.
+- Never guess a Testomat.io CI profile name — pick from a list (Testomat.io MCP) confirmed by the user, or ask.
+- Say "Testomat.io CI profile" in full, never bare "profile"; every question option explains itself in plain words.
+- Avoid presenting the project's full test inventory as the run scope; never print full test lists.
+- No coverage map → no pipeline; delegate map creation to `qa-test-code-coverage`.
+- The PR-open job creates the run and executes nothing.
+- Preview launches gate on the deploy-finished signal, never on the push.
+- Launch jobs never block a PR and never fail a merge/release pipeline.
+- PR comments come from the reporter's own pipes — never script a PR-comment API call.
+- Every run gets a PR-based title and a rungroup.
+
+## Workflow
+
+### Step 1 — Discover
+
+- Delegate to `scan-automation-project`: are there manual `.test.md` cases, which e2e framework exists (unit/integration don't count), do automated tests live in this repo or elsewhere.
+- The result fixes the project kind — manual, automated, or mixed — and with it which flows apply.
+- Read the repo's CI config files to identify the CI system. Several CIs or none → ask which one runs PRs.
+- Locate the coverage map (default `coverage.tests.yml`). Missing → propose creating it and delegate to `qa-test-code-coverage`.
+
+### Step 2 — Present the flows and ask the unknowns
+
+Post the possible-flows diagram, trimmed to the kinds found in Step 1, as its own message with its one-paragraph explanation (what the schema is, which choices the user is about to make) — then ask only what applies. Read the CI files first so you don't ask what's already answered.
+
+Manual tests found — nothing to choose: their part of the run is complete at creation, testers start on Testomat.io immediately.
+
+Automated tests found — ❓ choose the execution mode. Each option in the question must explain itself in plain words — what runs where and who triggers it. In particular spell out what a Testomat.io CI profile is: a CI workflow configuration saved on the Testomat.io project (Settings → CI) that Testomat.io dispatches to execute the tests, with results reporting back into the run.
+
+| Mode                            | When it fits                                                                                                  |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Remote — Testomat.io CI profile | a Testomat.io CI profile for the e2e suite exists (Settings → CI); Testomat.io owns runner, env, secrets      |
+| Inline — this pipeline          | mobile/simulators, services this pipeline spins up, or an e2e job that already works in this repo             |
+| Cross-repo dispatch             | the e2e suite lives in another repo and no Testomat.io CI profile covers it                                   |
+
+- Remote chosen → identify the Testomat.io CI profile, never guess it: Testomat.io MCP connected → fetch the list, present it, ❓ ask the user to choose (profiles differ by workflow and job names); no MCP → ❓ ask for the exact profile name; none exists yet → creating one in Testomat.io (Settings → CI) is a prerequisite; wire the launch step ready to enable.
+- No e2e suite anywhere → wire only the manual flow; never fabricate an e2e job.
+
+Then the launch triggers (automated/mixed only):
+
+1. Preview environments — is every commit deployed to a preview server? If yes: what is the observable deploy-finished signal, and where does the preview URL surface?
+2. Post-merge timing — launch right on merge, or wait for a staging/production deploy to finish? A deploy gate needs its own observable signal.
+
+And for every kind:
+
+3. Rungroup strategy — week / day / release / milestone.
+4. Diff base — the PR's target branch for PR jobs; post-merge jobs need the previous mainline tip (diff-base rules in `run-tests-with-testomatio-reporter`).
+
+### Step 3 — Confirm the selected flow
+
+- Draw the flow the answers produced — only the chosen kind, triggers, and execution mode. Mermaid when supported, ASCII otherwise.
+- ❓ Present the diagram and get approval; wire nothing until the user accepts it.
+
+Example — mixed project, Testomat.io CI profile, previews confirmed:
+
+```mermaid
+flowchart LR
+    PR([PR opened]) --> RUN[Create one mixed run<br/>scoped to the diff]
+    RUN --> TESTERS[Testers execute manual cases<br/>on Testomat.io]
+    RUN --> SCHED[Schedule automated tests —<br/>nothing runs yet]
+    PREV([Preview deployed]) --> L1[Launch automated tests via the<br/>Testomat.io CI profile, against the preview]
+    MERGE([PR merged]) --> L2[Launch automated tests<br/>with the final diff]
+    SCHED -.-> L1
+    SCHED -.-> L2
+    L1 --> RES[Results land in the PR run]
+    L2 --> RES
+```
+
+### Step 4 — Wire the phases into CI
+
+Write the jobs in the CI's own syntax; take every command and env var from `run-tests-with-testomatio-reporter`. Manual-only projects get phase (a) alone.
+
+**(a) PR opened → create the run.**
+
+- Use `start` with the coverage filter; pick the run kind matching the project's tests.
+- Persist the printed run id with the CI's native value-passing mechanism (artifact, variable, output); fallback is shared-run title matching.
+- Run once per PR (on open); pushes to the PR don't recreate runs.
+- A diff affecting zero tests creates no run — the job still succeeds.
+
+**(b) Preview deployed → launch against the preview** (only when Step 2 confirmed previews).
+
+- Trigger on the deploy-finished signal, never on the push.
+- Remote mode forwards the preview URL as a remote param; inline mode points the runner's own base-URL env at it.
+- Manual cases need no launch — testers work through them against the preview by hand.
+
+**(c) PR merged → launch with the final diff.**
+
+- Target the persisted run id; pass a fresh coverage filter with the post-merge diff base so the final merged diff decides what runs.
+- Cross-repo mode: trigger the e2e repo's pipeline with the CI's native mechanism, passing the run id, API key, and title env into it.
+- Keep the job non-blocking and off the release's critical path.
+
+### Step 5 — Ensure secrets are set
+
+- Store the project API key as `TESTOMATIO_<project_slug>` in the CI's secret store; map it to the `TESTOMATIO` env var in every job that calls the reporter. ❓ Slug unknown → ask the user.
+- Tell the user exactly where to add it: name the secret-store location the CI at hand uses for this repo/pipeline and the exact secret name to type.
+- Provision the PR-comment pipe token the same way (tokens per platform in `run-tests-with-testomatio-reporter`).
+- ❓ Ask the user to confirm the secrets are in place before the pipeline PR merges — a pipeline with missing secrets fails on its first PR.
+- The Testomat.io CI profile for remote launches is configured in Testomat.io (Settings → CI), not stored as a repo secret.
+
+### Step 6 — Suggest a PR with the new workflow
+
+- Commit the CI config on a branch and suggest opening a PR through the project's normal flow — the pipeline lands reviewed, never pushed straight to the default branch.
+- Put in the PR description: the approved flow diagram, the phases wired, the execution mode chosen, and the secrets/prerequisites the reviewers must provision before merging.
+- Where the CI runs PR-triggered workflows from the branch itself, point out that this very PR will exercise the PR-opened phase.
+
+### Step 7 — Battle-test the setup (on approval)
+
+Prove the pipeline's commands work before the CI ever runs them — by running them once, locally, on a real change.
+
+- ❓ Ask the user for a real PR to validate with — open or already merged — and for approval to create real runs.
+- Reproduce the pipeline's diff locally: open PR → check out its branch and diff against the target branch; merged PR → check out the merge commit and diff against the pre-merge tip.
+- Create the run exactly as phase (a) does — same kind, same filter — with a title that marks it as a battle-test.
+- Open PR → stop here: the run stays scheduled, nothing executes.
+- Merged PR → the change is already in mainline, so launching is safe: run the phase (c) launch against the created run.
+- Report every run created — id, kind, and the tests it scoped — and ask the user to review it in Testomat.io: does the scope match what that diff should affect?
+- Zero tests matched → report it as a finding, then pick a PR that touches mapped source files together with the user.
+
+### Step 8 — Summarize and hand off
+
+Present the approved flow diagram once more, now marked as wired. Report: the CI targeted and files written; which phases are wired and which were skipped (no previews / no e2e / no Testomat.io CI profile); the chosen execution mode; title scheme and rungroup; how the launch steps find the prepared run (run id carrier or shared title); the battle-test outcome and the runs awaiting the user's review; secrets and prerequisites still to provision; assumptions to confirm. Recommend committing the coverage map alongside the CI config.
+
+## Examples
+
+**Example 1 — mixed project, previews, Testomat.io CI profile**
+Discovery finds manual cases and an e2e suite; MCP lists the Testomat.io CI profiles and the user picks the one running the e2e suite; previews confirmed. → Diagram approved, then all three phases wired: mixed run on PR open, preview launch gated on the deployment-success event with the preview URL as a remote param, merge launch with a fresh post-merge filter. Comment pipe enabled.
+
+**Example 2 — e2e lives in another repo, no Testomat.io CI profile**
+The user picks cross-repo dispatch from the mode table: the merge job triggers the e2e repo's pipeline via the CI's native mechanism, passing the run id so results land in the prepared run. Note the Testomat.io CI profile option as the simpler future path.
+
+**Example 3 — no coverage map yet**
+No `coverage*.yml` found → explain nothing can be filtered without a map; delegate to `qa-test-code-coverage`; wire CI only after the map exists.
+
+**Example 4 — manual-only project**
+`scan-automation-project` finds `.test.md` cases and no e2e framework → the flows diagram shows only the manual branch; no execution-mode or trigger questions asked. One phase wired: a manual run per PR, complete at creation — testers start on Testomat.io. Explain that launch phases need an e2e suite first.
+
+## Related skills
+
+`run-tests-with-testomatio-reporter` (the reporter commands every job executes), `qa-test-code-coverage` (creates the coverage map this skill consumes), `scan-automation-project` (mandatory discovery), `qa-e2e-tests-reporting` (install the reporter if the project has no Testomat.io integration yet), `sync-test-cases-with-tms` (manual cases not yet in Testomat.io).