@testspectra/skills 1.2.8 → 1.2.9

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

@@ -24,12 +24,49 @@ per action/assertion in `.testspectra/reports/`.
 | `await el.clear()`                   | `Clear text in {el}`                    |
 | `await el.select(option)`            | `Select option "{option}" in {el}`      |
 | `await el.hover()`                   | `Hover over {el}`                       |
+| `await el.focus()`                   | `Focus {el}`                            |
+| `await el.blur()`                    | `Blur {el}`                             |
+| `await el.click({ x, y })`           | `Click on element "{el}" at (x, y)`     |
 | `await source.dragDrop(dest)`        | `Drag {source} and drop onto {dest}`    |
 | `await el.scrollIntoView()`          | `Scroll {el} into view`                 |
 | `await el.longPress(durationMs)`     | `Long-press on {el} for {durationMs}ms` |
 | `await el.waitForElement(timeoutMs)` | `Wait for {el} to be displayed`         |
+| `await el.waitForElementRemoved(t?)` | `Wait for {el} to be removed`           |
+| `await el.waitForUndisplayed(o?)`    | `Wait for {el} to be hidden`            |
+| `await el.waitForClickable(o?)`      | `Wait for {el} to be clickable`         |
+| `await el.getBounds()`               | `Get bounds of {el}`                    |
 
 `type()` accepts an options object, e.g. `{ clearFirst: true }` to clear the field before typing.
+`click({ x, y })` clicks at coordinates relative to the element; `Spectra.clickAt(x, y)` /
+`Spectra.browser.clickAt(x, y)` clicks at absolute viewport coordinates.
+`getText()` returns authored text (`textContent`) — CSS `text-transform` never leaks into assertions.
+`getBounds()` returns `{ x, y, top, right, bottom, left, width, height }` (web
+`getBoundingClientRect`, Android node bounds).
+
+### 1b. DOM Traversal (cross-platform, no XPath)
+
+| TestSpectra syntax                | Meaning                                              |
+| :-------------------------------- | :--------------------------------------------------- |
+| `el.parent()`                     | Parent element in the DOM / a11y tree                |
+| `await el.closest(selector)`      | Closest matching ancestor, or `null` (like `closest`)|
+| `el.children(selector?)`          | Direct children as a collection (optional filter)    |
+| `el.siblings(selector?)`          | Same-parent siblings (excluding self) as collection  |
+| `el.next(selector?)`              | Next sibling, or first following sibling matching it |
+
+```typescript
+await Spectra.get('ul').children('li').shouldHaveLength(3);
+const card = await Spectra.get('#buy-button').closest('.product-card');
+```
+
+Collection index survives traversal: `getAll('.x').nth(1).parent()` resolves the second
+`.x`'s parent, not the first document match. No XPath here by design — XPath dialects differ
+per platform, traversal keeps one API.
+
+### 1c. State Queries (return values, not assertions)
+
+`await el.isClickable()` → `true` when visible + enabled + in viewport. Combines with
+`isVisible()` / `isExisting()` / `isEnabled()` for explicit branching; prefer
+`shouldBe*` matchers + `waitForClickable()` for plain waiting.
 
 ---
 
@@ -107,6 +144,8 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 | :------------- | :------------------------------------------------------------------------------------------------------------------------------- |
 | Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                                                     |
 | Element query  | `Spectra.get(selector)` / `Spectra.getAll(selector)` — chain `.get()`/`.getAll()` on the result to scope a lookup, see section 4 |
+| Focus          | `await Spectra.focus(target)` / `await Spectra.blur(target)`                                                                     |
+| Coordinate     | `await Spectra.clickAt(x, y)` — absolute viewport click                                                                          |
 | Window         | `await Spectra.setViewport(1920, 1080)`                                                                                          |
 | Timing         | `await Spectra.wait(1000)`                                                                                                       |
 | Keyboard       | `await Spectra.pressKey("Enter")`                                                                                                |
@@ -118,6 +157,7 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 
 | Syntax                                              | Purpose                         |
 | :-------------------------------------------------- | :------------------------------ |
+| `await Spectra.browser.clickAt(x, y)`                | Click at viewport coordinates   |
 | `await Spectra.browser.clearCookies()`              | Clear all cookies               |
 | `await Spectra.browser.clearLocalStorage()`         | Clear localStorage              |
 | `await Spectra.browser.shouldHaveUrl(url)`          | Assert exact URL                |

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

@@ -121,6 +121,32 @@ This is a Page Object concern, not a new selector prefix — `~`/`#`/xpath all s
 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.
 
+### Traversal instead of compound selectors
+
+For moving up/sideways in the tree, prefer traversal over xpath axes (xpath dialects differ per
+platform — DOM attrs on web vs `@text`/`@resource-id` on Android — so traversal is the one
+cross-platform API):
+
+```typescript
+class ProductCard {
+  buyButton() {
+    return Spectra.get('#buy-button');
+  }
+  card() {
+    return this.buyButton().parent(); // or await .closest('.product-card')
+  }
+  siblings() {
+    return Spectra.get('.step-1').next('.step-2');
+  }
+}
+```
+
+- `parent()` / `await closest(sel)` / `children(sel?)` / `siblings(sel?)` / `next(sel?)` work on
+  web (DOM) and Android (a11y-tree links) identically.
+- Index survives traversal: `cards.nth(1).parent()` resolves the second card's parent, never the
+  first document match. Unfiltered `parent()` chains stay document-wide — scope with
+  `closest(selector)` or a filter when several subtrees match.
+
 ---
 
 ## 4. Never Use Raw `$` / `$$` / `browser` / `driver`

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

@@ -152,6 +152,7 @@ export default defineConfig({
     normalResponseTime: '1000',
     monitoredDomains: [{ domain: 'api.example.com', enabled: true }],
     environmentVariables: { API_MODE: 'sandbox' },
+    plugins: ['@myorg/spectra-button-plugin'],
   },
 });
 ```
@@ -173,6 +174,9 @@ Numeric-looking fields (timeouts, ports, session counts) accept either a `number
   `.testspectra/types/env.d.ts`, autocompleted, zero-import — **prefer this over `process.env`**,
   which is untyped `string | undefined`) and a plain `process.env.KEY` string for code that must
   consume the untyped standard API.
+- **`plugins`**: module specifiers (package name or project-relative path) extending `Spectra`
+  with custom commands via `Spectra.registerCommand()`; installs are idempotent per specifier.
+  Run `spectra sync-types` to regenerate per-platform ambient declarations.
 
 ---
 

package/package.json

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

@@ -24,12 +24,49 @@ per action/assertion in `.testspectra/reports/`.
 | `await el.clear()`                   | `Clear text in {el}`                    |
 | `await el.select(option)`            | `Select option "{option}" in {el}`      |
 | `await el.hover()`                   | `Hover over {el}`                       |
+| `await el.focus()`                   | `Focus {el}`                            |
+| `await el.blur()`                    | `Blur {el}`                             |
+| `await el.click({ x, y })`           | `Click on element "{el}" at (x, y)`     |
 | `await source.dragDrop(dest)`        | `Drag {source} and drop onto {dest}`    |
 | `await el.scrollIntoView()`          | `Scroll {el} into view`                 |
 | `await el.longPress(durationMs)`     | `Long-press on {el} for {durationMs}ms` |
 | `await el.waitForElement(timeoutMs)` | `Wait for {el} to be displayed`         |
+| `await el.waitForElementRemoved(t?)` | `Wait for {el} to be removed`           |
+| `await el.waitForUndisplayed(o?)`    | `Wait for {el} to be hidden`            |
+| `await el.waitForClickable(o?)`      | `Wait for {el} to be clickable`         |
+| `await el.getBounds()`               | `Get bounds of {el}`                    |
 
 `type()` accepts an options object, e.g. `{ clearFirst: true }` to clear the field before typing.
+`click({ x, y })` clicks at coordinates relative to the element; `Spectra.clickAt(x, y)` /
+`Spectra.browser.clickAt(x, y)` clicks at absolute viewport coordinates.
+`getText()` returns authored text (`textContent`) — CSS `text-transform` never leaks into assertions.
+`getBounds()` returns `{ x, y, top, right, bottom, left, width, height }` (web
+`getBoundingClientRect`, Android node bounds).
+
+### 1b. DOM Traversal (cross-platform, no XPath)
+
+| TestSpectra syntax                | Meaning                                              |
+| :-------------------------------- | :--------------------------------------------------- |
+| `el.parent()`                     | Parent element in the DOM / a11y tree                |
+| `await el.closest(selector)`      | Closest matching ancestor, or `null` (like `closest`)|
+| `el.children(selector?)`          | Direct children as a collection (optional filter)    |
+| `el.siblings(selector?)`          | Same-parent siblings (excluding self) as collection  |
+| `el.next(selector?)`              | Next sibling, or first following sibling matching it |
+
+```typescript
+await Spectra.get('ul').children('li').shouldHaveLength(3);
+const card = await Spectra.get('#buy-button').closest('.product-card');
+```
+
+Collection index survives traversal: `getAll('.x').nth(1).parent()` resolves the second
+`.x`'s parent, not the first document match. No XPath here by design — XPath dialects differ
+per platform, traversal keeps one API.
+
+### 1c. State Queries (return values, not assertions)
+
+`await el.isClickable()` → `true` when visible + enabled + in viewport. Combines with
+`isVisible()` / `isExisting()` / `isEnabled()` for explicit branching; prefer
+`shouldBe*` matchers + `waitForClickable()` for plain waiting.
 
 ---
 
@@ -107,6 +144,8 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 | :------------- | :------------------------------------------------------------------------------------------------------------------------------- |
 | Navigation     | `await Spectra.navigate("/login")` / `.back()` / `.forward()` / `.refresh()`                                                     |
 | Element query  | `Spectra.get(selector)` / `Spectra.getAll(selector)` — chain `.get()`/`.getAll()` on the result to scope a lookup, see section 4 |
+| Focus          | `await Spectra.focus(target)` / `await Spectra.blur(target)`                                                                     |
+| Coordinate     | `await Spectra.clickAt(x, y)` — absolute viewport click                                                                          |
 | Window         | `await Spectra.setViewport(1920, 1080)`                                                                                          |
 | Timing         | `await Spectra.wait(1000)`                                                                                                       |
 | Keyboard       | `await Spectra.pressKey("Enter")`                                                                                                |
@@ -118,6 +157,7 @@ collection carry the scope forward too. No behavior difference on web vs. Androi
 
 | Syntax                                              | Purpose                         |
 | :-------------------------------------------------- | :------------------------------ |
+| `await Spectra.browser.clickAt(x, y)`                | Click at viewport coordinates   |
 | `await Spectra.browser.clearCookies()`              | Clear all cookies               |
 | `await Spectra.browser.clearLocalStorage()`         | Clear localStorage              |
 | `await Spectra.browser.shouldHaveUrl(url)`          | Assert exact URL                |

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

@@ -121,6 +121,32 @@ This is a Page Object concern, not a new selector prefix — `~`/`#`/xpath all s
 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.
 
+### Traversal instead of compound selectors
+
+For moving up/sideways in the tree, prefer traversal over xpath axes (xpath dialects differ per
+platform — DOM attrs on web vs `@text`/`@resource-id` on Android — so traversal is the one
+cross-platform API):
+
+```typescript
+class ProductCard {
+  buyButton() {
+    return Spectra.get('#buy-button');
+  }
+  card() {
+    return this.buyButton().parent(); // or await .closest('.product-card')
+  }
+  siblings() {
+    return Spectra.get('.step-1').next('.step-2');
+  }
+}
+```
+
+- `parent()` / `await closest(sel)` / `children(sel?)` / `siblings(sel?)` / `next(sel?)` work on
+  web (DOM) and Android (a11y-tree links) identically.
+- Index survives traversal: `cards.nth(1).parent()` resolves the second card's parent, never the
+  first document match. Unfiltered `parent()` chains stay document-wide — scope with
+  `closest(selector)` or a filter when several subtrees match.
+
 ---
 
 ## 4. Never Use Raw `$` / `$$` / `browser` / `driver`

package/skills/workspace-structure/SKILL.md

@@ -152,6 +152,7 @@ export default defineConfig({
     normalResponseTime: '1000',
     monitoredDomains: [{ domain: 'api.example.com', enabled: true }],
     environmentVariables: { API_MODE: 'sandbox' },
+    plugins: ['@myorg/spectra-button-plugin'],
   },
 });
 ```
@@ -173,6 +174,9 @@ Numeric-looking fields (timeouts, ports, session counts) accept either a `number
   `.testspectra/types/env.d.ts`, autocompleted, zero-import — **prefer this over `process.env`**,
   which is untyped `string | undefined`) and a plain `process.env.KEY` string for code that must
   consume the untyped standard API.
+- **`plugins`**: module specifiers (package name or project-relative path) extending `Spectra`
+  with custom commands via `Spectra.registerCommand()`; installs are idempotent per specifier.
+  Run `spectra sync-types` to regenerate per-platform ambient declarations.
 
 ---