@testspectra/cli 1.0.5 → 1.0.6

package/dist/step/runner/single.js

@@ -0,0 +1,138 @@
+import { executeSingleMatcher, resolveElement } from "../matchers.js";
+export class SingleElementRunner {
+    _target;
+    _action = null;
+    _assertions = [];
+    constructor(target, action) {
+        this._target = target;
+        this._action = action || null;
+    }
+    // --- Chained Actions on current target ---
+    click() {
+        const target = this.requireTarget("click");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.click();
+        };
+        return this;
+    }
+    doubleClick() {
+        const target = this.requireTarget("doubleClick");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.doubleClick();
+        };
+        return this;
+    }
+    longPress(durationMs = 1000) {
+        const target = this.requireTarget("longPress");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            if (typeof el.touchAction === "function") {
+                await el.touchAction([
+                    { action: "longPress", ms: durationMs },
+                    { action: "release" },
+                ]);
+            }
+            else {
+                await el.click();
+            }
+        };
+        return this;
+    }
+    type(value, options) {
+        const target = this.requireTarget("type");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            if (options?.clearFirst) {
+                await el.clearValue();
+            }
+            await el.setValue(value);
+        };
+        return this;
+    }
+    clear() {
+        const target = this.requireTarget("clear");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.clearValue();
+        };
+        return this;
+    }
+    select(value) {
+        const target = this.requireTarget("select");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.selectByVisibleText(value);
+        };
+        return this;
+    }
+    hover() {
+        const target = this.requireTarget("hover");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.moveTo();
+        };
+        return this;
+    }
+    waitForElement(timeoutMs = 10000) {
+        const target = this.requireTarget("waitForElement");
+        this._action = async () => {
+            const el = await resolveElement(target);
+            await el.waitForDisplayed({ timeout: timeoutMs });
+        };
+        return this;
+    }
+    should(a, b, ...rest) {
+        const isFirstArgMatcher = typeof a === "string" &&
+            (a.includes(".") ||
+                a.includes("exist") ||
+                a.includes("visible") ||
+                a.includes("enabled") ||
+                a.includes("disabled") ||
+                a.includes("selected") ||
+                a.includes("checked"));
+        if (b !== undefined && !isFirstArgMatcher) {
+            // Form: should(target, matcher, ...args)
+            this._assertions.push({
+                target: a,
+                matcher: b,
+                args: rest,
+            });
+        }
+        else {
+            // Form: should(matcher, ...args) -> on current target
+            this._assertions.push({
+                target: this._target,
+                matcher: a,
+                args: b !== undefined ? [b, ...rest] : rest,
+            });
+        }
+        return this;
+    }
+    // --- Execution when awaited ---
+    async then(onfulfilled, onrejected) {
+        try {
+            if (this._action) {
+                await this._action();
+            }
+            for (const assert of this._assertions) {
+                await executeSingleMatcher(assert.target, assert.matcher, assert.args);
+            }
+            const res = (onfulfilled ? await onfulfilled() : undefined);
+            return res;
+        }
+        catch (err) {
+            if (onrejected) {
+                return onrejected(err);
+            }
+            throw err;
+        }
+    }
+    requireTarget(actionName) {
+        if (!this._target) {
+            throw new Error(`Cannot execute '${actionName}' without specifying an element target.`);
+        }
+        return this._target;
+    }
+}

package/dist/step/spectra.d.ts

@@ -0,0 +1,34 @@
+import { ClickOptions, ElementTarget, KeyOption, LongPressOptions, ScrollOptions, SwipeOptions, TypeOptions } from "./types.js";
+import { SingleElementRunner } from "./runner/single.js";
+import { MultiElementRunner } from "./runner/collection.js";
+/**
+ * Main Spectra testing API orchestrator.
+ * Combines direct actions, single element queries (get), and collections (getAll).
+ */
+export declare class SpectraStatic {
+    /**
+     * Targets a single element by selector or Page Object element.
+     */
+    get(target: ElementTarget): SingleElementRunner;
+    /**
+     * Targets multiple elements / collections by selector.
+     */
+    getAll(selector: string): MultiElementRunner;
+    navigate(url: string): SingleElementRunner;
+    back(): SingleElementRunner;
+    refresh(): SingleElementRunner;
+    click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner;
+    longPress(target: ElementTarget, options?: LongPressOptions | number): SingleElementRunner;
+    type(target: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner;
+    clear(target: ElementTarget): SingleElementRunner;
+    select(target: ElementTarget, value: string): SingleElementRunner;
+    hover(target: ElementTarget): SingleElementRunner;
+    pressKey(key: KeyOption | string): SingleElementRunner;
+    dragDrop(sourceTarget: ElementTarget, destTarget: ElementTarget): SingleElementRunner;
+    scroll(options?: ScrollOptions): SingleElementRunner;
+    swipe(options: SwipeOptions): SingleElementRunner;
+    wait(durationMs: number): SingleElementRunner;
+    waitForElement(target: ElementTarget, timeoutMs?: number): SingleElementRunner;
+}
+export declare const Spectra: SpectraStatic;

package/dist/step/spectra.js

@@ -0,0 +1,156 @@
+import { SingleElementRunner } from "./runner/single.js";
+import { MultiElementRunner } from "./runner/collection.js";
+import { resolveElement } from "./matchers.js";
+/**
+ * Main Spectra testing API orchestrator.
+ * Combines direct actions, single element queries (get), and collections (getAll).
+ */
+export class SpectraStatic {
+    /**
+     * Targets a single element by selector or Page Object element.
+     */
+    get(target) {
+        return new SingleElementRunner(target);
+    }
+    /**
+     * Targets multiple elements / collections by selector.
+     */
+    getAll(selector) {
+        return new MultiElementRunner(selector);
+    }
+    // --- Browser & Navigation Actions ---
+    navigate(url) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.url(url);
+        });
+    }
+    back() {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.back();
+        });
+    }
+    refresh() {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.refresh();
+        });
+    }
+    // --- Direct Interaction Actions ---
+    click(target, textOrOptions) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.click();
+        });
+    }
+    doubleClick(target, textOrOptions) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.doubleClick();
+        });
+    }
+    longPress(target, options) {
+        const duration = typeof options === "number" ? options : options?.duration || 1000;
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            if (typeof el.touchAction === "function") {
+                await el.touchAction([
+                    { action: "longPress", ms: duration },
+                    { action: "release" },
+                ]);
+            }
+            else {
+                await el.click();
+            }
+        });
+    }
+    type(target, value, options) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            if (options?.clearFirst) {
+                await el.clearValue();
+            }
+            await el.setValue(value);
+        });
+    }
+    clear(target) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.clearValue();
+        });
+    }
+    select(target, value) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.selectByVisibleText(value);
+        });
+    }
+    hover(target) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.moveTo();
+        });
+    }
+    pressKey(key) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.keys(key);
+        });
+    }
+    dragDrop(sourceTarget, destTarget) {
+        return new SingleElementRunner(sourceTarget, async () => {
+            const source = await resolveElement(sourceTarget);
+            const target = await resolveElement(destTarget);
+            await source.dragAndDrop(target);
+        });
+    }
+    // --- Gesture Actions ---
+    scroll(options) {
+        return new SingleElementRunner(options?.selector, async () => {
+            if (options?.selector) {
+                const el = await resolveElement(options.selector);
+                await el.scrollIntoView();
+            }
+            else {
+                await browser.execute((direction, pixels) => {
+                    const delta = pixels || 500;
+                    window.scrollBy({
+                        top: direction === "up" ? -delta : direction === "down" ? delta : 0,
+                        left: direction === "left" ? -delta : direction === "right" ? delta : 0,
+                        behavior: "smooth",
+                    });
+                }, options?.direction || "down", options?.pixels || 500);
+            }
+        });
+    }
+    swipe(options) {
+        return new SingleElementRunner(options.selector, async () => {
+            if (typeof browser.touchAction === "function") {
+                const distance = options.distance || 300;
+                await browser.touchAction([
+                    { action: "press", x: 200, y: 500 },
+                    {
+                        action: "moveTo",
+                        x: options.direction === "right" ? 200 + distance : options.direction === "left" ? 200 - distance : 200,
+                        y: options.direction === "down" ? 500 + distance : options.direction === "up" ? 500 - distance : 500,
+                    },
+                    { action: "release" },
+                ]);
+            }
+            else {
+                // Fallback to web scroll
+                await this.scroll({ direction: options.direction, pixels: options.distance });
+            }
+        });
+    }
+    // --- Timing Actions ---
+    wait(durationMs) {
+        return new SingleElementRunner(undefined, async () => {
+            await browser.pause(durationMs);
+        });
+    }
+    waitForElement(target, timeoutMs = 10000) {
+        return new SingleElementRunner(target, async () => {
+            const el = await resolveElement(target);
+            await el.waitForDisplayed({ timeout: timeoutMs });
+        });
+    }
+}
+export const Spectra = new SpectraStatic();

package/dist/step/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Database Canonical Action and Assertion Types
+ * Matches backend/src/models/test_step.rs
+ */
+export type ActionKey = "navigate" | "click" | "type" | "clear" | "select" | "scroll" | "swipe" | "wait" | "waitForElement" | "pressKey" | "longPress" | "doubleClick" | "hover" | "dragDrop" | "back" | "refresh";
+export type AssertionKey = "elementDisplayed" | "elementNotDisplayed" | "elementExists" | "elementEnabled" | "elementDisabled" | "textContains" | "textEquals" | "textNotContains" | "urlContains" | "urlEquals" | "valueEquals" | "valueContains" | "attributeEquals" | "attributeContains" | "hasClass" | "hasAttribute" | "isSelected" | "elementCount" | "elementCountGreaterThan" | "pageLoaded" | "noErrors";
+export type KeyOption = "Enter" | "Tab" | "Escape" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Space";
+export type Direction = "up" | "down" | "left" | "right";
+export type ElementTarget = string | WebdriverIO.Element | ChainablePromiseElement;
+export interface ScrollOptions {
+    direction?: Direction;
+    pixels?: number;
+    selector?: ElementTarget;
+}
+export interface SwipeOptions {
+    direction: Direction;
+    distance?: number;
+    selector?: ElementTarget;
+}
+export interface LongPressOptions {
+    text?: string;
+    duration?: number;
+}
+export interface ClickOptions {
+    text?: string;
+    clickType?: "single" | "double";
+}
+export interface TypeOptions {
+    clearFirst?: boolean;
+}
+export type SingleElementMatcher = "be.visible" | "not.be.visible" | "exist" | "not.exist" | "be.enabled" | "be.disabled" | "be.checked" | "be.selected" | "have.value" | "contain.value" | "have.text" | "contain.text" | "have.class" | "have.attr" | "have.url" | "contain.url" | "have.title" | "contain.title";
+export type MultiElementMatcher = "have.length" | "have.length.greaterThan" | "be.empty" | "exist";

package/dist/step/types.js

@@ -0,0 +1,5 @@
+/**
+ * Database Canonical Action and Assertion Types
+ * Matches backend/src/models/test_step.rs
+ */
+export {};

package/dist/types/generator.js

@@ -44,7 +44,43 @@ export class TypeGenerator {
             content += `  }\n`;
             content += `  interface Browser {\n`;
             content += `    intercept<TData = unknown>(path: string, method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', fixture?: InterceptInput<TData>, options?: InterceptFixtureOptions): Promise<Mock>;\n`;
+            content += `    shouldHaveUrl(expectedUrl: string): Promise<void>;\n`;
+            content += `    shouldContainUrl(expectedUrl: string): Promise<void>;\n`;
+            content += `    shouldHaveTitle(expectedTitle: string): Promise<void>;\n`;
+            content += `    shouldContainTitle(expectedTitle: string): Promise<void>;\n`;
             content += `  }\n`;
+            content += `  interface Element {\n`;
+            content += `    shouldBeVisible(): Promise<Element>;\n`;
+            content += `    shouldNotBeVisible(): Promise<Element>;\n`;
+            content += `    shouldExist(): Promise<Element>;\n`;
+            content += `    shouldNotExist(): Promise<Element>;\n`;
+            content += `    shouldBeEnabled(): Promise<Element>;\n`;
+            content += `    shouldBeDisabled(): Promise<Element>;\n`;
+            content += `    shouldBeSelected(): Promise<Element>;\n`;
+            content += `    shouldBeChecked(): Promise<Element>;\n`;
+            content += `    shouldHaveValue(expectedValue: string): Promise<Element>;\n`;
+            content += `    shouldContainValue(expectedValue: string): Promise<Element>;\n`;
+            content += `    shouldHaveText(expectedText: string): Promise<Element>;\n`;
+            content += `    shouldContainText(expectedText: string): Promise<Element>;\n`;
+            content += `    shouldHaveClass(className: string): Promise<Element>;\n`;
+            content += `    shouldHaveAttribute(attributeName: string, expectedValue?: string): Promise<Element>;\n`;
+            content += `  }\n`;
+            content += `}\n\n`;
+            content += `interface Promise<T> {\n`;
+            content += `  shouldBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldNotBeVisible(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldNotExist(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldBeEnabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldBeDisabled(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldBeSelected(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldBeChecked(this: Promise<WebdriverIO.Element>): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldHaveValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldContainValue(this: Promise<WebdriverIO.Element>, expectedValue: string): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldHaveText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldContainText(this: Promise<WebdriverIO.Element>, expectedText: string): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldHaveClass(this: Promise<WebdriverIO.Element>, className: string): Promise<WebdriverIO.Element>;\n`;
+            content += `  shouldHaveAttribute(this: Promise<WebdriverIO.Element>, attributeName: string, expectedValue?: string): Promise<WebdriverIO.Element>;\n`;
             content += `}\n\n`;
             // 1. Page Objects Global Declarations (Hierarchical)
             // 2. Page Objects Global Declarations (Hierarchical)
@@ -75,8 +111,8 @@ export class TypeGenerator {
                     }
                 }
             }
-            // 3. Actions Global Interface
-            content += `\ninterface TestSpectraActions {\n`;
+            // 3. Actions Global Interface (Extends built-in @testspectra/cli Spectra)
+            content += `\ninterface TestSpectraActions extends Omit<typeof import('@testspectra/cli').Spectra, ''> {\n`;
             if (fs.existsSync(actionsDir)) {
                 const actionEntries = fs.readdirSync(actionsDir, { withFileTypes: true });
                 for (const entry of actionEntries) {
@@ -99,7 +135,7 @@ export class TypeGenerator {
                             }
                         }
                         if (matchedFile) {
-                            content += `  ${actionName}: typeof import('${matchedFile}');\n`;
+                            content += `  ${actionName}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
                         }
                         else {
                             content += `  ${actionName}: (...args: any[]) => Promise<any>;\n`;
@@ -107,7 +143,8 @@ export class TypeGenerator {
                     }
                     else if (entry.isFile() && entry.name.endsWith(".ts")) {
                         const actionName = entry.name.split(".")[0];
-                        content += `  ${actionName}: typeof import('../../actions/${entry.name.replace(".ts", ".js")}');\n`;
+                        const modPath = `../../actions/${entry.name.replace(".ts", ".js")}`;
+                        content += `  ${actionName}: (typeof import('${modPath}') extends { default: infer T } ? T : typeof import('${modPath}'));\n`;
                     }
                 }
             }
@@ -137,7 +174,7 @@ export class TypeGenerator {
                             }
                         }
                         if (matchedFile) {
-                            content += `  ${stepName}: typeof import('${matchedFile}');\n`;
+                            content += `  ${stepName}: (typeof import('${matchedFile}') extends { default: infer T } ? T : typeof import('${matchedFile}'));\n`;
                         }
                         else {
                             content += `  ${stepName}: (...args: any[]) => Promise<any>;\n`;
@@ -145,7 +182,8 @@ export class TypeGenerator {
                     }
                     else if (entry.isFile() && entry.name.endsWith(".ts")) {
                         const stepName = entry.name.split(".")[0];
-                        content += `  ${stepName}: typeof import('../../steps/${entry.name.replace(".ts", ".js")}');\n`;
+                        const modPath = `../../steps/${entry.name.replace(".ts", ".js")}`;
+                        content += `  ${stepName}: (typeof import('${modPath}') extends { default: infer T } ? T : typeof import('${modPath}'));\n`;
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "TestSpectra Zero-Config Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/commands/init.ts

@@ -294,14 +294,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);
   }
 }
 `;
@@ -320,14 +324,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);
   }
 }
 `;
@@ -386,34 +394,35 @@ 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/src/index.ts

@@ -7,6 +7,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() {

package/src/step/index.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";