testeiya 0.3.9 → 0.3.14

package/skills/playwright/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/skills/playwright/playwright-cli/references/video-recording.md

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows inserting appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/skills/skills.lock.json

@@ -3,55 +3,59 @@
     {
       "source": "testomatio/skills",
       "ref": null,
-      "sha": "fa1cf38572773bae6c6ffe417392587b5d8087e2",
+      "sha": "ef338b8b8dfabfdd523a7f00544d00c3705946f6",
       "folder": "testomatio",
       "skills": [
-        "testomatio-mcp",
-        "sync-test-cases-with-tms",
-        "scan-automation-project",
-        "qa-write-test-cases",
-        "qa-thinking",
-        "qa-test-code-coverage",
-        "qa-sprint-report-by-testomatio",
-        "qa-split-testing-levels-pyramid",
-        "qa-requirement-reviewer",
-        "qa-pr-requirements-analyzer",
-        "qa-e2e-tests-reporting",
-        "pull-request-diff-analyzer",
-        "improve-test-cases",
+        "automate-manual-test-cases",
+        "debug-fix-failed-flaky-autotests",
         "detect-duplicate-test-cases",
-        "setup-ci-automation",
-        "setup-change-aware-pr-testing",
-        "run-tests-with-testomatio-reporter",
-        "qa-data-seeder",
+        "explorbot-fundamentals",
+        "explorbot-plan",
+        "explorbot-setup",
+        "improve-test-cases",
+        "prima",
+        "pull-request-diff-analyzer",
         "qa-automation-test-consolidation",
-        "debug-fix-failed-flaky-autotests",
-        "automate-manual-test-cases",
+        "qa-data-seeder",
+        "qa-e2e-tests-reporting",
+        "qa-explain-behavior",
+        "qa-lead-strategy-advisor",
+        "qa-pr-requirements-analyzer",
+        "qa-requirement-reviewer",
+        "qa-split-testing-levels-pyramid",
+        "qa-sprint-report-by-testomatio",
+        "qa-test-code-coverage",
+        "qa-thinking",
+        "qa-write-test-cases",
+        "run-tests-with-testomatio-reporter",
+        "scan-automation-project",
+        "setup-change-aware-pr-testing",
+        "setup-ci-automation",
+        "sync-test-cases-with-tms",
+        "testing-workflow",
         "testomat-allure-adapter",
-        "explorbot-setup",
-        "explorbot-plan",
-        "explorbot-fundamentals"
+        "testomatio-mcp"
       ]
     },
     {
       "source": "codeceptjs/skills",
       "ref": null,
-      "sha": "e19ba9d0f513cbc9c3e4a4c5c6dd02cfedde4afd",
+      "sha": "d3d6a4e0e29207b1afb051eeb6f5f36984f4752b",
       "folder": "codeceptjs",
       "skills": [
-        "writing-codeceptjs-tests",
-        "refactoring-codeceptjs-tests",
-        "migrate-testcafe-to-codeceptjs",
-        "migrate-selenium-java-to-codeceptjs",
-        "migrate-protractor-to-codeceptjs",
-        "migrate-cypress-to-codeceptjs",
-        "migrate-codeceptjs-4",
-        "debugging-codeceptjs-tests",
-        "codeceptjs-run-analysis",
-        "codeceptjs-fundamentals",
-        "codeceptjs-exploration",
+        "ci-fix-tests",
         "codeceptjs-auth",
-        "ci-fix-tests"
+        "codeceptjs-exploration",
+        "codeceptjs-fundamentals",
+        "codeceptjs-run-analysis",
+        "debugging-codeceptjs-tests",
+        "migrate-codeceptjs-4",
+        "migrate-cypress-to-codeceptjs",
+        "migrate-protractor-to-codeceptjs",
+        "migrate-selenium-java-to-codeceptjs",
+        "migrate-testcafe-to-codeceptjs",
+        "refactoring-codeceptjs-tests",
+        "writing-codeceptjs-tests"
       ]
     },
     {
@@ -66,7 +70,7 @@
     {
       "source": "microsoft/playwright-cli/tree/main/skills/playwright-cli",
       "ref": null,
-      "sha": "4f9d85a9472fc6d0c9a91ac62f3f3ecc24c16de2",
+      "sha": "60cb176373cf4400405122703e6de26cd58c7a1c",
       "folder": "playwright",
       "skills": [
         "playwright-cli"

package/skills/skills.yaml

@@ -32,3 +32,4 @@
   folder: playwright
 - source: microsoft/playwright-cli/tree/main/skills/playwright-cli
   folder: playwright
+

package/skills/testomatio/explorbot/explorbot-fundamentals/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: explorbot-fundamentals
+description: Use when running or debugging Explorbot from the command line — which command to run, what a flag does, where results were written, why a run failed, or how to run it with nothing installed in the project.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 1.2.0
+---
+
+# Explorbot Fundamentals
+
+Explorbot is an autonomous AI web-testing CLI. It drives its own browser through cycles of research → plan → test, and an agent drives it like `git` or `npm`.
+
+**Answer command and flag questions from the installed CLI, never from memory.**
+
+```bash
+npx explorbot --help                  # commands, and the EXPLORBOT_* variables
+npx explorbot <command> --help        # flags for one command
+```
+
+## Running it with nothing installed
+
+Explorbot needs no project install: `npx` plus a provider is enough, and nothing is written into the working directory. Reach for this when the user wants to try Explorbot, or is pointing it at an app that has no repo here.
+
+```bash
+npx explorbot init --global --provider <name>          # once per machine, key in ~/.explorbot/.env
+npx explorbot explore https://app.example.com/login --max-tests 3
+```
+
+Details, including the per-command `EXPLORBOT_*` form for CI: [references/no-install.md](references/no-install.md).
+
+Installing into the project instead — config, knowledge, and generated tests in the repo — is [[explorbot-setup]].
+
+## Docs
+
+`node_modules/explorbot/docs/` after a local install, the repo's `docs/` when working inside Explorbot itself, otherwise `https://raw.githubusercontent.com/testomatio/explorbot/main/docs/<path>`. `docs/index.json` lists every page with a description — read it to pick the page, then open that page.
+
+## Where results land
+
+Explorbot writes into the project directory when the run used a project `explorbot.config.js`, and into `~/.explorbot/sites/<host>/` otherwise. Under that root:
+
+| Path | Contents |
+|---|---|
+| `output/reports/` | session report: coverage, defects, execution issues |
+| `output/plans/` | the plan generated or executed |
+| `output/states/` | per-state HTML, ARIA snapshots, screenshots |
+| `output/research/` | UI maps from the Researcher |
+| `output/tests/` | generated Playwright / CodeceptJS files |
+| `output/explorbot.log` | run log — start here on a failure |
+| `knowledge/`, `experience/` | what you taught it, and what it learned |
+
+**Exit codes are not pass/fail.** `explore` and `test` exit `0` whenever the session completes; a failing scenario is a result, not a crash. Read the report. `navigate` is the exception — `1` means unreachable, which makes it a pre-flight check.
+
+## Naming the site
+
+A target is either **absolute** — starting with `http://` or `https://` — or a **relative path** starting with `/`. Anything else is ambiguous and not a valid target.
+
+A relative path needs a site to resolve against: `web.url` from a project config, or `EXPLORBOT_URL`. Without either, pass the absolute URL. Commands that take no target at all — `test`, `learn`, `knows`, `experience`, `compact` — read the same two sources. `npx explorbot sites` lists what has been explored so far.
+
+## Cheap before expensive
+
+- `npx explorbot context <url>` — headings, matched knowledge, interactive elements. No AI calls.
+- `npx explorbot shell <url> '<codecept command>'` — run one command and exit.
+- `npx explorbot knows <url>` — what knowledge matches a page.
+- `npx explorbot navigate <url> --session` — reachability, and it saves the session.
+
+## Rules
+
+- `explorbot start` is an interactive TUI — an agent cannot operate it. Ask the user to run it. Everything else runs headless and exits.
+- If `--help` does not show a command or flag, it does not exist.
+- Explorbot needs CRUD; a landing page, blog, or CMS is out of scope.
+
+## Related skills
+
+- [[explorbot-setup]] — install into a project: config, provider, login knowledge, verified navigation.
+- [[explorbot-plan]] — hand-author a test plan and run it with `explorbot test`.

package/skills/testomatio/explorbot/explorbot-fundamentals/references/no-install.md

@@ -0,0 +1,36 @@
+# Running Explorbot without installing it
+
+Two ways, both `npx`. Neither writes anything into the working directory: knowledge, experience, and output go to `~/.explorbot/sites/<host>/`.
+
+## Once per machine
+
+```bash
+npx explorbot init --global --provider <name>
+```
+
+Writes `~/.explorbot/config.js` with the model ids recommended by that Explorbot version, and `~/.explorbot/.env` with the provider's key variable — add the key there, or pass `--api-key`. `npx explorbot init --help` lists the accepted providers. With `--provider` there is no wizard, so an agent can run it unattended.
+
+Every directory can then run Explorbot, and each app keeps what Explorbot learned about it between runs. With no project config there is no site to resolve a relative path against, so pass the absolute URL — or set `EXPLORBOT_URL` and pass paths:
+
+```bash
+npx explorbot explore https://app.example.com/login --max-tests 3
+EXPLORBOT_URL=https://app.example.com npx explorbot explore /dashboard
+npx explorbot sites                                    # what has been explored, and when
+```
+
+## Per command
+
+When nothing may be written — CI, containers, someone else's machine — `EXPLORBOT_AI_PROVIDER` builds the config from the environment:
+
+```bash
+EXPLORBOT_URL=https://app.example.com \
+EXPLORBOT_AI_PROVIDER=<name> \
+  npx explorbot explore /login --max-tests 3
+```
+
+- `npx explorbot --help` lists every `EXPLORBOT_*` variable of the installed version — read it there rather than copying a list.
+- `EXPLORBOT_KNOWLEDGE="Log in as …"` applies knowledge to every page without a file; `EXPLORBOT_KNOWLEDGE_FILE` points at one.
+- Model variables take a provider name for its recommendation, or `provider/model-id` to pin one.
+- These variables win over `~/.explorbot/config.js`; a project `explorbot.config.js` wins over them.
+- `EXPLORBOT_EPHEMERAL=1` keeps nothing between runs.
+- Trade-off: the Historian is off, so no generated Playwright or CodeceptJS files. Plans and reports are still written.

package/skills/testomatio/explorbot/explorbot-plan/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: explorbot-plan
+description: Use when the user wants to write an Explorbot test plan by hand — from a feature description, requirements, ticket, or docs, without exploring a live page — so `explorbot test` can run it.
+license: MIT
+metadata:
+  author: Testomat.io
+  version: 0.1.0
+---
+
+# Writing Explorbot Test Plans
+
+Write an Explorbot **test plan** by hand in Explorbot's exact markdown format, from a feature
+description / requirements / docs and a starting URL. No browser or live exploration needed.
+
+**Explorbot does not need to be installed to author a plan** — it is just a markdown file.
+Installation is only required later to *run* the plan (see Output).
+
+## Inputs to gather
+
+- The feature / requirements / user story (ask for docs or a description).
+- A suite title (the feature under test).
+- The **start URL**: a path relative to the app host (e.g. `/login`), or a full absolute URL.
+  This is mandatory. Relative paths resolve against `web.url` in a project config, or against
+  the site the command names (`EXPLORBOT_URL` / a registered host) in global mode.
+- Optional per-test start URLs when a scenario begins on a different page.
+- Priority for each scenario: `critical`, `important`, `high`, `normal`, `low`.
+
+## Format
+
+```markdown
+<!-- suite -->
+# User Authentication
+
+### Prerequisite
+
+* URL: /login
+
+<!-- test
+priority: critical
+-->
+# User signs in with valid credentials
+
+## Requirements
+/login
+
+## Steps
+* Enter a registered email in the email field
+* Enter the matching password
+* Submit the sign-in form
+
+## Expected
+* The user lands on the authenticated dashboard
+* The signed-in account is shown in the header
+
+<!-- test
+priority: high
+-->
+# Sign-in is rejected for an unknown account
+
+## Requirements
+/login
+
+## Steps
+* Enter an unregistered email and any password
+* Submit the sign-in form
+
+## Expected
+* An invalid-credentials error is shown
+* The user stays on the sign-in page
+```
+
+## Rules
+
+- `<!-- suite -->` then the **next line** is `# Suite Title`. One suite per file is normal;
+  add more by repeating `<!-- suite -->`.
+- `### Prerequisite` — its **first list item** must be `* URL: <path>`. This documents the
+  suite-wide start page for readers and the TUI. A relative path resolves against `web.url` /
+  `playwright.url`; absolute URLs work too.
+- Each test: a `<!-- test` … `priority: <level>` … `-->` block, then `# Scenario` (h1).
+  Missing priority defaults to `normal`.
+- **Give every test its own `## Requirements` line with the start URL** (same value as the
+  Prerequisite, unless the scenario starts elsewhere). Execution reads the per-test
+  `## Requirements` URL; a test with no `## Requirements` may have no start URL and fail to
+  run. The canonical generated plans repeat the URL in every test for this reason.
+- `## Steps` and `## Expected` use `* ` bullets; wrap a long bullet by indenting continuation
+  lines two spaces.
+- Steps are **guidance** — the Tester adapts them; keep each step atomic and free of brittle
+  selectors. Every `## Expected` bullet must be **independently verifiable** (a data change,
+  state change, or UI change with a real side effect), not a restated step.
+- Scenario titles describe a **business outcome**, not a click path.
+
+## Output
+
+A hand-written plan is input only — Explorbot never rewrites it, so keep it in the repo next to
+the code it covers (`tests/plans/<feature>.md` or similar) and pass its path to `explorbot test`.
+Save it under the run's `output/plans/` only when the user wants it alongside generated plans:
+`output/plans/` in a project setup, `~/.explorbot/sites/<host>/output/plans/` in global mode.
+
+Run it (index: `1`, `1,3`, `1-5`, or `*` for all):
+
+```bash
+npx explorbot test checkout-plan.md '*'
+EXPLORBOT_URL=https://app.example.com npx explorbot test checkout-plan.md '*'
+```
+
+`test` takes no URL argument: it uses `web.url` from a project config, and needs `EXPLORBOT_URL`
+in global mode. It exits `0` whenever the session completes — read the report in
+`output/reports/`, not the exit code. See [[explorbot-fundamentals]].