@testspectra/skills 1.1.0-rc.0

package/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/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.