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

package/skills/shared-steps-and-actions/SKILL.md

@@ -1,184 +1,184 @@
----
-name: shared-steps-and-actions
-description: The difference between TestSpectra Shared Steps (Step.*, high-level business workflows, documented in spec.md via @step) and Spectra Actions (support/actions, low-level technical utilities) — directory layout, the mandatory anonymous async default export convention, and ambient type generation. Use whenever extracting reusable logic out of a test script.
----
-
-# Skill: Shared Steps vs. Custom Actions
-
-Use this skill when you're about to extract repeated logic (e.g. login, checkout) out of test
-scripts, or when deciding whether new reusable logic belongs under `support/steps/` or
-`support/actions/`.
-
----
-
-## 1. Which One Do I Need?
-
-| Attribute         | Shared Steps (`Step.*`)                        | Custom Actions (`Spectra.*` / on-element helpers)                             |
-| :---------------- | :--------------------------------------------- | :---------------------------------------------------------------------------- |
-| Abstraction level | High-level business workflow (login, checkout) | Low-level technical utility                                                   |
-| Directory         | `support/steps/<stepName>/`                    | `support/actions/<actionName>/`                                               |
-| Spec mapping      | Documented as `@step:<name>` in `spec.md`      | Just called inline, not listed in spec steps                                  |
-| Metadata file     | `step.md` (YAML frontmatter + description)     | None — implementation file only                                               |
-| Files             | `step.md` + `web.step.ts` [+ `mobile.step.ts`] | `web.action.ts` [+ `mobile.action.ts`]                                        |
-| Invocation        | `await Step.loginAsAdmin(params)`              | Called as a helper bound to an element/page, e.g. inside a Page Object method |
-
-Rule of thumb: if it's a multi-step _business_ flow a human would describe in one sentence
-("log in as admin"), it's a **Step**. If it's a small technical helper reused across Page Objects
-(a resilient click retry, filling a pair of fields), it's an **Action**.
-
----
-
-## 2. Directory Layout
-
-```
-support/
-├── steps/
-│   └── loginAsAdmin/
-│       ├── step.md            # Metadata, docs, parameter types
-│       ├── web.step.ts
-│       └── mobile.step.ts     # optional
-└── actions/
-    └── fillCredentials/
-        ├── web.action.ts
-        └── mobile.action.ts
-```
-
-Both use **camelCase** directory/function names (`loginAsAdmin`, `fillCredentials`,
-`applyDiscount`, `verifyOtp`) — never kebab-case or snake_case.
-
----
-
-## 3. `step.md` Metadata
-
-```markdown
----
-id: step-login-as-admin
-name: loginAsAdmin
-description: Authenticates as an administrator and asserts landing dashboard
-platform:
-  - web
-  - mobile
-tags:
-  - auth
-  - admin
-parameters:
-  - name: email
-    type: string
-    required: false
-    description: Admin email address (defaults to Fixture.users.admin.email)
-  - name: password
-    type: string
-    required: false
-    description: Admin password (defaults to Fixture.users.admin.password)
----
-
-# Login as Admin Step
-
-## Purpose
-
-Provides a standard, hardened administrative login sequence for web and mobile platforms.
-
-## Prerequisites
-
-- User fixture file exists at `fixtures/users.json`.
-- Browser is navigated to the base URL or login route.
-```
-
----
-
-## 4. Implementation: Anonymous Async Default Export (Mandatory)
-
-Every `*.step.ts` and `*.action.ts` file exports **one anonymous async function as its default
-export** — no named exports, no `test()`/`it()` blocks. This is enforced by the linter
-(`testspectra/require-anonymous-default-export`).
-
-```typescript
-// support/steps/loginAsAdmin/web.step.ts
-export default async function (params?: { email?: string; password?: string }) {
-  const email = params?.email ?? Fixture.users.admin.email;
-  const password = params?.password ?? Fixture.users.admin.password;
-
-  await Spectra.navigate('/auth/login');
-  await LoginPage.emailInput.type(email, { clearFirst: true });
-  await LoginPage.passwordInput.type(password);
-  await LoginPage.submitButton.click();
-
-  await DashboardPage.header.shouldBeVisible();
-}
-```
-
-Custom Actions follow the same shape and are commonly written with a `this` receiver so they can
-be attached/bound as element/page helpers:
-
-```typescript
-// support/actions/fillCredentials/web.action.ts
-export default async function (this: any, email: string, token: string) {
-  await this.get('#demo-email-input-pg').type(email);
-  await this.get('#demo-token-input-pg').type(token);
-}
-```
-
-```typescript
-// support/actions/fillCredentials/mobile.action.ts
-export default async function (this: any, email: string, token: string) {
-  await this.get('~pg-email-input').type(email);
-  await this.get('~pg-token-input').type(token);
-}
-```
-
-Zero-import applies here too: never manually `import` a Page Object, `Fixture`, or `Spectra` — see
-the `workspace-structure` skill.
-
----
-
-## 5. Type Generation & Invocation
-
-The `TypeGenerator` scans `support/steps/` and emits the `Step` ambient namespace automatically:
-
-```typescript
-declare global {
-  namespace Step {
-    function loginAsAdmin(params?: { email?: string; password?: string }): Promise<void>;
-  }
-}
-```
-
-### In `spec.md` (documents the step as part of the human-readable flow):
-
-```markdown
-## Test Steps
-
-1. @step:loginAsAdmin
-2. Navigate to user settings page
-3. Update profile avatar
-```
-
-### In `web.test.ts` (invokes it with zero manual imports):
-
-```typescript
-it('should update admin profile avatar', async () => {
-  await Step.loginAsAdmin();
-
-  await SettingsPage.openProfile();
-  await SettingsPage.avatarInput.type('avatar.png');
-  await SettingsPage.successToast.shouldBeVisible();
-});
-```
-
-Every `@step:<name>` in `spec.md` must have a matching `Step.<name>()` call in the paired test
-script, or `spectra lint` reports `testspectra/missing-step-call`. See the
-`spec-and-suite-authoring` skill for the full linter rule matrix.
-
----
-
-## 6. Renaming a Step or Action
-
-Never rename a step/action folder by hand. Use:
-
-```
-spectra refactor step loginAsAdmin authenticateAdmin
-```
-
-This atomically: renames `support/steps/loginAsAdmin/` → `support/steps/authenticateAdmin/`,
-updates `name:` in `step.md`, rewrites every `@step:loginAsAdmin` in every `spec.md`, rewrites
-every `Step.loginAsAdmin()` call site, and regenerates `.testspectra/types/steps.d.ts`.
+---
+name: shared-steps-and-actions
+description: The difference between TestSpectra Shared Steps (Step.*, high-level business workflows, documented in spec.md via @step) and Spectra Actions (support/actions, low-level technical utilities) — directory layout, the mandatory anonymous async default export convention, and ambient type generation. Use whenever extracting reusable logic out of a test script.
+---
+
+# Skill: Shared Steps vs. Custom Actions
+
+Use this skill when you're about to extract repeated logic (e.g. login, checkout) out of test
+scripts, or when deciding whether new reusable logic belongs under `support/steps/` or
+`support/actions/`.
+
+---
+
+## 1. Which One Do I Need?
+
+| Attribute         | Shared Steps (`Step.*`)                        | Custom Actions (`Spectra.*` / on-element helpers)                             |
+| :---------------- | :--------------------------------------------- | :---------------------------------------------------------------------------- |
+| Abstraction level | High-level business workflow (login, checkout) | Low-level technical utility                                                   |
+| Directory         | `support/steps/<stepName>/`                    | `support/actions/<actionName>/`                                               |
+| Spec mapping      | Documented as `@step:<name>` in `spec.md`      | Just called inline, not listed in spec steps                                  |
+| Metadata file     | `step.md` (YAML frontmatter + description)     | None — implementation file only                                               |
+| Files             | `step.md` + `web.step.ts` [+ `mobile.step.ts`] | `web.action.ts` [+ `mobile.action.ts`]                                        |
+| Invocation        | `await Step.loginAsAdmin(params)`              | Called as a helper bound to an element/page, e.g. inside a Page Object method |
+
+Rule of thumb: if it's a multi-step _business_ flow a human would describe in one sentence
+("log in as admin"), it's a **Step**. If it's a small technical helper reused across Page Objects
+(a resilient click retry, filling a pair of fields), it's an **Action**.
+
+---
+
+## 2. Directory Layout
+
+```
+support/
+├── steps/
+│   └── loginAsAdmin/
+│       ├── step.md            # Metadata, docs, parameter types
+│       ├── web.step.ts
+│       └── mobile.step.ts     # optional
+└── actions/
+    └── fillCredentials/
+        ├── web.action.ts
+        └── mobile.action.ts
+```
+
+Both use **camelCase** directory/function names (`loginAsAdmin`, `fillCredentials`,
+`applyDiscount`, `verifyOtp`) — never kebab-case or snake_case.
+
+---
+
+## 3. `step.md` Metadata
+
+```markdown
+---
+id: step-login-as-admin
+name: loginAsAdmin
+description: Authenticates as an administrator and asserts landing dashboard
+platform:
+  - web
+  - mobile
+tags:
+  - auth
+  - admin
+parameters:
+  - name: email
+    type: string
+    required: false
+    description: Admin email address (defaults to Fixture.users.admin.email)
+  - name: password
+    type: string
+    required: false
+    description: Admin password (defaults to Fixture.users.admin.password)
+---
+
+# Login as Admin Step
+
+## Purpose
+
+Provides a standard, hardened administrative login sequence for web and mobile platforms.
+
+## Prerequisites
+
+- User fixture file exists at `fixtures/users.json`.
+- Browser is navigated to the base URL or login route.
+```
+
+---
+
+## 4. Implementation: Anonymous Async Default Export (Mandatory)
+
+Every `*.step.ts` and `*.action.ts` file exports **one anonymous async function as its default
+export** — no named exports, no `test()`/`it()` blocks. This is enforced by the linter
+(`testspectra/require-anonymous-default-export`).
+
+```typescript
+// support/steps/loginAsAdmin/web.step.ts
+export default async function (params?: { email?: string; password?: string }) {
+  const email = params?.email ?? Fixture.users.admin.email;
+  const password = params?.password ?? Fixture.users.admin.password;
+
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(email, { clearFirst: true });
+  await LoginPage.passwordInput.type(password);
+  await LoginPage.submitButton.click();
+
+  await DashboardPage.header.shouldBeVisible();
+}
+```
+
+Custom Actions follow the same shape and are commonly written with a `this` receiver so they can
+be attached/bound as element/page helpers:
+
+```typescript
+// support/actions/fillCredentials/web.action.ts
+export default async function (this: any, email: string, token: string) {
+  await this.get('#demo-email-input-pg').type(email);
+  await this.get('#demo-token-input-pg').type(token);
+}
+```
+
+```typescript
+// support/actions/fillCredentials/mobile.action.ts
+export default async function (this: any, email: string, token: string) {
+  await this.get('~pg-email-input').type(email);
+  await this.get('~pg-token-input').type(token);
+}
+```
+
+Zero-import applies here too: never manually `import` a Page Object, `Fixture`, or `Spectra` — see
+the `workspace-structure` skill.
+
+---
+
+## 5. Type Generation & Invocation
+
+The `TypeGenerator` scans `support/steps/` and emits the `Step` ambient namespace automatically:
+
+```typescript
+declare global {
+  namespace Step {
+    function loginAsAdmin(params?: { email?: string; password?: string }): Promise<void>;
+  }
+}
+```
+
+### In `spec.md` (documents the step as part of the human-readable flow):
+
+```markdown
+## Test Steps
+
+1. @step:loginAsAdmin
+2. Navigate to user settings page
+3. Update profile avatar
+```
+
+### In `web.test.ts` (invokes it with zero manual imports):
+
+```typescript
+it('should update admin profile avatar', async () => {
+  await Step.loginAsAdmin();
+
+  await SettingsPage.openProfile();
+  await SettingsPage.avatarInput.type('avatar.png');
+  await SettingsPage.successToast.shouldBeVisible();
+});
+```
+
+Every `@step:<name>` in `spec.md` must have a matching `Step.<name>()` call in the paired test
+script, or `spectra lint` reports `testspectra/missing-step-call`. See the
+`spec-and-suite-authoring` skill for the full linter rule matrix.
+
+---
+
+## 6. Renaming a Step or Action
+
+Never rename a step/action folder by hand. Use:
+
+```
+spectra refactor step loginAsAdmin authenticateAdmin
+```
+
+This atomically: renames `support/steps/loginAsAdmin/` → `support/steps/authenticateAdmin/`,
+updates `name:` in `step.md`, rewrites every `@step:loginAsAdmin` in every `spec.md`, rewrites
+every `Step.loginAsAdmin()` call site, and regenerates `.testspectra/types/steps.d.ts`.

package/skills/spec-and-suite-authoring/SKILL.md

@@ -1,132 +1,132 @@
----
-name: spec-and-suite-authoring
-description: How to write suite.md, spec.md, and the paired *.test.ts execution script for a TestSpectra test case — frontmatter schema, the @step directive convention, and every spec-schema-linter rule that must pass (single it(), no describe/test, zero-import, title parity). Use whenever creating or editing a test case.
----
-
-# Skill: Spec & Suite Authoring (`spec.md`, `suite.md`, `*.test.ts`)
-
-Use this skill whenever you create a new test case, add a new suite, or edit an existing
-`spec.md` / `*.test.ts` pair. TestSpectra treats the Markdown spec as the human-readable source of
-truth and the TypeScript file as its execution — the CLI linter (`spectra lint`) enforces that the
-two never drift apart.
-
----
-
-## 1. Directory Convention
-
-```
-specs/<SuiteName>/suite.md
-specs/<SuiteName>/hooks/{before,beforeEach,afterEach,after}/web.hook.ts
-specs/<SuiteName>/TC-<NNNN>-<kebab-slug>/spec.md
-specs/<SuiteName>/TC-<NNNN>-<kebab-slug>/web.test.ts   # + android/ios/mobile/common variants
-```
-
-`SuiteName` is a directory (no `describe()` block ever exists in code — the suite boundary is
-purely the folder). The test case id (`TC-0001-valid-login`) is both the directory name and the
-`id` in `spec.md`'s frontmatter, and must be unique across the entire workspace
-(`testspectra/duplicate-spec-id`).
-
----
-
-## 2. `suite.md` Frontmatter
-
-```markdown
----
-name: Untitled Suite
-id: suite-element-matchers
-description: Element visibility, existence, form states and attributes
-executionOrder: 1.0
-parallel: true
----
-
-# Suite: ElementMatchers
-```
-
----
-
-## 3. `spec.md` Frontmatter & Body
-
-```markdown
----
-id: TC-0003-visibility-and-dom
-title: Verify element visibility and existence matchers
-priority: High
-caseType: Positive
-status: ready-for-automation
-coverage:
-  web: automated
-  mobile: automated
----
-
-# Verify element visibility and existence matchers
-
-## Test Steps
-
-1. Open visibility section in matchers page
-2. Assert visible element has be.visible state
-3. Assert existing element exists in DOM
-```
-
-Required frontmatter: `id`, `title`, `priority`, `caseType`, `status` — missing any of these, or
-missing the `# <Title>` / `## Test Steps` headings, triggers `testspectra/missing-frontmatter`.
-Invalid enum values (an unrecognized `priority`, `caseType`, or `status`) trigger
-`testspectra/invalid-frontmatter-enum`.
-
-If the test case invokes a shared step (see the `shared-steps-and-actions` skill), reference it in
-the `## Test Steps` list as `@step:<stepName>` — the linter cross-checks this against
-`Step.<stepName>()` calls in the paired `*.test.ts`.
-
----
-
-## 4. The Paired Test Script (`web.test.ts`)
-
-```typescript
-it('Verify element visibility and existence matchers', async () => {
-  await MatchersPage.open('visibility');
-
-  await MatchersPage.visibleElement.shouldBeVisible();
-  await MatchersPage.hiddenElement.shouldNotBeVisible();
-
-  await MatchersPage.existingElement.shouldExist();
-  await Spectra.get('#demo-non-existent-el').shouldNotExist();
-});
-```
-
-### Hard rules (each is a `spectra lint` error unless noted):
-
-1. **Exactly one `it(...)` block, nothing else at the top level.** Zero or multiple `it()` blocks
-   → `testspectra/single-it-required`.
-2. **Never `test(...)`.** Only `it(...)` is allowed → `testspectra/no-test-block`.
-3. **Never `describe(...)`.** Suite grouping is the directory, not code →
-   `testspectra/no-describe-block`.
-4. **Zero manual `import`s.** See the `workspace-structure` skill →
-   `testspectra/no-manual-import`.
-5. **`it()`'s title should read the same as `spec.md`'s `title`** (case-insensitive semantic
-   match). A mismatch is a warning, not an error → `testspectra/title-mismatch`.
-6. **Every `@step:<name>` in `spec.md` must have a matching `Step.<name>()` call** in the test
-   script → `testspectra/missing-step-call` (error) if absent, and conversely a `Step.<name>()`
-   call not documented with `@step:<name>` in `spec.md` is
-   `testspectra/undocumented-step` (warning).
-
-### Platform variants
-
-A test case directory may contain any combination of `web.test.ts`, `android.test.ts`,
-`ios.test.ts`, `mobile.test.ts`, `common.test.ts` — each is linted and can be run independently.
-Reuse a shared step for the parts of the flow that are identical across platforms rather than
-duplicating the `it()` body per platform.
-
----
-
-## 5. Running the Linter
-
-- `spectra lint` — scan the whole workspace, human-readable output.
-- `spectra lint --strict` — treat warnings as errors, exit code `1` on any diagnostic (use this in
-  CI).
-- `spectra lint --json` — machine-readable diagnostics (what an AI agent should parse to
-  self-correct after generating a spec).
-- `spectra lint <path>` — scan a single suite or test case folder.
-
-Exit codes: `0` valid, `1` violations found, `2` fatal (malformed YAML/JSON).
-
-After authoring or editing a `spec.md`/`*.test.ts` pair, run `spectra lint <path-to-that-case>`
-before considering the task done.
+---
+name: spec-and-suite-authoring
+description: How to write suite.md, spec.md, and the paired *.test.ts execution script for a TestSpectra test case — frontmatter schema, the @step directive convention, and every spec-schema-linter rule that must pass (single it(), no describe/test, zero-import, title parity). Use whenever creating or editing a test case.
+---
+
+# Skill: Spec & Suite Authoring (`spec.md`, `suite.md`, `*.test.ts`)
+
+Use this skill whenever you create a new test case, add a new suite, or edit an existing
+`spec.md` / `*.test.ts` pair. TestSpectra treats the Markdown spec as the human-readable source of
+truth and the TypeScript file as its execution — the CLI linter (`spectra lint`) enforces that the
+two never drift apart.
+
+---
+
+## 1. Directory Convention
+
+```
+specs/<SuiteName>/suite.md
+specs/<SuiteName>/hooks/{before,beforeEach,afterEach,after}/web.hook.ts
+specs/<SuiteName>/TC-<NNNN>-<kebab-slug>/spec.md
+specs/<SuiteName>/TC-<NNNN>-<kebab-slug>/web.test.ts   # + android/ios/mobile/common variants
+```
+
+`SuiteName` is a directory (no `describe()` block ever exists in code — the suite boundary is
+purely the folder). The test case id (`TC-0001-valid-login`) is both the directory name and the
+`id` in `spec.md`'s frontmatter, and must be unique across the entire workspace
+(`testspectra/duplicate-spec-id`).
+
+---
+
+## 2. `suite.md` Frontmatter
+
+```markdown
+---
+name: Untitled Suite
+id: suite-element-matchers
+description: Element visibility, existence, form states and attributes
+executionOrder: 1.0
+parallel: true
+---
+
+# Suite: ElementMatchers
+```
+
+---
+
+## 3. `spec.md` Frontmatter & Body
+
+```markdown
+---
+id: TC-0003-visibility-and-dom
+title: Verify element visibility and existence matchers
+priority: High
+caseType: Positive
+status: ready-for-automation
+coverage:
+  web: automated
+  mobile: automated
+---
+
+# Verify element visibility and existence matchers
+
+## Test Steps
+
+1. Open visibility section in matchers page
+2. Assert visible element has be.visible state
+3. Assert existing element exists in DOM
+```
+
+Required frontmatter: `id`, `title`, `priority`, `caseType`, `status` — missing any of these, or
+missing the `# <Title>` / `## Test Steps` headings, triggers `testspectra/missing-frontmatter`.
+Invalid enum values (an unrecognized `priority`, `caseType`, or `status`) trigger
+`testspectra/invalid-frontmatter-enum`.
+
+If the test case invokes a shared step (see the `shared-steps-and-actions` skill), reference it in
+the `## Test Steps` list as `@step:<stepName>` — the linter cross-checks this against
+`Step.<stepName>()` calls in the paired `*.test.ts`.
+
+---
+
+## 4. The Paired Test Script (`web.test.ts`)
+
+```typescript
+it('Verify element visibility and existence matchers', async () => {
+  await MatchersPage.open('visibility');
+
+  await MatchersPage.visibleElement.shouldBeVisible();
+  await MatchersPage.hiddenElement.shouldNotBeVisible();
+
+  await MatchersPage.existingElement.shouldExist();
+  await Spectra.get('#demo-non-existent-el').shouldNotExist();
+});
+```
+
+### Hard rules (each is a `spectra lint` error unless noted):
+
+1. **Exactly one `it(...)` block, nothing else at the top level.** Zero or multiple `it()` blocks
+   → `testspectra/single-it-required`.
+2. **Never `test(...)`.** Only `it(...)` is allowed → `testspectra/no-test-block`.
+3. **Never `describe(...)`.** Suite grouping is the directory, not code →
+   `testspectra/no-describe-block`.
+4. **Zero manual `import`s.** See the `workspace-structure` skill →
+   `testspectra/no-manual-import`.
+5. **`it()`'s title should read the same as `spec.md`'s `title`** (case-insensitive semantic
+   match). A mismatch is a warning, not an error → `testspectra/title-mismatch`.
+6. **Every `@step:<name>` in `spec.md` must have a matching `Step.<name>()` call** in the test
+   script → `testspectra/missing-step-call` (error) if absent, and conversely a `Step.<name>()`
+   call not documented with `@step:<name>` in `spec.md` is
+   `testspectra/undocumented-step` (warning).
+
+### Platform variants
+
+A test case directory may contain any combination of `web.test.ts`, `android.test.ts`,
+`ios.test.ts`, `mobile.test.ts`, `common.test.ts` — each is linted and can be run independently.
+Reuse a shared step for the parts of the flow that are identical across platforms rather than
+duplicating the `it()` body per platform.
+
+---
+
+## 5. Running the Linter
+
+- `spectra lint` — scan the whole workspace, human-readable output.
+- `spectra lint --strict` — treat warnings as errors, exit code `1` on any diagnostic (use this in
+  CI).
+- `spectra lint --json` — machine-readable diagnostics (what an AI agent should parse to
+  self-correct after generating a spec).
+- `spectra lint <path>` — scan a single suite or test case folder.
+
+Exit codes: `0` valid, `1` violations found, `2` fatal (malformed YAML/JSON).
+
+After authoring or editing a `spec.md`/`*.test.ts` pair, run `spectra lint <path-to-that-case>`
+before considering the task done.