@testspectra/cli 1.0.5 → 1.0.7

package/src/step/spectra.ts

@@ -0,0 +1,185 @@
+import {
+  ClickOptions,
+  ElementTarget,
+  KeyOption,
+  LongPressOptions,
+  ScrollOptions,
+  SwipeOptions,
+  TypeOptions,
+} from "./types.js";
+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: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target);
+  }
+
+  /**
+   * Targets multiple elements / collections by selector.
+   */
+  getAll(selector: string): MultiElementRunner {
+    return new MultiElementRunner(selector);
+  }
+
+  // --- Browser & Navigation Actions ---
+
+  navigate(url: string): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.url(url);
+    });
+  }
+
+  back(): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.back();
+    });
+  }
+
+  refresh(): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.refresh();
+    });
+  }
+
+  // --- Direct Interaction Actions ---
+
+  click(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.click();
+    });
+  }
+
+  doubleClick(target: ElementTarget, textOrOptions?: string | ClickOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.doubleClick();
+    });
+  }
+
+  longPress(target: ElementTarget, options?: LongPressOptions | number): SingleElementRunner {
+    const duration = typeof options === "number" ? options : options?.duration || 1000;
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      if (typeof (el as any).touchAction === "function") {
+        await (el as any).touchAction([
+          { action: "longPress", ms: duration },
+          { action: "release" },
+        ]);
+      } else {
+        await el.click();
+      }
+    });
+  }
+
+  type(target: ElementTarget, value: string, options?: TypeOptions): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      if (options?.clearFirst) {
+        await el.clearValue();
+      }
+      await el.setValue(value);
+    });
+  }
+
+  clear(target: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.clearValue();
+    });
+  }
+
+  select(target: ElementTarget, value: string): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.selectByVisibleText(value);
+    });
+  }
+
+  hover(target: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.moveTo();
+    });
+  }
+
+  pressKey(key: KeyOption | string): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.keys(key);
+    });
+  }
+
+  dragDrop(sourceTarget: ElementTarget, destTarget: ElementTarget): SingleElementRunner {
+    return new SingleElementRunner(sourceTarget, async () => {
+      const source = await resolveElement(sourceTarget);
+      const target = await resolveElement(destTarget);
+      await source.dragAndDrop(target);
+    });
+  }
+
+  // --- Gesture Actions ---
+
+  scroll(options?: ScrollOptions): SingleElementRunner {
+    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: SwipeOptions): SingleElementRunner {
+    return new SingleElementRunner(options.selector, async () => {
+      if (typeof (browser as any).touchAction === "function") {
+        const distance = options.distance || 300;
+        await (browser as any).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: number): SingleElementRunner {
+    return new SingleElementRunner(undefined, async () => {
+      await browser.pause(durationMs);
+    });
+  }
+
+  waitForElement(target: ElementTarget, timeoutMs = 10000): SingleElementRunner {
+    return new SingleElementRunner(target, async () => {
+      const el = await resolveElement(target);
+      await el.waitForDisplayed({ timeout: timeoutMs });
+    });
+  }
+}
+
+export const Spectra = new SpectraStatic();

package/src/step/types.ts

@@ -0,0 +1,113 @@
+/**
+ * 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/src/types/generator.ts

@@ -51,7 +51,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)
@@ -83,8 +119,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) {
@@ -105,13 +141,14 @@ 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`;
             }
           } 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`;
           }
         }
       }
@@ -140,13 +177,14 @@ 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`;
             }
           } 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/tsconfig.json

@@ -9,6 +9,7 @@
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,
+    "types": ["node", "@wdio/globals/types", "@wdio/mocha-framework"],
     "forceConsistentCasingInFileNames": true
   },
   "include": ["src/**/*"],