@testspectra/skills 1.1.8-rc.2 → 1.1.8-rc.21

package/skills/network-interception/SKILL.md

@@ -1,115 +1,115 @@
----
-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/callCount assertions. Use whenever a test needs to mock, stub, or assert on an API call instead of hitting the real backend.
----
-
-# Skill: Network Interception (`Spectra.intercept`)
-
-Use this skill whenever a test needs deterministic control over a network response — mocking an
-API, simulating an error, or asserting a call happened — rather than depending on a real backend.
-
----
-
-## 1. Rule & Handle Shapes
-
-```typescript
-interface InterceptRule {
-  url: string | RegExp; // supports glob, e.g. '**/api/v1/payments/charge'
-  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL';
-  response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
-}
-
-interface MockResponse {
-  status?: number; // default: 200
-  headers?: Record<string, string>;
-  body?: any;
-  delayMs?: number;
-}
-
-interface MockHandle {
-  respondWith(response: MockResponse): this; // default response for all subsequent matches
-  respondOnce(response: MockResponse): this; // one-time FIFO-queued response
-  abort(errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset'): this;
-  waitForCall(options?: { timeout?: number; count?: number }): Promise<InterceptedRequest>;
-  readonly callCount: number;
-  readonly calls: InterceptedRequest[];
-}
-```
-
-`Spectra.intercept(rule)` is `async` and returns a `MockHandle` — always `await` it before
-interacting with the UI that triggers the call.
-
----
-
-## 2. Pattern: Single-Shot Static Mock
-
-```typescript
-it('should mock payment failure response gracefully', async () => {
-  const paymentMock = await Spectra.intercept({
-    url: '**/api/v1/payments/charge',
-    method: 'POST',
-    response: {
-      status: 402,
-      headers: { 'content-type': 'application/json' },
-      body: { error: 'insufficient_funds', message: 'Your card was declined due to insufficient funds.' },
-    },
-  });
-
-  await CheckoutPage.submitPaymentButton.click();
-
-  await paymentMock.waitForCall({ timeout: 5000 });
-  expect(paymentMock.callCount).toBe(1);
-
-  await CheckoutPage.errorBanner.shouldBeVisible();
-  await CheckoutPage.errorBanner.shouldContainText('insufficient funds');
-});
-```
-
----
-
-## 3. Pattern: Multi-Response Sequential Polling
-
-Use `respondOnce` (FIFO queue, consumed one per matching request) plus a trailing `respondWith`
-default for status-polling / retry flows:
-
-```typescript
-it('should poll export job status until completed', async () => {
-  const jobMock = await Spectra.intercept({ url: '**/api/v1/export/job-99', method: 'GET' });
-
-  jobMock.respondOnce({ status: 200, body: { status: 'pending' } });
-  jobMock.respondOnce({ status: 200, body: { status: 'processing' } });
-  jobMock.respondWith({ status: 200, body: { status: 'completed', downloadUrl: '/files/report.pdf' } });
-
-  await ExportPage.startExportButton.click();
-  await ExportPage.downloadLink.shouldBeVisible();
-});
-```
-
----
-
-## 4. Pattern: Simulating a Network Failure
-
-```typescript
-it('should handle offline mode gracefully when sync fails', async () => {
-  const syncMock = await Spectra.intercept({ url: '**/api/v1/sync' });
-  syncMock.abort('ConnectionReset');
-
-  await DashboardPage.syncButton.click();
-  await DashboardPage.offlineBanner.shouldBeVisible();
-});
-```
-
----
-
-## 5. Conventions
-
-- Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
-  environment/base-URL changes between local, staging, and CI.
-- 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.
-- Always assert on the mock (`waitForCall` / `callCount`) 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.
-- Every real (non-mocked) network call made during a run is separately captured and written to
-  `.testspectra/reports/network-resources.json` for post-run diagnostics — you don't need to record
-  this yourself.
+---
+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/callCount assertions. Use whenever a test needs to mock, stub, or assert on an API call instead of hitting the real backend.
+---
+
+# Skill: Network Interception (`Spectra.intercept`)
+
+Use this skill whenever a test needs deterministic control over a network response — mocking an
+API, simulating an error, or asserting a call happened — rather than depending on a real backend.
+
+---
+
+## 1. Rule & Handle Shapes
+
+```typescript
+interface InterceptRule {
+  url: string | RegExp; // supports glob, e.g. '**/api/v1/payments/charge'
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL';
+  response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
+}
+
+interface MockResponse {
+  status?: number; // default: 200
+  headers?: Record<string, string>;
+  body?: any;
+  delayMs?: number;
+}
+
+interface MockHandle {
+  respondWith(response: MockResponse): this; // default response for all subsequent matches
+  respondOnce(response: MockResponse): this; // one-time FIFO-queued response
+  abort(errorCode?: 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset'): this;
+  waitForCall(options?: { timeout?: number; count?: number }): Promise<InterceptedRequest>;
+  readonly callCount: number;
+  readonly calls: InterceptedRequest[];
+}
+```
+
+`Spectra.intercept(rule)` is `async` and returns a `MockHandle` — always `await` it before
+interacting with the UI that triggers the call.
+
+---
+
+## 2. Pattern: Single-Shot Static Mock
+
+```typescript
+it('should mock payment failure response gracefully', async () => {
+  const paymentMock = await Spectra.intercept({
+    url: '**/api/v1/payments/charge',
+    method: 'POST',
+    response: {
+      status: 402,
+      headers: { 'content-type': 'application/json' },
+      body: { error: 'insufficient_funds', message: 'Your card was declined due to insufficient funds.' },
+    },
+  });
+
+  await CheckoutPage.submitPaymentButton.click();
+
+  await paymentMock.waitForCall({ timeout: 5000 });
+  expect(paymentMock.callCount).toBe(1);
+
+  await CheckoutPage.errorBanner.shouldBeVisible();
+  await CheckoutPage.errorBanner.shouldContainText('insufficient funds');
+});
+```
+
+---
+
+## 3. Pattern: Multi-Response Sequential Polling
+
+Use `respondOnce` (FIFO queue, consumed one per matching request) plus a trailing `respondWith`
+default for status-polling / retry flows:
+
+```typescript
+it('should poll export job status until completed', async () => {
+  const jobMock = await Spectra.intercept({ url: '**/api/v1/export/job-99', method: 'GET' });
+
+  jobMock.respondOnce({ status: 200, body: { status: 'pending' } });
+  jobMock.respondOnce({ status: 200, body: { status: 'processing' } });
+  jobMock.respondWith({ status: 200, body: { status: 'completed', downloadUrl: '/files/report.pdf' } });
+
+  await ExportPage.startExportButton.click();
+  await ExportPage.downloadLink.shouldBeVisible();
+});
+```
+
+---
+
+## 4. Pattern: Simulating a Network Failure
+
+```typescript
+it('should handle offline mode gracefully when sync fails', async () => {
+  const syncMock = await Spectra.intercept({ url: '**/api/v1/sync' });
+  syncMock.abort('ConnectionReset');
+
+  await DashboardPage.syncButton.click();
+  await DashboardPage.offlineBanner.shouldBeVisible();
+});
+```
+
+---
+
+## 5. Conventions
+
+- Prefer glob URL patterns (`'**/api/v1/...'`) over exact origin strings so mocks survive
+  environment/base-URL changes between local, staging, and CI.
+- 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.
+- Always assert on the mock (`waitForCall` / `callCount`) 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.
+- Every real (non-mocked) network call made during a run is separately captured and written to
+  `.testspectra/reports/network-resources.json` for post-run diagnostics — you don't need to record
+  this yourself.

package/skills/page-objects-and-selectors/SKILL.md

@@ -1,132 +1,132 @@
----
-name: page-objects-and-selectors
-description: How to write a TestSpectra Page Object (Spectra.get / Spectra.getAll singleton pattern) and how the ~accessibility-id vs #native-id selector contract resolves identically across Web, Android, and iOS. Use whenever declaring element locators or a new Page Object.
----
-
-# Skill: Page Objects & the Selector Contract
-
-Use this skill whenever you add a new Page Object, add a getter to an existing one, or need to
-pick a selector string.
-
----
-
-## 1. Page Object Pattern
-
-A Page Object is a class with getter properties that return `Spectra.get(selector)` /
-`Spectra.getAll(selector)`, exported as a singleton default export, and consumed with **zero
-imports** anywhere else in the workspace (see the `workspace-structure` skill).
-
-```typescript
-// page-objects/MatchersPage/web.ts
-class MatchersPage {
-  get visibleElement() {
-    return Spectra.get('#demo-visible-el');
-  }
-  get hiddenElement() {
-    return Spectra.get('#demo-hidden-el');
-  }
-  get existingElement() {
-    return Spectra.get('#demo-existing-el');
-  }
-  get productCards() {
-    return Spectra.getAll('.demo-product-card');
-  } // collection
-
-  async open(section = '') {
-    await Spectra.navigate('/' + (section ? '#' + section : ''));
-  }
-}
-
-export default new MatchersPage();
-```
-
-Rules:
-
-- One getter per element/collection; name the getter for what the element _is_ (`submitButton`,
-  `statCards`), not for the selector string.
-- `Spectra.get(selector)` → single element; `Spectra.getAll(selector)` → collection (used with
-  collection matchers like `.shouldHaveLength(n)`).
-- Add reusable navigation/composite helpers as regular `async` methods on the same class (e.g.
-  `open()` above), not as standalone actions, when they are specific to that one page.
-- File suffix follows the platform-suffix rule: `web.ts` for CSS selectors, `mobile.ts` /
-  `android.ts` / `ios.ts` for native selectors targeting the same logical page.
-
----
-
-## 2. Selector Contract: `~name` vs `#name`
-
-TestSpectra resolves selectors identically across every platform — a selector written once means
-the same thing everywhere. Each prefix maps to **exactly one** attribute; there is no silent
-cross-matching.
-
-| Selector           | Meaning              | Web                     | Android                          | iOS                      |
-| :----------------- | :------------------- | :---------------------- | :------------------------------- | :----------------------- |
-| `~name`            | **accessibility id** | `[aria-label="name"]`   | `content-desc`                   | accessibility identifier |
-| `#name`            | **native id**        | CSS `#name`             | `resource-id`                    | — (n/a)                  |
-| `//xpath`          | raw XPath            | delegated to the driver | delegated to the on-device agent | n/a                      |
-| `name` (no prefix) | lenient fallback     | n/a                     | native id, then accessibility id | n/a                      |
-
-### Which one to use
-
-- **Prefer `~name`** for anything a user can perceive — it's the portable, semantic, recommended
-  default across all platforms.
-- **Use `#name`** only when the element has a stable test/native id and no accessibility label
-  (React Native `testID`, Android `resource-id`, CSS `id`).
-- Set the _matching_ attribute on the app/page element so the selector actually resolves:
-
-```tsx
-// React Native — these resolve DIFFERENT selectors:
-<Pressable accessibilityLabel="submit-button" />   // → Spectra.get('~submit-button')
-<Pressable testID="submit-button" />                // → Spectra.get('#submit-button')
-```
-
-```html
-<!-- Web -->
-<button aria-label="submit-button">…</button>
-<!-- → Spectra.get('~submit-button') -->
-<button id="submit-button">…</button>
-<!-- → Spectra.get('#submit-button') -->
-```
-
-- When `testID` and `accessibilityLabel` are set to the same value, `~name` and `#name` are
-  interchangeable; they diverge the moment the two attributes differ.
-- Avoid the unprefixed lenient form (`name`) in new tests — it's Android-only leniency kept for
-  backwards compatibility, not part of the cross-platform contract. Always write an explicit `~`
-  or `#`.
-- Avoid raw `//xpath` unless there is genuinely no stable id/label to hook into — it's brittle and
-  bypasses the fast, cached full-hierarchy snapshot lookup that `~`/`#` selectors use on Android.
-
----
-
-## 3. Scoping a Lookup Instead of Writing a Compound Selector
-
-When the same selector repeats across rows (a list of cards, a table), **do not** reach for a
-compound CSS selector (`.card:nth-child(3) .buy-btn`) or an index baked into an xpath — those are
-brittle and don't have a cross-platform equivalent (Android has no CSS nth-child). Chain
-`.get(childSelector)` / `.getAll(childSelector)` off an already-resolved element instead; it
-scopes the lookup to that element's own subtree:
-
-```typescript
-class ProductsPage {
-  get cards() {
-    return Spectra.getAll('.product-card');
-  }
-  cardBuyButton(index: number) {
-    return this.cards.nth(index).get('.buy-btn');
-  }
-}
-```
-
-This is a Page Object concern, not a new selector prefix — `~`/`#`/xpath all still apply as the
-child selector, resolved within the parent's subtree instead of the whole document/screen. See the
-`matchers-and-assertions` skill for the full `.get()`/`.getAll()` chaining behavior.
-
----
-
-## 4. Never Use Raw `$` / `$$` / `browser` / `driver`
-
-TestSpectra encapsulates the entire runtime into a single global `Spectra` object. There is no raw
-WebdriverIO `$`, `$$`, `browser`, or `driver` in test-authoring code — always go through
-`Spectra.get()` / `Spectra.getAll()` for locators and `Spectra.*` / `Spectra.browser.*` for
-everything else (navigation, gestures, storage, network). See the `matchers-and-assertions` skill
-for the full command surface.
+---
+name: page-objects-and-selectors
+description: How to write a TestSpectra Page Object (Spectra.get / Spectra.getAll singleton pattern) and how the ~accessibility-id vs #native-id selector contract resolves identically across Web, Android, and iOS. Use whenever declaring element locators or a new Page Object.
+---
+
+# Skill: Page Objects & the Selector Contract
+
+Use this skill whenever you add a new Page Object, add a getter to an existing one, or need to
+pick a selector string.
+
+---
+
+## 1. Page Object Pattern
+
+A Page Object is a class with getter properties that return `Spectra.get(selector)` /
+`Spectra.getAll(selector)`, exported as a singleton default export, and consumed with **zero
+imports** anywhere else in the workspace (see the `workspace-structure` skill).
+
+```typescript
+// page-objects/MatchersPage/web.ts
+class MatchersPage {
+  get visibleElement() {
+    return Spectra.get('#demo-visible-el');
+  }
+  get hiddenElement() {
+    return Spectra.get('#demo-hidden-el');
+  }
+  get existingElement() {
+    return Spectra.get('#demo-existing-el');
+  }
+  get productCards() {
+    return Spectra.getAll('.demo-product-card');
+  } // collection
+
+  async open(section = '') {
+    await Spectra.navigate('/' + (section ? '#' + section : ''));
+  }
+}
+
+export default new MatchersPage();
+```
+
+Rules:
+
+- One getter per element/collection; name the getter for what the element _is_ (`submitButton`,
+  `statCards`), not for the selector string.
+- `Spectra.get(selector)` → single element; `Spectra.getAll(selector)` → collection (used with
+  collection matchers like `.shouldHaveLength(n)`).
+- Add reusable navigation/composite helpers as regular `async` methods on the same class (e.g.
+  `open()` above), not as standalone actions, when they are specific to that one page.
+- File suffix follows the platform-suffix rule: `web.ts` for CSS selectors, `mobile.ts` /
+  `android.ts` / `ios.ts` for native selectors targeting the same logical page.
+
+---
+
+## 2. Selector Contract: `~name` vs `#name`
+
+TestSpectra resolves selectors identically across every platform — a selector written once means
+the same thing everywhere. Each prefix maps to **exactly one** attribute; there is no silent
+cross-matching.
+
+| Selector           | Meaning              | Web                     | Android                          | iOS                      |
+| :----------------- | :------------------- | :---------------------- | :------------------------------- | :----------------------- |
+| `~name`            | **accessibility id** | `[aria-label="name"]`   | `content-desc`                   | accessibility identifier |
+| `#name`            | **native id**        | CSS `#name`             | `resource-id`                    | — (n/a)                  |
+| `//xpath`          | raw XPath            | delegated to the driver | delegated to the on-device agent | n/a                      |
+| `name` (no prefix) | lenient fallback     | n/a                     | native id, then accessibility id | n/a                      |
+
+### Which one to use
+
+- **Prefer `~name`** for anything a user can perceive — it's the portable, semantic, recommended
+  default across all platforms.
+- **Use `#name`** only when the element has a stable test/native id and no accessibility label
+  (React Native `testID`, Android `resource-id`, CSS `id`).
+- Set the _matching_ attribute on the app/page element so the selector actually resolves:
+
+```tsx
+// React Native — these resolve DIFFERENT selectors:
+<Pressable accessibilityLabel="submit-button" />   // → Spectra.get('~submit-button')
+<Pressable testID="submit-button" />                // → Spectra.get('#submit-button')
+```
+
+```html
+<!-- Web -->
+<button aria-label="submit-button">…</button>
+<!-- → Spectra.get('~submit-button') -->
+<button id="submit-button">…</button>
+<!-- → Spectra.get('#submit-button') -->
+```
+
+- When `testID` and `accessibilityLabel` are set to the same value, `~name` and `#name` are
+  interchangeable; they diverge the moment the two attributes differ.
+- Avoid the unprefixed lenient form (`name`) in new tests — it's Android-only leniency kept for
+  backwards compatibility, not part of the cross-platform contract. Always write an explicit `~`
+  or `#`.
+- Avoid raw `//xpath` unless there is genuinely no stable id/label to hook into — it's brittle and
+  bypasses the fast, cached full-hierarchy snapshot lookup that `~`/`#` selectors use on Android.
+
+---
+
+## 3. Scoping a Lookup Instead of Writing a Compound Selector
+
+When the same selector repeats across rows (a list of cards, a table), **do not** reach for a
+compound CSS selector (`.card:nth-child(3) .buy-btn`) or an index baked into an xpath — those are
+brittle and don't have a cross-platform equivalent (Android has no CSS nth-child). Chain
+`.get(childSelector)` / `.getAll(childSelector)` off an already-resolved element instead; it
+scopes the lookup to that element's own subtree:
+
+```typescript
+class ProductsPage {
+  get cards() {
+    return Spectra.getAll('.product-card');
+  }
+  cardBuyButton(index: number) {
+    return this.cards.nth(index).get('.buy-btn');
+  }
+}
+```
+
+This is a Page Object concern, not a new selector prefix — `~`/`#`/xpath all still apply as the
+child selector, resolved within the parent's subtree instead of the whole document/screen. See the
+`matchers-and-assertions` skill for the full `.get()`/`.getAll()` chaining behavior.
+
+---
+
+## 4. Never Use Raw `$` / `$$` / `browser` / `driver`
+
+TestSpectra encapsulates the entire runtime into a single global `Spectra` object. There is no raw
+WebdriverIO `$`, `$$`, `browser`, or `driver` in test-authoring code — always go through
+`Spectra.get()` / `Spectra.getAll()` for locators and `Spectra.*` / `Spectra.browser.*` for
+everything else (navigation, gestures, storage, network). See the `matchers-and-assertions` skill
+for the full command surface.