@testspectra/skills 1.2.22 → 1.3.0

package/README.md

@@ -53,6 +53,7 @@ overrides the saved selection for a single invocation.
 | Skill                        | Covers                                                                                            |
 | :--------------------------- | :------------------------------------------------------------------------------------------------ |
 | `workspace-structure`        | Directory layout, zero-import architecture, file suffixes, `spectra.config.ts`, core CLI commands |
+| `debugging-runs`             | Reading a failing or slow run: failure context, warnings, intercept records, `spectra diagnose`   |
 | `spec-and-suite-authoring`   | `suite.md` / `spec.md` frontmatter, the paired `*.test.ts` script, every `spectra lint` rule      |
 | `page-objects-and-selectors` | Page Object pattern (`Spectra.get`/`getAll`), the `~`/`#` selector contract                       |
 | `matchers-and-assertions`    | Full element action/assertion/collection matcher and global `Spectra.*` command reference         |

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

@@ -0,0 +1,51 @@
+---
+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.
+---
+
+# Skill: Debugging a run
+
+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/`.
+
+## 1. Signals and what they mean
+
+| Signal                                                                 | Meaning                                                                                           | Do                                                                                       |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `── failure context ──` (`[TESTSPECTRA_FAILURE_CONTEXT]` as JSON)      | The page when the test failed: last step, URL, focused element, open dialogs, input rates, CDP calls, a screenshot | Open the screenshot; check the focused element and the dialogs against what the step expected |
+| `"resolved":"<button aria-label=…>"` on a click/type step              | The element the action actually hit                                                               | If it is not the one you meant, the lookup is wrong (a position, a repeated name)        |
+| `⚠ the page received N keydown events/s`                                | Input is repeating (a stuck key, a script re-dispatching)                                         | Find the step named in the warning; the page is unusable after it                        |
+| `⚠ the page's main thread is busy` / `CDP command … timed out during step #N` | The page did not answer                                                                    | Look for an input storm or long tasks first, not for a longer timeout                    |
+| `[TESTSPECTRA_INTERCEPT] '<pattern>' (METHOD) answered METHOD <url>`   | Which mock answered which request                                                                 | A URL you did not mean: narrow the pattern (a glob matches the whole URL)                |
+| `⚠ intercept '<pattern>' … answered no request`                        | The mock never matched                                                                            | Check its URL and method                                                                 |
+| `[TESTSPECTRA_STATE_CARRIED] … sessionStorage: <keys>`                  | Storage the previous test case left (`isolation: 'suite'`)                                        | A test that passes alone but fails in the suite: clear those keys in `beforeEach`, or set `webConfig.isolation: 'testcase'` |
+| `⚠ another spectra run (pid …) is testing <url>`                       | Two runs share one server and reset each other's data                                             | Stop one; results of both runs are unreliable                                            |
+| `Typed text did not reach … (focus was on …; the field is …)`          | The keystrokes went elsewhere, or the field was disabled/inert                                    | Wait for the state that enables the field                                                |
+
+`network-resources.json` holds every request with its HTTP method, request body and, when a mock
+answered it, `interceptedBy`. The terminal no longer prints one line per request; set
+`TESTSPECTRA_STREAM_NETWORK=1` to stream them.
+
+## 2. A test that passes with `--delay`
+
+It waits for no state. Ask the runner which step:
+
+```bash
+spectra diagnose --spec <id>
+```
+
+It reruns the spec with a wait after one step at a time, closest to the failure first, and prints
+the step the test must wait after (`before step #33: click <button aria-label="Close dialog">`).
+Put a `should*` assertion there for the state the app reaches — never a sleep. A global
+`--delay` hides transient states a spec checks on purpose ("Checking availability…").
+
+## 3. Probes, when the signals are not enough
+
+```ts
+await Spectra.browser.addInitScript(source); // runs in every document from its first instant
+const stop = Spectra.onConsole(({ type, text }) => { /* … */ });
+await Spectra.browser.cdp('Performance.getMetrics');
+await Spectra.sleep(500); // probes only
+```
+
+Delete a probe spec when you are done.

package/dist/skills/lifecycle-hooks/SKILL.md

@@ -25,6 +25,11 @@ screenshots) that shouldn't be duplicated inside every `it()` body.
 test genuinely depends on (navigating to `/login`, clearing storage) in a **suite** hook instead,
 not a global one, or the test will fail/behave differently when run in isolation.
 
+Test cases of a batch share one browser session (`webConfig.isolation: 'suite'`, the default): what
+a case leaves in cookies, localStorage or sessionStorage (a table's search and page) is there for the
+next one, and the run prints `[TESTSPECTRA_STATE_CARRIED]` naming it. Reset that state in the
+suite's `beforeEach`, or set `isolation: 'testcase'` when no `before` hook needs to log in once.
+
 ---
 
 ## 2. Directory Layout

package/dist/skills/network-interception/SKILL.md

@@ -14,7 +14,7 @@ API, simulating an error, or asserting a call happened — rather than depending
 
 ```typescript
 interface InterceptRule {
-  url: string | RegExp; // supports glob, e.g. '**/api/v1/payments/charge'
+  url: string | RegExp; // a glob matches the whole URL (a query may follow), e.g. '**/api/v1/payments/charge'
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL';
   response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
 }
@@ -105,6 +105,7 @@ it('should handle offline mode gracefully when sync fails', async () => {
 
 - Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
   environment/base-URL changes between local, staging, and CI.
+- A glob matches the whole URL: `'**/api/v1/brands'` does not also catch `/api/v1/brands/check-availability`; end it with `*` to cover every path under it.
 - Only mock what the test is actually about — don't blanket-intercept every domain; the linter and
   reviewers expect `monitoredDomains` in `spectra.config.ts` (see the `workspace-structure` skill)
   to reflect real traffic, and over-mocking hides real integration regressions.

package/dist/skills/workspace-structure/SKILL.md

@@ -124,6 +124,7 @@ export default defineConfig({
     headless: true,
     implicitWait: '5000',
     parallelizationMode: 'testcase', // "testcase" | "suite"
+    isolation: 'suite', // "suite": cases share the browser session (a before hook logs in once) | "testcase": empty cookies and storage per case
   },
   androidConfig: {
     driverServer: 'tcp://127.0.0.1:8200',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/skills",
-  "version": "1.2.22",
+  "version": "1.3.0",
   "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

@@ -0,0 +1,51 @@
+---
+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.
+---
+
+# Skill: Debugging a run
+
+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/`.
+
+## 1. Signals and what they mean
+
+| Signal                                                                 | Meaning                                                                                           | Do                                                                                       |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `── failure context ──` (`[TESTSPECTRA_FAILURE_CONTEXT]` as JSON)      | The page when the test failed: last step, URL, focused element, open dialogs, input rates, CDP calls, a screenshot | Open the screenshot; check the focused element and the dialogs against what the step expected |
+| `"resolved":"<button aria-label=…>"` on a click/type step              | The element the action actually hit                                                               | If it is not the one you meant, the lookup is wrong (a position, a repeated name)        |
+| `⚠ the page received N keydown events/s`                                | Input is repeating (a stuck key, a script re-dispatching)                                         | Find the step named in the warning; the page is unusable after it                        |
+| `⚠ the page's main thread is busy` / `CDP command … timed out during step #N` | The page did not answer                                                                    | Look for an input storm or long tasks first, not for a longer timeout                    |
+| `[TESTSPECTRA_INTERCEPT] '<pattern>' (METHOD) answered METHOD <url>`   | Which mock answered which request                                                                 | A URL you did not mean: narrow the pattern (a glob matches the whole URL)                |
+| `⚠ intercept '<pattern>' … answered no request`                        | The mock never matched                                                                            | Check its URL and method                                                                 |
+| `[TESTSPECTRA_STATE_CARRIED] … sessionStorage: <keys>`                  | Storage the previous test case left (`isolation: 'suite'`)                                        | A test that passes alone but fails in the suite: clear those keys in `beforeEach`, or set `webConfig.isolation: 'testcase'` |
+| `⚠ another spectra run (pid …) is testing <url>`                       | Two runs share one server and reset each other's data                                             | Stop one; results of both runs are unreliable                                            |
+| `Typed text did not reach … (focus was on …; the field is …)`          | The keystrokes went elsewhere, or the field was disabled/inert                                    | Wait for the state that enables the field                                                |
+
+`network-resources.json` holds every request with its HTTP method, request body and, when a mock
+answered it, `interceptedBy`. The terminal no longer prints one line per request; set
+`TESTSPECTRA_STREAM_NETWORK=1` to stream them.
+
+## 2. A test that passes with `--delay`
+
+It waits for no state. Ask the runner which step:
+
+```bash
+spectra diagnose --spec <id>
+```
+
+It reruns the spec with a wait after one step at a time, closest to the failure first, and prints
+the step the test must wait after (`before step #33: click <button aria-label="Close dialog">`).
+Put a `should*` assertion there for the state the app reaches — never a sleep. A global
+`--delay` hides transient states a spec checks on purpose ("Checking availability…").
+
+## 3. Probes, when the signals are not enough
+
+```ts
+await Spectra.browser.addInitScript(source); // runs in every document from its first instant
+const stop = Spectra.onConsole(({ type, text }) => { /* … */ });
+await Spectra.browser.cdp('Performance.getMetrics');
+await Spectra.sleep(500); // probes only
+```
+
+Delete a probe spec when you are done.

package/skills/lifecycle-hooks/SKILL.md

@@ -25,6 +25,11 @@ screenshots) that shouldn't be duplicated inside every `it()` body.
 test genuinely depends on (navigating to `/login`, clearing storage) in a **suite** hook instead,
 not a global one, or the test will fail/behave differently when run in isolation.
 
+Test cases of a batch share one browser session (`webConfig.isolation: 'suite'`, the default): what
+a case leaves in cookies, localStorage or sessionStorage (a table's search and page) is there for the
+next one, and the run prints `[TESTSPECTRA_STATE_CARRIED]` naming it. Reset that state in the
+suite's `beforeEach`, or set `isolation: 'testcase'` when no `before` hook needs to log in once.
+
 ---
 
 ## 2. Directory Layout

package/skills/network-interception/SKILL.md

@@ -14,7 +14,7 @@ API, simulating an error, or asserting a call happened — rather than depending
 
 ```typescript
 interface InterceptRule {
-  url: string | RegExp; // supports glob, e.g. '**/api/v1/payments/charge'
+  url: string | RegExp; // a glob matches the whole URL (a query may follow), e.g. '**/api/v1/payments/charge'
   method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL';
   response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
 }
@@ -105,6 +105,7 @@ it('should handle offline mode gracefully when sync fails', async () => {
 
 - Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
   environment/base-URL changes between local, staging, and CI.
+- A glob matches the whole URL: `'**/api/v1/brands'` does not also catch `/api/v1/brands/check-availability`; end it with `*` to cover every path under it.
 - Only mock what the test is actually about — don't blanket-intercept every domain; the linter and
   reviewers expect `monitoredDomains` in `spectra.config.ts` (see the `workspace-structure` skill)
   to reflect real traffic, and over-mocking hides real integration regressions.

package/skills/workspace-structure/SKILL.md

@@ -124,6 +124,7 @@ export default defineConfig({
     headless: true,
     implicitWait: '5000',
     parallelizationMode: 'testcase', // "testcase" | "suite"
+    isolation: 'suite', // "suite": cases share the browser session (a before hook logs in once) | "testcase": empty cookies and storage per case
   },
   androidConfig: {
     driverServer: 'tcp://127.0.0.1:8200',