@testspectra/skills 1.2.29 → 1.2.31

package/README.md

@@ -60,7 +60,7 @@ overrides the saved selection for a single invocation.
 | `shared-steps-and-actions`   | `Step.*` business workflows vs `support/actions/*` technical utilities                            |
 | `lifecycle-hooks`            | `global-hooks/` vs `specs/<suite>/hooks/`, execution order, failure cascade                       |
 | `fixtures-data`              | `fixtures/*.json` and the ambient `Fixture.*` namespace                                           |
-| `network-interception`       | `Spectra.intercept()` mocking, polling, and failure-simulation patterns                           |
+| `network-interception`       | `Spectra.intercept()` mocking and failure simulation; `Spectra.spy()` to wait for a real API      |
 
 Each skill is grounded in `docs/v2/` and the reference workspace at `cli/templates/default`, so an
 AI coding agent scaffolding TestSpectra scripts produces code that already passes `spectra lint`.

package/dist/skills/matchers-and-assertions/SKILL.md

@@ -93,7 +93,8 @@ per platform, traversal keeps one API.
 Every assertion above (and every collection matcher in section 3) accepts a trailing
 `options?: { timeoutMs }` to override the adaptive fail-fast timeout for that one call, without
 raising it for every other assertion in the test — use this when a specific assertion is known to
-need longer, e.g. right after a deliberately delayed `Spectra.intercept(..., { delayMs })` mock:
+need longer. To wait for an API, don't raise a timeout: `await spy.waitForResponse()` (or the
+intercept handle's, after a deliberate `delayMs`) — see the `network-interception` skill.
 
 ```typescript
 await ReportPage.statusBadge.shouldHaveText('Ready', { timeoutMs: 5000 });
@@ -153,6 +154,7 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 | Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                                                           |
 | Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                                                          |
 | Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill                             |
+| Network spy    | `const api = await Spectra.spy(pattern, method); ...; await api.waitForResponse()` — see the `network-interception` skill            |
 
 ## 6. `Spectra.browser.*` — Browser/Context Level
 

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

@@ -1,6 +1,6 @@
 ---
 name: network-interception
-description: The Spectra.intercept() API for deterministic network mocking in TestSpectra — InterceptRule/MockResponse/MockHandle shapes, respondOnce vs respondWith sequential polling, aborting requests, and waitForCall/shouldHaveCallCount assertions. Use whenever a test needs to mock, stub, or assert on an API call instead of hitting the real backend.
+description: The Spectra.intercept() and Spectra.spy() APIs in TestSpectra — InterceptRule/MockResponse/MockHandle shapes, respondOnce vs respondWith sequential polling, aborting requests, waiting for a real API with spy().waitForResponse(), and waitForCall/shouldHaveCallCount/shouldHaveStatus/shouldHaveRequestBody assertions. Use whenever a test needs to wait for, mock, stub, or assert on an API call.
 ---
 
 # Skill: Network Interception (`Spectra.intercept`)
@@ -31,7 +31,10 @@ interface MockHandle {
   respondOnce(response: MockResponse): this; // one-time FIFO-queued response
   abort(errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset'): this;
   waitForCall(options?: { timeout?: number; count?: number }): Promise<InterceptedRequest>;
+  waitForResponse(options?: { timeout?: number; count?: number }): Promise<CDPNetworkEntry>; // the answer delivered, after delayMs
   shouldHaveCallCount(count: number, options?: { timeout?: number }): Promise<void>; // polls; 0 proves no request went out
+  shouldHaveStatus(status: number, options?: { count?: number; timeout?: number }): Promise<void>; // default: the last answer
+  shouldHaveRequestBody(expected: string | object, options?: { timeout?: number }): Promise<void>; // object: JSON subset; string: substring
   readonly callCount: number;
   readonly calls: InterceptedRequest[];
 }
@@ -52,7 +55,11 @@ await Spectra.intercept({
   url: '**/api/v1/brands/*',
   method: 'PATCH',
   response: async (request) => {
-    const reply = await fetch(request.url, { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: request.postData });
+    const reply = await fetch(request.url, {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: request.postData,
+    });
     return { status: reply.status, body: await reply.text(), delayMs: 3000 };
   },
 });
@@ -123,7 +130,42 @@ it('should handle offline mode gracefully when sync fails', async () => {
 
 ---
 
-## 5. Conventions
+## 5. Pattern: Waiting for an API (`Spectra.spy`)
+
+Wait for an API with a spy, never with a guessed duration (`Spectra.sleep`). The spy leaves the
+request alone: the real server answers. Make it before the step that sends the request.
+
+```typescript
+const verify = await Spectra.spy('**/v2/iam/auth/otp/verify', 'POST'); // method default: 'ALL'
+await OtpPage.boxes.setValue('000000');
+await verify.waitForResponse(); // default timeout: the implicit wait
+await verify.shouldHaveStatus(422);
+await verify.shouldHaveRequestBody({ code: '000000' });
+await OtpPage.error.shouldHaveText('Invalid code');
+```
+
+The spy handle has the same `waitForResponse` / `shouldHaveCallCount` / `shouldHaveStatus` /
+`shouldHaveRequestBody` / `callCount` / `calls` as above. Only requests answered after the spy is
+made count. `requestBody` is cut to 500 characters: expect a part of a long body as a string.
+
+Intercept with `delayMs` only when the step reads the page while the request is in flight; then
+`waitForResponse()` before checking the result:
+
+```typescript
+const save = await Spectra.intercept({
+  url: '**/api/v1/brands',
+  method: 'POST',
+  response: { status: 201, body: {}, delayMs: 3000 },
+});
+await BrandPage.saveButton.click();
+await BrandPage.saveButton.shouldBeDisabled(); // read mid-request
+await save.waitForResponse();
+await BrandPage.toast.shouldHaveText('Brand created');
+```
+
+---
+
+## 6. Conventions
 
 - Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
   environment/base-URL changes between local, staging, and CI.
@@ -131,6 +173,8 @@ it('should handle offline mode gracefully when sync fails', async () => {
 - 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.
+- Wait for an API with `Spectra.spy(...).waitForResponse()`, not a guessed duration. Intercept +
+  `delayMs` only when the step reads the page mid-request, then `waitForResponse()` before checking the result.
 - Always assert on the mock (`waitForCall` / `shouldHaveCallCount(n)`) when the test's purpose is to
   verify the request was made — don't just assert on UI state and silently hope the mock fired. A
   blocked submit: `shouldHaveCallCount(0)` after the `should*` on the state the app settles in.

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

@@ -136,6 +136,14 @@ actual for platform "android": add android.action.ts (or the common one) in …`
   is never loaded.
 - An entity that is the same everywhere has no contract: one `common.*` file.
 
+**Split at the smallest unit.** When a page object, step or flow is the same on every platform but
+one step, keep it one `common.*` file and put only that step behind a contract. Name the contract
+for what the step achieves, not how one platform does it (`passBotCheck`, not `solveRecaptcha`);
+a platform where the step does not exist gets an actual that does nothing. Never copy a whole page
+object or script per platform for one differing step. A script stays `web.test.ts` (or
+`mobile.test.ts`) only when its subject is a mechanism that one platform has (a captcha's caption,
+a browser tab), not when it merely passes through one.
+
 ---
 
 ## 5. `spectra.config.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/skills",
-  "version": "1.2.29",
+  "version": "1.2.31",
   "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/matchers-and-assertions/SKILL.md

@@ -93,7 +93,8 @@ per platform, traversal keeps one API.
 Every assertion above (and every collection matcher in section 3) accepts a trailing
 `options?: { timeoutMs }` to override the adaptive fail-fast timeout for that one call, without
 raising it for every other assertion in the test — use this when a specific assertion is known to
-need longer, e.g. right after a deliberately delayed `Spectra.intercept(..., { delayMs })` mock:
+need longer. To wait for an API, don't raise a timeout: `await spy.waitForResponse()` (or the
+intercept handle's, after a deliberate `delayMs`) — see the `network-interception` skill.
 
 ```typescript
 await ReportPage.statusBadge.shouldHaveText('Ready', { timeoutMs: 5000 });
@@ -153,6 +154,7 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 | Scroll         | `await Spectra.scroll({ direction: "down", pixels: 400 })`                                                                           |
 | Mobile gesture | `await Spectra.swipe({ direction: "left", distance: 300 })`                                                                          |
 | Network mock   | `const mock = await Spectra.intercept({ url, method, response })` — see the `network-interception` skill                             |
+| Network spy    | `const api = await Spectra.spy(pattern, method); ...; await api.waitForResponse()` — see the `network-interception` skill            |
 
 ## 6. `Spectra.browser.*` — Browser/Context Level
 

package/skills/network-interception/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: network-interception
-description: The Spectra.intercept() API for deterministic network mocking in TestSpectra — InterceptRule/MockResponse/MockHandle shapes, respondOnce vs respondWith sequential polling, aborting requests, and waitForCall/shouldHaveCallCount assertions. Use whenever a test needs to mock, stub, or assert on an API call instead of hitting the real backend.
+description: The Spectra.intercept() and Spectra.spy() APIs in TestSpectra — InterceptRule/MockResponse/MockHandle shapes, respondOnce vs respondWith sequential polling, aborting requests, waiting for a real API with spy().waitForResponse(), and waitForCall/shouldHaveCallCount/shouldHaveStatus/shouldHaveRequestBody assertions. Use whenever a test needs to wait for, mock, stub, or assert on an API call.
 ---
 
 # Skill: Network Interception (`Spectra.intercept`)
@@ -31,7 +31,10 @@ interface MockHandle {
   respondOnce(response: MockResponse): this; // one-time FIFO-queued response
   abort(errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset'): this;
   waitForCall(options?: { timeout?: number; count?: number }): Promise<InterceptedRequest>;
+  waitForResponse(options?: { timeout?: number; count?: number }): Promise<CDPNetworkEntry>; // the answer delivered, after delayMs
   shouldHaveCallCount(count: number, options?: { timeout?: number }): Promise<void>; // polls; 0 proves no request went out
+  shouldHaveStatus(status: number, options?: { count?: number; timeout?: number }): Promise<void>; // default: the last answer
+  shouldHaveRequestBody(expected: string | object, options?: { timeout?: number }): Promise<void>; // object: JSON subset; string: substring
   readonly callCount: number;
   readonly calls: InterceptedRequest[];
 }
@@ -52,7 +55,11 @@ await Spectra.intercept({
   url: '**/api/v1/brands/*',
   method: 'PATCH',
   response: async (request) => {
-    const reply = await fetch(request.url, { method: 'PATCH', headers: { 'content-type': 'application/json' }, body: request.postData });
+    const reply = await fetch(request.url, {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: request.postData,
+    });
     return { status: reply.status, body: await reply.text(), delayMs: 3000 };
   },
 });
@@ -123,7 +130,42 @@ it('should handle offline mode gracefully when sync fails', async () => {
 
 ---
 
-## 5. Conventions
+## 5. Pattern: Waiting for an API (`Spectra.spy`)
+
+Wait for an API with a spy, never with a guessed duration (`Spectra.sleep`). The spy leaves the
+request alone: the real server answers. Make it before the step that sends the request.
+
+```typescript
+const verify = await Spectra.spy('**/v2/iam/auth/otp/verify', 'POST'); // method default: 'ALL'
+await OtpPage.boxes.setValue('000000');
+await verify.waitForResponse(); // default timeout: the implicit wait
+await verify.shouldHaveStatus(422);
+await verify.shouldHaveRequestBody({ code: '000000' });
+await OtpPage.error.shouldHaveText('Invalid code');
+```
+
+The spy handle has the same `waitForResponse` / `shouldHaveCallCount` / `shouldHaveStatus` /
+`shouldHaveRequestBody` / `callCount` / `calls` as above. Only requests answered after the spy is
+made count. `requestBody` is cut to 500 characters: expect a part of a long body as a string.
+
+Intercept with `delayMs` only when the step reads the page while the request is in flight; then
+`waitForResponse()` before checking the result:
+
+```typescript
+const save = await Spectra.intercept({
+  url: '**/api/v1/brands',
+  method: 'POST',
+  response: { status: 201, body: {}, delayMs: 3000 },
+});
+await BrandPage.saveButton.click();
+await BrandPage.saveButton.shouldBeDisabled(); // read mid-request
+await save.waitForResponse();
+await BrandPage.toast.shouldHaveText('Brand created');
+```
+
+---
+
+## 6. Conventions
 
 - Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
   environment/base-URL changes between local, staging, and CI.
@@ -131,6 +173,8 @@ it('should handle offline mode gracefully when sync fails', async () => {
 - 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.
+- Wait for an API with `Spectra.spy(...).waitForResponse()`, not a guessed duration. Intercept +
+  `delayMs` only when the step reads the page mid-request, then `waitForResponse()` before checking the result.
 - Always assert on the mock (`waitForCall` / `shouldHaveCallCount(n)`) when the test's purpose is to
   verify the request was made — don't just assert on UI state and silently hope the mock fired. A
   blocked submit: `shouldHaveCallCount(0)` after the `should*` on the state the app settles in.

package/skills/workspace-structure/SKILL.md

@@ -136,6 +136,14 @@ actual for platform "android": add android.action.ts (or the common one) in …`
   is never loaded.
 - An entity that is the same everywhere has no contract: one `common.*` file.
 
+**Split at the smallest unit.** When a page object, step or flow is the same on every platform but
+one step, keep it one `common.*` file and put only that step behind a contract. Name the contract
+for what the step achieves, not how one platform does it (`passBotCheck`, not `solveRecaptcha`);
+a platform where the step does not exist gets an actual that does nothing. Never copy a whole page
+object or script per platform for one differing step. A script stays `web.test.ts` (or
+`mobile.test.ts`) only when its subject is a mechanism that one platform has (a captcha's caption,
+a browser tab), not when it merely passes through one.
+
 ---
 
 ## 5. `spectra.config.ts`