@testspectra/skills 1.1.0-rc.0

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

@@ -0,0 +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`.

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

@@ -0,0 +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.

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

@@ -0,0 +1,181 @@
+---
+name: workspace-structure
+description: TestSpectra workspace layout, zero-import ambient type architecture, platform file suffixes (web/android/ios/mobile/common), spectra.config.ts, and the core spectra CLI commands. Use before scaffolding any new TestSpectra project or file so it lands in the right directory with the right suffix.
+---
+
+# Skill: TestSpectra Workspace Structure & Zero-Import Architecture
+
+Use this skill whenever you scaffold a new TestSpectra workspace, add a new file to an existing
+one, or need to decide where a Page Object / Step / Action / Hook / Fixture belongs.
+
+---
+
+## 1. Core Philosophy: Git-First, Spec-as-Code
+
+Every test case, shared step, Page Object, fixture, and config file is a plain TypeScript or
+Markdown file tracked in git — there is no proprietary binary project format. TestSpectra supports
+two workspace paradigms:
+
+1. **Default Project Mode** (`spectra init`, single-root repo) — one app, one `spectra.config.ts`.
+2. **Monorepo / Nx Project Mode** (`spectra init --template nx`) — multiple `packages/*` test
+   projects sharing a library under `shared/testing` (or a custom path), wired into
+   `pnpm-workspace.yaml`.
+
+Never guess which mode a repo uses — check for `nx.json` / `pnpm-workspace.yaml` with a
+`packages:` list first.
+
+---
+
+## 2. Default Workspace Directory Layout
+
+```
+my-test-project/
+├── .testspectra/                # Auto-managed. NEVER hand-edit these files.
+│   ├── tsconfig/                 # web.json, mobile.json, android.json, ios.json, common.json
+│   ├── types/                    # web.d.ts, mobile.d.ts, android.d.ts, ios.d.ts, common.d.ts,
+│   │                              # fixtures.d.ts — ambient globals (Spectra, Step, Fixture, POs)
+│   └── reports/                  # report.json, network-resources.json, last-run.json
+│
+├── specs/                        # Test suites & test cases (Spec-as-Code)
+│   └── <SuiteName>/
+│       ├── suite.md              # Suite metadata (id, name, executionOrder, parallel)
+│       ├── hooks/                 # Suite-level lifecycle hooks (before/beforeEach/afterEach/after)
+│       └── TC-<NNNN>-<slug>/     # One directory per test case
+│           ├── spec.md            # Frontmatter + "## Test Steps" with @step:<name> directives
+│           ├── web.test.ts        # and/or android.test.ts / ios.test.ts / mobile.test.ts / common.test.ts
+│
+├── page-objects/                 # Page Object Model singletons
+│   └── <PageName>/
+│       ├── web.ts
+│       └── mobile.ts             # (or android.ts / ios.ts)
+│
+├── support/
+│   ├── steps/                    # High-level reusable business workflows (Step.*)
+│   │   └── <stepName>/
+│   │       ├── step.md
+│   │       ├── web.step.ts
+│   │       └── mobile.step.ts
+│   └── actions/                  # Low-level technical utilities (Spectra.<action>())
+│       └── <actionName>/
+│           ├── web.action.ts
+│           └── mobile.action.ts
+│
+├── fixtures/                     # JSON/CSV test data, auto-typed under Fixture.*
+│   └── users.json
+│
+├── global-hooks/                 # Workspace-wide hooks, run once per Global Batch Run only
+│   ├── before/
+│   └── after/
+│
+├── spectra.config.ts             # Single source of truth for execution settings
+├── tsconfig.json                 # References ./.testspectra/tsconfig.json — do not add "include"
+└── package.json                  # Has "postinstall": "spectra sync-types"
+```
+
+For the Nx/monorepo variant, each `packages/<project>/` is its own self-contained workspace
+(`specs/`, `page-objects/`, `spectra.config.ts`, `package.json`), and a shared library
+(default `shared/testing/`) holds cross-project Page Objects/Steps/Actions/Fixtures. **Never** put
+a `specs/` directory or a `spec.md`/`suite.md` file inside the shared library — the linter rejects
+it (`testspectra/no-specs-in-shared-lib`).
+
+---
+
+## 3. Zero-Import Rule (Non-Negotiable)
+
+TestSpectra scripts **never** contain a manual `import` statement for framework entities. Page
+Objects, `Step.*`, `Fixture.*`, and the global `Spectra` object are all injected as ambient
+globals via `.testspectra/types/*.d.ts`, which the CLI regenerates automatically (sub-60ms) when
+you add/rename files under `page-objects/`, `support/`, or `fixtures/`.
+
+- ❌ `import LoginPage from '../../page-objects/LoginPage';`
+- ✅ Just reference `LoginPage` directly — it resolves globally.
+
+Adding an `import` in a `*.test.ts`, `*.step.ts`, `*.action.ts`, `*.hook.ts`, or Page Object file
+triggers linter rule `testspectra/no-manual-import` (error). If a file's types look stale after you
+add a new Page Object/Step/Fixture, run `spectra sync-types` rather than importing manually.
+
+---
+
+## 4. Platform File Suffixes
+
+| Suffix        | Target                      | Can access                                    |
+| :------------ | :-------------------------- | :-------------------------------------------- |
+| `*.web.*`     | Web (Chrome CDP)            | web + common                                  |
+| `*.android.*` | Android (native TCP driver) | android + mobile + common                     |
+| `*.ios.*`     | iOS (XCUITest)              | ios + mobile + common                         |
+| `*.mobile.*`  | Shared Android & iOS        | mobile + common only (no web, no android/ios) |
+| `*.common.*`  | Universal (web + mobile)    | common only (strictest isolation)             |
+
+This applies to test scripts (`web.test.ts`), Page Objects (`web.ts`), steps (`web.step.ts`),
+actions (`web.action.ts`), and hooks (`web.hook.ts`). Pick the narrowest suffix that fits — don't
+write a `mobile.test.ts` for something that is actually web-only.
+
+---
+
+## 5. `spectra.config.ts`
+
+```typescript
+import { defineConfig } from '@testspectra/cli';
+
+export default defineConfig({
+  webConfig: {
+    baseUrl: 'http://localhost:5173',
+    maxConcurrentSessions: '1',
+    headless: true,
+    implicitWait: '5000',
+    pageLoadTimeout: '30000',
+    scriptTimeout: '30000',
+    parallelizationMode: 'testcase', // "testcase" | "suite"
+  },
+  browsers: [{ id: 'chrome-desktop', type: 'chrome', mobileEmulation: false }],
+  androidConfig: {
+    driverServer: 'tcp://127.0.0.1:8200',
+    appPackage: 'dev.example.app',
+    appActivity: 'dev.example.app.MainActivity',
+    noReset: false,
+    implicitWait: '10000',
+    parallelizationMode: 'suite',
+    devices: [{ id: 'emulator-5554', name: 'Pixel 8a Emulator', version: '14.0', systemPort: 8200 }],
+  },
+  iosConfig: {
+    appiumServer: 'http://127.0.0.1:4723',
+    automationName: 'XCUITest',
+    bundleId: '',
+    autoAcceptAlerts: true,
+    noReset: false,
+    implicitWait: '10000',
+    parallelizationMode: 'suite',
+    devices: [
+      { id: 'iphone-15-pro', name: 'iPhone 15 Pro Simulator', version: '17.0', udid: 'auto', wdaLocalPort: 8100 },
+    ],
+  },
+  executionConfig: {
+    networkMonitoringEnabled: true,
+    fastResponseTime: '200',
+    normalResponseTime: '1000',
+    monitoredDomains: [],
+    environmentVariables: [],
+  },
+});
+```
+
+Numeric-looking fields (timeouts, ports, session counts) accept either a `number` or a numeric
+`string` — stay consistent with whatever the rest of the file already uses.
+
+---
+
+## 6. Core `spectra` CLI Commands
+
+| Command                                              | Purpose                                                                                                 |
+| :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
+| `spectra init [--template nx]`                       | Scaffold a new workspace                                                                                |
+| `spectra sync-types`                                 | Regenerate `.testspectra/types` and `.testspectra/tsconfig` (also runs on `postinstall` and file-watch) |
+| `spectra run [path] -t <web\|mobile\|android\|ios>`  | Execute tests                                                                                           |
+| `spectra lint [path] [--strict] [--json]`            | Validate `spec.md`/`suite.md` schema + code parity (see the `spec-and-suite-authoring` skill)           |
+| `spectra doctor`                                     | Preflight dependency/environment health check                                                           |
+| `spectra refactor step\|action\|fixture <old> <new>` | Atomically rename across folder, metadata, and all call sites                                           |
+| `spectra watch`                                      | Background file watcher driving `sync-types`                                                            |
+
+After scaffolding or renaming any file under `page-objects/`, `support/`, or `fixtures/`, assume
+the ambient types are stale until `sync-types` (or the watcher) has run — don't hand-write
+`.testspectra/types/*.d.ts` yourself.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@testspectra/skills",
+  "version": "1.1.0-rc.0",
+  "description": "Installer & manager for modular AI agent skills that standardize TestSpectra script authoring (specs, page objects, steps, actions, hooks, fixtures, matchers)",
+  "keywords": [
+    "agents",
+    "ai",
+    "claude-code",
+    "cli",
+    "cursor",
+    "kilo",
+    "opencode",
+    "skills",
+    "testspectra",
+    "spectra"
+  ],
+  "homepage": "https://github.com/TestSpectra/testspectra-source",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TestSpectra/testspectra-source.git",
+    "directory": "tools/skills"
+  },
+  "bin": {
+    "spectra-skills": "./bin/spectra-skills.js",
+    "testspectra-skills": "./bin/spectra-skills.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "skills",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/copy-skills.js",
+    "watch": "tsc -w",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@clack/prompts": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  },
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md"
+}

package/skills/fixtures-data/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: fixtures-data
+description: TestSpectra test data fixtures — JSON files under fixtures/, auto-typed globally under Fixture.* with zero imports, and how to reference/refactor them from test scripts, steps, and hooks. Use whenever a test needs static mock data (credentials, catalog items, payloads, locales).
+---
+
+# Skill: Fixture & Test Data Management
+
+Use this skill whenever a test case, shared step, or hook needs static data — user credentials,
+product catalogs, mock API payloads, localization strings.
+
+---
+
+## 1. Directory & Storage
+
+```
+workspace-root/
+└── fixtures/
+    ├── users.json             # User roles & credential sets
+    ├── products.json          # Catalog items & SKU metadata
+    ├── api-payloads.json      # Mock response payloads
+    └── locales.json           # Localization dictionaries
+```
+
+```json
+// fixtures/users.json
+{
+  "admin": {
+    "id": "usr-admin-01",
+    "name": "System Administrator",
+    "email": "admin@testspectra.dev",
+    "password": "Password123!",
+    "role": "admin"
+  },
+  "standardUser": {
+    "id": "usr-std-02",
+    "name": "Jane Doe",
+    "email": "jane.doe@testspectra.dev",
+    "password": "Password123!",
+    "role": "member"
+  }
+}
+```
+
+---
+
+## 2. Ambient Typing (Zero Import)
+
+The `TypeGenerator` watches `fixtures/` and emits `.testspectra/types/fixtures.d.ts` automatically
+whenever a fixture file is created/updated:
+
+```typescript
+declare global {
+  namespace Fixture {
+    const users: typeof import('../../fixtures/users.json');
+    const products: typeof import('../../fixtures/products.json');
+  }
+}
+```
+
+Never hand-write this file, and never `import` a fixture JSON file directly — always access it via
+the global `Fixture.<fileBaseName>` namespace, exactly like Page Objects and `Step.*`.
+
+---
+
+## 3. Usage
+
+### In test scripts
+
+```typescript
+it('should login with admin credentials from fixture', async () => {
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(Fixture.users.admin.email, { clearFirst: true });
+  await LoginPage.passwordInput.type(Fixture.users.admin.password);
+  await LoginPage.submitButton.click();
+
+  await DashboardPage.welcomeMsg.shouldContainText(Fixture.users.admin.name);
+});
+```
+
+### In shared steps
+
+```typescript
+// support/steps/loginUser/web.step.ts
+export default async function (userType: 'admin' | 'standardUser' = 'standardUser') {
+  const user = Fixture.users[userType];
+  await Spectra.navigate('/auth/login');
+  await LoginPage.emailInput.type(user.email, { clearFirst: true });
+  await LoginPage.passwordInput.type(user.password);
+  await LoginPage.submitButton.click();
+}
+```
+
+Fixtures are freely usable inside hooks too (e.g. `global-hooks/before` seeding a DB via `fetch`
+with `Fixture.apiPayloads.seedUser`).
+
+---
+
+## 4. Renaming a Fixture
+
+Never rename a fixture file by hand. Use:
+
+```
+spectra refactor fixture users accounts
+```
+
+This renames `fixtures/users.json` → `fixtures/accounts.json`, rewrites every `Fixture.users`
+reference across `specs/**/*.test.ts`, `support/steps/**/*.step.ts`, and `hooks/**` to
+`Fixture.accounts`, and regenerates `.testspectra/types/fixtures.d.ts` immediately with 0
+TypeScript errors.