@testspectra/skills 1.2.34 → 1.2.36

package/dist/skills/debugging-runs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging-runs
-description: How to read a failing or slow `spectra run` — the failure context, the warnings, the step lines, the network and intercept records — and `spectra diagnose` for failures that pass with `--delay`. Use whenever a test fails, times out, or a run slows down, before changing the script.
+description: How to read a failing or slow `spectra run` — `--agent` output, `spectra report`, the page snapshot, the failure context, the warnings, the step lines, the network and intercept records — how to pause a test at a line or a failure and inspect the live page with `spectra inspect`, and `spectra diagnose` for failures that pass with `--delay`. Use whenever a test fails, times out, or a run slows down, before changing the script.
 ---
 
 # Skill: Debugging a run
@@ -8,6 +8,50 @@ description: How to read a failing or slow `spectra run` — the failure context
 Read what the run already reports before you change a script or add a wait. Every signal below is
 printed by `spectra run` (plain output, CI, or an agent's shell) and saved under `.testspectra/reports/`.
 
+## 0. Agent workflow
+
+```bash
+spectra run <spec> --agent          # compact output; ends with a failure digest
+spectra report                      # the same digest for the last run (--json for JSON)
+```
+
+For each failed case the digest gives `at:` (the spec/page-object line), `failed step:` (or
+`after step:` when the test's own code threw), the error, the last steps, and three files:
+
+- `page:` — `.testspectra/reports/snapshots/<case>.md`, a text outline of the page at the failure:
+  URL, open dialogs, alerts, headings, every visible interactive element with its state
+  (`disabled`, `covered by <div#overlay>`, `off-screen`) and a selector `Spectra.get()` accepts.
+  Read it before the screenshot.
+- `screenshot:` and `video:`.
+
+The `⏱` line splits a case's time into setup / beforeEach / body / afterEach / artifacts and says how
+much no step accounts for; `… untracked Nms` under a group is time spent outside reported steps.
+
+### Breakpoints: look at the live page
+
+```bash
+spectra run <spec> --agent --break-at specs/Auth/TC-1/web.test.ts:42   # before the steps line 42 runs
+spectra run <spec> --agent --break-at step:7                           # before step #7
+spectra run <spec> --agent --break-on-failure                          # where it fails, before afterEach
+```
+
+Run it in the background; when it prints `⏸ Paused`, drive it from another shell:
+
+```bash
+spectra inspect                    # where it is paused and why
+spectra inspect snapshot           # page outline with selectors
+spectra inspect eval "document.querySelector('#email').value"
+spectra inspect exec "await Spectra.get('~Close').click(); return Spectra.browser.getUrl()"
+spectra inspect screenshot
+spectra inspect next               # run one step, pause again
+spectra inspect continue           # run to the next breakpoint or the end
+spectra inspect abort              # fail the case here
+```
+
+Try a fix with `exec` on the paused page, then put it in the script. A pause nobody resumes continues
+by itself after 15 minutes (`TESTSPECTRA_BREAK_TIMEOUT_MS`). Breakpoints run one worker and lift
+the test timeout.
+
 ## 1. Signals and what they mean
 
 | Signal                                                                 | Meaning                                                                                           | Do                                                                                       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/skills",
-  "version": "1.2.34",
+  "version": "1.2.36",
   "description": "Installer & manager for modular AI agent skills that standardize TestSpectra script authoring (specs, page objects, steps, actions, hooks, fixtures, matchers)",
   "keywords": [
     "agents",

package/skills/debugging-runs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging-runs
-description: How to read a failing or slow `spectra run` — the failure context, the warnings, the step lines, the network and intercept records — and `spectra diagnose` for failures that pass with `--delay`. Use whenever a test fails, times out, or a run slows down, before changing the script.
+description: How to read a failing or slow `spectra run` — `--agent` output, `spectra report`, the page snapshot, the failure context, the warnings, the step lines, the network and intercept records — how to pause a test at a line or a failure and inspect the live page with `spectra inspect`, and `spectra diagnose` for failures that pass with `--delay`. Use whenever a test fails, times out, or a run slows down, before changing the script.
 ---
 
 # Skill: Debugging a run
@@ -8,6 +8,50 @@ description: How to read a failing or slow `spectra run` — the failure context
 Read what the run already reports before you change a script or add a wait. Every signal below is
 printed by `spectra run` (plain output, CI, or an agent's shell) and saved under `.testspectra/reports/`.
 
+## 0. Agent workflow
+
+```bash
+spectra run <spec> --agent          # compact output; ends with a failure digest
+spectra report                      # the same digest for the last run (--json for JSON)
+```
+
+For each failed case the digest gives `at:` (the spec/page-object line), `failed step:` (or
+`after step:` when the test's own code threw), the error, the last steps, and three files:
+
+- `page:` — `.testspectra/reports/snapshots/<case>.md`, a text outline of the page at the failure:
+  URL, open dialogs, alerts, headings, every visible interactive element with its state
+  (`disabled`, `covered by <div#overlay>`, `off-screen`) and a selector `Spectra.get()` accepts.
+  Read it before the screenshot.
+- `screenshot:` and `video:`.
+
+The `⏱` line splits a case's time into setup / beforeEach / body / afterEach / artifacts and says how
+much no step accounts for; `… untracked Nms` under a group is time spent outside reported steps.
+
+### Breakpoints: look at the live page
+
+```bash
+spectra run <spec> --agent --break-at specs/Auth/TC-1/web.test.ts:42   # before the steps line 42 runs
+spectra run <spec> --agent --break-at step:7                           # before step #7
+spectra run <spec> --agent --break-on-failure                          # where it fails, before afterEach
+```
+
+Run it in the background; when it prints `⏸ Paused`, drive it from another shell:
+
+```bash
+spectra inspect                    # where it is paused and why
+spectra inspect snapshot           # page outline with selectors
+spectra inspect eval "document.querySelector('#email').value"
+spectra inspect exec "await Spectra.get('~Close').click(); return Spectra.browser.getUrl()"
+spectra inspect screenshot
+spectra inspect next               # run one step, pause again
+spectra inspect continue           # run to the next breakpoint or the end
+spectra inspect abort              # fail the case here
+```
+
+Try a fix with `exec` on the paused page, then put it in the script. A pause nobody resumes continues
+by itself after 15 minutes (`TESTSPECTRA_BREAK_TIMEOUT_MS`). Breakpoints run one worker and lift
+the test timeout.
+
 ## 1. Signals and what they mean
 
 | Signal                                                                 | Meaning                                                                                           | Do                                                                                       |