@testspectra/cli 1.0.5 → 1.0.7

package/README.md

@@ -35,13 +35,67 @@ The **TestSpectra CLI** (`spectra` / `testspectra`) is the command-line orchestr
 
 ### A. Zero-Import Multi-Platform Authoring
 TestSpectra allows developers to write clean, boilerplate-free test specs, steps, actions, and page objects without manual `import` statements for globals or framework entities:
-- **Page Objects**: `LoginPage.login(...)` resolves automatically based on target platform.
-- **Actions**: `Spectra.verifyOtp(...)` provides typed action access.
+- **Page Objects**: `LoginPage.login(...)` and getters `LoginPage.flashAlert` resolve automatically based on target platform.
+- **Actions (`Spectra.*`)**: Built-in 16 atomic actions (`Spectra.navigate`, `Spectra.click`, `Spectra.type`, `Spectra.select`, `Spectra.scroll`, `Spectra.swipe`, `Spectra.wait`, etc.) matching TestSpectra database schema, merged seamlessly with user-defined custom actions (`Spectra.verifyOtp`).
+- **Direct Callable Assertions**: Instant, auto-completed assertion methods available directly on `WebdriverIO.Element`, `ChainablePromiseElement`, and `browser` (`shouldBeVisible()`, `shouldContainText()`, `shouldHaveValue()`, `shouldHaveUrl()`, etc.).
 - **Steps**: `Step.loginUser(...)` exposes shared business step flows.
 - **Fixtures**: `Fixture.userData` provides typed, platform-agnostic test fixture access.
 - **WebdriverIO Globals**: `$`, `$$`, `browser`, `expect` are available globally across all platforms.
 
-### B. Platform Hierarchy & Resolution
+### B. Built-in Regular Actions & Direct Callable Assertions
+
+TestSpectra provides a bundled, 100% database-schema-compatible library of built-in atomic actions and direct element assertions:
+
+#### 1. Direct Callable Element Assertions (`should*`)
+All Page Object elements and locators support direct callable assertions without extra nesting:
+```typescript
+it("should authenticate user using Page Objects and assertions", async () => {
+  // Navigation & high-level business flows
+  await LoginPage.open();
+  await Step.loginUser("tomsmith", "SuperSecretPassword!");
+
+  // Direct assertions on Page Object elements
+  await LoginPage.flashAlert.shouldBeVisible();
+  await LoginPage.flashAlert.shouldContainText("You logged into a secure area!");
+  await LoginPage.usernameInput.shouldHaveValue("tomsmith");
+});
+```
+
+#### Available Assertion Methods:
+| Kategori | Method Callable |
+| :--- | :--- |
+| **Visibility** | `await el.shouldBeVisible()` / `await el.shouldNotBeVisible()` |
+| **DOM Existence** | `await el.shouldExist()` / `await el.shouldNotExist()` |
+| **Element State** | `await el.shouldBeEnabled()` / `await el.shouldBeDisabled()` / `await el.shouldBeSelected()` / `await el.shouldBeChecked()` |
+| **Text Matching** | `await el.shouldHaveText(expected)` / `await el.shouldContainText(expected)` |
+| **Input Value** | `await el.shouldHaveValue(expected)` / `await el.shouldContainValue(expected)` |
+| **CSS Class** | `await el.shouldHaveClass(className)` |
+| **Attribute** | `await el.shouldHaveAttribute(name, val?)` |
+| **Browser URL / Title**| `await browser.shouldHaveUrl(url)` / `await browser.shouldHaveTitle(title)` |
+
+#### 2. Built-in Atomic Actions (`Spectra.*`)
+Available inside Page Objects, Actions, and Steps for raw element manipulation:
+```typescript
+// Navigation
+await Spectra.navigate("https://example.com/login");
+await Spectra.back();
+await Spectra.refresh();
+
+// Interactions with Page Object getters or locators
+await Spectra.type(this.usernameInput, "tomsmith");
+await Spectra.click(this.submitButton);
+await Spectra.select(this.countryDropdown, "ID");
+await Spectra.clear(this.searchField);
+await Spectra.pressKey("Enter");
+
+// Gestures & Timing
+await Spectra.scroll({ direction: "down", pixels: 300 });
+await Spectra.swipe({ direction: "up", distance: 500 });
+await Spectra.wait(1000);
+await Spectra.waitForElement(this.flashAlert, 5000);
+```
+
+### C. Platform Hierarchy & Resolution
 Entities are structured with hierarchical platform stems:
 ```
 page-objects/
@@ -63,7 +117,7 @@ Resolution order:
 - **`mobile`**: `mobile` → `common`
 - **`common`**: `common`
 
-### C. Solution-Style TypeScript Configuration & Language Service Plugin
+### D. Solution-Style TypeScript Configuration & Language Service Plugin
 To avoid ambient type clashes between platforms (such as different method signatures across Web and Mobile Page Objects), TestSpectra uses standard TypeScript **Project References**:
 - **`tsconfig.json`**: Root project reference orchestrator with `@testspectra/cli` plugin registered.
 - **`tsconfig.web.json`**: Scoped exclusively to Web files and `.testspectra/types/web.d.ts`.
@@ -81,7 +135,7 @@ Project verification is executed with standard `tsc`:
 tsc -b
 ```
 
-### D. Typed Configuration with `defineConfig`
+### E. Typed Configuration with `defineConfig`
 Configuration is strongly typed with full JSDoc documentation via `spectra.config.ts`:
 ```typescript
 import { defineConfig } from "@testspectra/cli";

package/dist/commands/init.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import path from "path";
+import { fileURLToPath } from "url";
 import { ConfigLoader } from "../config/loader.js";
 import { TypeGenerator } from "../types/generator.js";
 export async function initCommand(options) {
@@ -92,6 +93,37 @@ export default defineConfig({
     console.log(`\x1b[32m[TestSpectra]\x1b[0m Initialized spectra.config.ts with defineConfig`);
     // 3. Create or update package.json with npm scripts & devDependencies
     const packageJsonPath = path.join(cwd, "package.json");
+    // Dynamically resolve CLI version
+    let cliVersion = "^1.0.6";
+    try {
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const cliPackageJsonPath = path.resolve(__dirname, "../../package.json");
+        if (fs.existsSync(cliPackageJsonPath)) {
+            const cliPkg = JSON.parse(fs.readFileSync(cliPackageJsonPath, "utf-8"));
+            if (cliPkg.version) {
+                cliVersion = `^${cliPkg.version}`;
+            }
+        }
+    }
+    catch { }
+    // Check if cwd is inside the testspectra monorepo with a pnpm-workspace.yaml
+    let isInternalWorkspace = false;
+    let cur = cwd;
+    while (cur !== path.dirname(cur)) {
+        if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml"))) {
+            try {
+                const wsContent = fs.readFileSync(path.join(cur, "pnpm-workspace.yaml"), "utf-8");
+                if (wsContent.includes("cli")) {
+                    isInternalWorkspace = true;
+                    break;
+                }
+            }
+            catch { }
+        }
+        cur = path.dirname(cur);
+    }
+    const cliDepVersion = isInternalWorkspace ? "workspace:*" : cliVersion;
     let pkg = {
         name: path.basename(cwd),
         version: "1.0.0",
@@ -102,7 +134,7 @@ export default defineConfig({
             "type-check": "tsc -b",
         },
         devDependencies: {
-            "@testspectra/cli": "workspace:*",
+            "@testspectra/cli": cliDepVersion,
             "@types/node": "^20.14.0",
             "@wdio/globals": "^9.2.8",
             "@wdio/mocha-framework": "^9.2.8",
@@ -122,7 +154,9 @@ export default defineConfig({
                 },
                 devDependencies: {
                     ...(existing.devDependencies || {}),
-                    "@testspectra/cli": existing.devDependencies?.["@testspectra/cli"] || "workspace:*",
+                    "@testspectra/cli": existing.devDependencies?.["@testspectra/cli"]?.startsWith("workspace:") && !isInternalWorkspace
+                        ? cliVersion
+                        : existing.devDependencies?.["@testspectra/cli"] || cliDepVersion,
                     "@types/node": existing.devDependencies?.["@types/node"] || "^20.14.0",
                     "@wdio/globals": existing.devDependencies?.["@wdio/globals"] || "^9.2.8",
                     "@wdio/mocha-framework": existing.devDependencies?.["@wdio/mocha-framework"] || "^9.2.8",
@@ -283,14 +317,18 @@ export default defineConfig({
     return $('button[type="submit"]');
   }
 
+  static get flashAlert(): ChainablePromiseElement {
+    return $('#flash');
+  }
+
   static async open() {
-    await browser.url('/login');
+    await Spectra.navigate('/login');
   }
 
   static async login(username: string, pass: string) {
-    await this.usernameInput.setValue(username);
-    await this.passwordInput.setValue(pass);
-    await this.submitButton.click();
+    await Spectra.type(this.usernameInput, username);
+    await Spectra.type(this.passwordInput, pass);
+    await Spectra.click(this.submitButton);
   }
 }
 `;
@@ -308,14 +346,18 @@ export default defineConfig({
     return $('~login_button');
   }
 
+  static get welcomeText(): ChainablePromiseElement {
+    return $('~welcome_text');
+  }
+
   static async open() {
     // Mobile app startup
   }
 
   static async login(username: string, pass: string) {
-    await this.usernameInput.setValue(username);
-    await this.passwordInput.setValue(pass);
-    await this.submitButton.click();
+    await Spectra.type(this.usernameInput, username);
+    await Spectra.type(this.passwordInput, pass);
+    await Spectra.click(this.submitButton);
   }
 }
 `;
@@ -366,32 +408,33 @@ export default defineConfig({
 }
 `;
     fs.writeFileSync(path.join(cwd, "hooks/default/before.ios.hook.ts"), hookIos, "utf-8");
-    // 10. Scaffold Specs (Pure test scripts, ZERO triple-slash lines)
-    const specWeb = `it("should authenticate user using web locators and fixtures", async () => {
+    // 10. Scaffold Specs (Pure test scripts, ZERO triple-slash lines, ZERO raw selectors)
+    const specWeb = `it("should authenticate user using Page Objects and Spectra assertions", async () => {
   await browser.intercept("/api/status", "GET", Fixture.userData);
+
+  // 1. Navigation via Page Object
   await LoginPage.open();
-  await LoginPage.login("tomsmith", "SuperSecretPassword!");
 
-  const flash = await $("#flash");
-  await expect(flash).toBeDisplayed();
+  // 2. High-level business flow via Shared Step & Page Object
+  await Step.loginUser("tomsmith", "SuperSecretPassword!");
+
+  // 3. Direct callable assertion on Page Object element
+  await LoginPage.flashAlert.shouldBeVisible();
+  await LoginPage.flashAlert.shouldContainText("You logged into a secure area!");
 });
 `;
     fs.writeFileSync(path.join(cwd, "specs/TC-LOGIN-01/web.test.ts"), specWeb, "utf-8");
-    const specAndroid = `it("should authenticate user on Android Appium device", async () => {
-  await LoginPage.open();
-  await LoginPage.login("tomsmith", "SuperSecretPassword!");
+    const specAndroid = `it("should authenticate user on Android Appium device using Page Objects", async () => {
+  await Step.loginUser("tomsmith", "SuperSecretPassword!");
 
-  const welcome = await $("~welcome_text");
-  await expect(welcome).toBeDisplayed();
+  await LoginPage.welcomeText.shouldBeVisible();
 });
 `;
     fs.writeFileSync(path.join(cwd, "specs/TC-LOGIN-01/android.test.ts"), specAndroid, "utf-8");
-    const specIos = `it("should authenticate user on iOS Appium device", async () => {
-  await LoginPage.open();
-  await LoginPage.login("tomsmith", "SuperSecretPassword!");
+    const specIos = `it("should authenticate user on iOS Appium device using Page Objects", async () => {
+  await Step.loginUser("tomsmith", "SuperSecretPassword!");
 
-  const welcome = await $("~welcome_text");
-  await expect(welcome).toBeDisplayed();
+  await LoginPage.welcomeText.shouldBeVisible();
 });
 `;
     fs.writeFileSync(path.join(cwd, "specs/TC-LOGIN-01/ios.test.ts"), specIos, "utf-8");

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { Command } from "commander";
 export * from "./config/schema.js";
 export * from "./config/loader.js";
 export * from "./types/generator.js";
+export * from "./step/index.js";
 export { init as initTsPlugin, default as tsPlugin } from "./plugin.js";
 export declare function createCliProgram(): Command;
 export declare function runCli(args?: string[]): Promise<void>;

package/dist/index.js

@@ -6,6 +6,7 @@ import { runCommand } from "./commands/run.js";
 export * from "./config/schema.js";
 export * from "./config/loader.js";
 export * from "./types/generator.js";
+export * from "./step/index.js";
 export { init as initTsPlugin, default as tsPlugin } from "./plugin.js";
 export function createCliProgram() {
     const program = new Command();

package/dist/step/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./matchers.js";
+export * from "./runner/single.js";
+export * from "./runner/collection.js";
+export * from "./spectra.js";
+export * from "./proto.js";

package/dist/step/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./matchers.js";
+export * from "./runner/single.js";
+export * from "./runner/collection.js";
+export * from "./spectra.js";
+export * from "./proto.js";

package/dist/step/matchers.d.ts

@@ -0,0 +1,14 @@
+import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+export declare function resolveElement(target: ElementTarget): Promise<WebdriverIO.Element>;
+/**
+ * Executes a single element matcher against the WebdriverIO browser / element context.
+ */
+export declare function executeSingleMatcher(target: ElementTarget | undefined, matcher: SingleElementMatcher, args: any[]): Promise<void>;
+/**
+ * Executes a multi-element collection matcher against WebdriverIO $$.
+ */
+export declare function executeMultiMatcher(selector: string, matcher: MultiElementMatcher, args: any[]): Promise<void>;

package/dist/step/matchers.js

@@ -0,0 +1,114 @@
+/**
+ * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
+ * to an actionable WebdriverIO.Element.
+ */
+export async function resolveElement(target) {
+    if (typeof target === "string") {
+        const el = await $(target);
+        return el;
+    }
+    const el = await target;
+    return el;
+}
+/**
+ * Executes a single element matcher against the WebdriverIO browser / element context.
+ */
+export async function executeSingleMatcher(target, matcher, args) {
+    const isBrowserLevel = matcher === "have.url" ||
+        matcher === "contain.url" ||
+        matcher === "have.title" ||
+        matcher === "contain.title";
+    if (isBrowserLevel) {
+        const expected = args[0];
+        switch (matcher) {
+            case "have.url":
+                await expect(browser).toHaveUrl(expected);
+                break;
+            case "contain.url":
+                await expect(browser).toHaveUrl(expect.stringContaining(expected));
+                break;
+            case "have.title":
+                await expect(browser).toHaveTitle(expected);
+                break;
+            case "contain.title":
+                await expect(browser).toHaveTitle(expect.stringContaining(expected));
+                break;
+        }
+        return;
+    }
+    if (!target) {
+        throw new Error(`Assertion matcher '${matcher}' requires an element target.`);
+    }
+    const el = await resolveElement(target);
+    switch (matcher) {
+        case "be.visible":
+            await expect(el).toBeDisplayed();
+            break;
+        case "not.be.visible":
+            await expect(el).not.toBeDisplayed();
+            break;
+        case "exist":
+            await expect(el).toExist();
+            break;
+        case "not.exist":
+            await expect(el).not.toExist();
+            break;
+        case "be.enabled":
+            await expect(el).toBeEnabled();
+            break;
+        case "be.disabled":
+            await expect(el).toBeDisabled();
+            break;
+        case "be.checked":
+        case "be.selected":
+            await expect(el).toBeSelected();
+            break;
+        case "have.value":
+            await expect(el).toHaveValue(args[0]);
+            break;
+        case "contain.value":
+            await expect(el).toHaveValue(expect.stringContaining(args[0]));
+            break;
+        case "have.text":
+            await expect(el).toHaveText(args[0]);
+            break;
+        case "contain.text":
+            await expect(el).toHaveText(expect.stringContaining(args[0]));
+            break;
+        case "have.class":
+            await expect(el).toHaveElementClass(args[0]);
+            break;
+        case "have.attr":
+            if (args.length >= 2) {
+                await expect(el).toHaveAttribute(args[0], args[1]);
+            }
+            else {
+                await expect(el).toHaveAttribute(args[0]);
+            }
+            break;
+        default:
+            throw new Error(`Unsupported matcher: ${matcher}`);
+    }
+}
+/**
+ * Executes a multi-element collection matcher against WebdriverIO $$.
+ */
+export async function executeMultiMatcher(selector, matcher, args) {
+    const elements = await $$(selector);
+    switch (matcher) {
+        case "have.length":
+            await expect(elements).toBeElementsArrayOfSize(args[0]);
+            break;
+        case "have.length.greaterThan":
+            await expect(elements).toBeElementsArrayOfSize({ gte: args[0] + 1 });
+            break;
+        case "be.empty":
+            await expect(elements).toBeElementsArrayOfSize(0);
+            break;
+        case "exist":
+            await expect(elements).toBeElementsArrayOfSize({ gte: 1 });
+            break;
+        default:
+            throw new Error(`Unsupported multi-element matcher: ${matcher}`);
+    }
+}

package/dist/step/proto.d.ts

@@ -0,0 +1,46 @@
+declare global {
+    namespace WebdriverIO {
+        interface Element {
+            shouldBeVisible(): Promise<Element>;
+            shouldNotBeVisible(): Promise<Element>;
+            shouldExist(): Promise<Element>;
+            shouldNotExist(): Promise<Element>;
+            shouldBeEnabled(): Promise<Element>;
+            shouldBeDisabled(): Promise<Element>;
+            shouldBeSelected(): Promise<Element>;
+            shouldBeChecked(): Promise<Element>;
+            shouldHaveValue(expectedValue: string): Promise<Element>;
+            shouldContainValue(expectedValue: string): Promise<Element>;
+            shouldHaveText(expectedText: string): Promise<Element>;
+            shouldContainText(expectedText: string): Promise<Element>;
+            shouldHaveClass(className: string): Promise<Element>;
+            shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;
+        }
+        interface Browser {
+            shouldHaveUrl(expectedUrl: string): Promise<void>;
+            shouldContainUrl(expectedUrl: string): Promise<void>;
+            shouldHaveTitle(expectedTitle: string): Promise<void>;
+            shouldContainTitle(expectedTitle: string): Promise<void>;
+        }
+    }
+    interface Promise<T> {
+        shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;
+        shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+        shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;
+        shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+        shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;
+        shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;
+        shouldHaveAttribute(this: Promise<WebdriverIO.Element>, attributeName: string, expectedValue?: string): Promise<WebdriverIO.Element>;
+    }
+}
+/**
+ * Install direct callable assertion methods onto WebdriverIO browser/element and Promise prototypes.
+ */
+export declare function installPrototypes(): void;

package/dist/step/proto.js

@@ -0,0 +1,114 @@
+import { resolveElement } from "./matchers.js";
+/**
+ * Install direct callable assertion methods onto WebdriverIO browser/element and Promise prototypes.
+ */
+export function installPrototypes() {
+    const elementCommands = {
+        async shouldBeVisible() {
+            const el = await resolveElement(this);
+            await expect(el).toBeDisplayed();
+            return el;
+        },
+        async shouldNotBeVisible() {
+            const el = await resolveElement(this);
+            await expect(el).not.toBeDisplayed();
+            return el;
+        },
+        async shouldExist() {
+            const el = await resolveElement(this);
+            await expect(el).toExist();
+            return el;
+        },
+        async shouldNotExist() {
+            const el = await resolveElement(this);
+            await expect(el).not.toExist();
+            return el;
+        },
+        async shouldBeEnabled() {
+            const el = await resolveElement(this);
+            await expect(el).toBeEnabled();
+            return el;
+        },
+        async shouldBeDisabled() {
+            const el = await resolveElement(this);
+            await expect(el).toBeDisabled();
+            return el;
+        },
+        async shouldBeSelected() {
+            const el = await resolveElement(this);
+            await expect(el).toBeSelected();
+            return el;
+        },
+        async shouldBeChecked() {
+            const el = await resolveElement(this);
+            await expect(el).toBeSelected();
+            return el;
+        },
+        async shouldHaveValue(val) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveValue(val);
+            return el;
+        },
+        async shouldContainValue(val) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveValue(expect.stringContaining(val));
+            return el;
+        },
+        async shouldHaveText(text) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveText(text);
+            return el;
+        },
+        async shouldContainText(text) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveText(expect.stringContaining(text));
+            return el;
+        },
+        async shouldHaveClass(cls) {
+            const el = await resolveElement(this);
+            await expect(el).toHaveElementClass(cls);
+            return el;
+        },
+        async shouldHaveAttribute(name, val) {
+            const el = await resolveElement(this);
+            if (val !== undefined) {
+                await expect(el).toHaveAttribute(name, val);
+            }
+            else {
+                await expect(el).toHaveAttribute(name);
+            }
+            return el;
+        },
+    };
+    const browserCommands = {
+        async shouldHaveUrl(url) {
+            await expect(browser).toHaveUrl(url);
+        },
+        async shouldContainUrl(url) {
+            await expect(browser).toHaveUrl(expect.stringContaining(url));
+        },
+        async shouldHaveTitle(title) {
+            await expect(browser).toHaveTitle(title);
+        },
+        async shouldContainTitle(title) {
+            await expect(browser).toHaveTitle(expect.stringContaining(title));
+        },
+    };
+    if (typeof browser !== "undefined" && browser.addCommand) {
+        for (const [name, fn] of Object.entries(elementCommands)) {
+            browser.addCommand(name, fn, true);
+        }
+        for (const [name, fn] of Object.entries(browserCommands)) {
+            browser.addCommand(name, fn, false);
+        }
+    }
+    // Attach to Promise.prototype for ChainablePromiseElement unwrapping
+    for (const [name, fn] of Object.entries(elementCommands)) {
+        if (typeof Promise.prototype[name] !== "function") {
+            Promise.prototype[name] = async function (...args) {
+                const el = await this;
+                return await fn.call(el, ...args);
+            };
+        }
+    }
+}

package/dist/step/runner/collection.d.ts

@@ -0,0 +1,13 @@
+import { MultiElementMatcher } from "../types.js";
+import { SingleElementRunner } from "./single.js";
+export declare class MultiElementRunner implements PromiseLike<void> {
+    private _selector;
+    private _assertions;
+    constructor(selector: string);
+    should(matcher: MultiElementMatcher, ...args: any[]): this;
+    eq(index: number): SingleElementRunner;
+    first(): SingleElementRunner;
+    last(): SingleElementRunner;
+    each(callback: (el: SingleElementRunner, index: number) => Promise<void>): Promise<void>;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+}

package/dist/step/runner/collection.js

@@ -0,0 +1,51 @@
+import { executeMultiMatcher } from "../matchers.js";
+import { SingleElementRunner } from "./single.js";
+export class MultiElementRunner {
+    _selector;
+    _assertions = [];
+    constructor(selector) {
+        this._selector = selector;
+    }
+    // --- Collection Assertions ---
+    should(matcher, ...args) {
+        this._assertions.push({ matcher, args });
+        return this;
+    }
+    // --- Item Navigation ---
+    eq(index) {
+        const indexedSelector = `(${this._selector})[${index + 1}]`;
+        return new SingleElementRunner(indexedSelector);
+    }
+    first() {
+        return this.eq(0);
+    }
+    last() {
+        const indexedSelector = `(${this._selector})[last()]`;
+        return new SingleElementRunner(indexedSelector);
+    }
+    // --- Iteration Callback ---
+    async each(callback) {
+        const elements = await $$(this._selector);
+        const count = await elements.length;
+        for (let i = 0; i < count; i++) {
+            const runner = this.eq(i);
+            await callback(runner, i);
+        }
+    }
+    // --- Execution when awaited ---
+    async then(onfulfilled, onrejected) {
+        try {
+            for (const assert of this._assertions) {
+                await executeMultiMatcher(this._selector, assert.matcher, assert.args);
+            }
+            const res = (onfulfilled ? await onfulfilled() : undefined);
+            return res;
+        }
+        catch (err) {
+            if (onrejected) {
+                return onrejected(err);
+            }
+            throw err;
+        }
+    }
+}

package/dist/step/runner/single.d.ts

@@ -0,0 +1,21 @@
+import { SingleElementMatcher, ElementTarget } from "../types.js";
+export declare class SingleElementRunner implements PromiseLike<void> {
+    private _target;
+    private _action;
+    private _assertions;
+    constructor(target?: ElementTarget, action?: () => Promise<any>);
+    click(): this;
+    doubleClick(): this;
+    longPress(durationMs?: number): this;
+    type(value: string, options?: {
+        clearFirst?: boolean;
+    }): this;
+    clear(): this;
+    select(value: string): this;
+    hover(): this;
+    waitForElement(timeoutMs?: number): this;
+    should(matcher: SingleElementMatcher, ...args: any[]): this;
+    should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private requireTarget;
+}