@testspectra/plugin-demo 1.2.0

package/LICENSE.md

@@ -0,0 +1,48 @@
+# TestSpectra Commercial Software License Agreement
+
+Copyright (c) 2026 TestSpectra. All rights reserved.
+
+IMPORTANT NOTICE: This software is NOT open-source. Although distribution archives,
+npm packages, and editor extensions are publicly downloadable, installation,
+execution, and use of the Software are strictly conditioned upon obtaining a valid
+Commercial License or an authorized Evaluation/Trial License from TestSpectra.
+
+1. GRANT OF LICENSE
+   Subject to payment of applicable license fees or an active authorized evaluation
+   period, TestSpectra grants you a non-exclusive, non-transferable, revocable license
+   to install and execute the Software solely for authoring, debugging, and executing
+   automated software tests.
+
+2. LICENSE ACTIVATION & ENFORCEMENT
+   - Use of the Software requires activation via a valid License Key, authorized CI token,
+     or active TestSpectra Cloud account.
+   - Any attempt to circumvent, disable, modify, reverse engineer, or tamper with the
+     license verification mechanisms, cryptographic signatures, or binary checks is
+     a material breach of this Agreement and automatically terminates your license.
+
+3. RESTRICTIONS
+   You shall not, and shall not permit any third party to:
+   - Decompile, disassemble, reverse engineer, or derive source code from the binaries,
+     compiled scripts, or libraries of the Software.
+   - Sublicense, sell, rent, lease, distribute, or host the Software as a service for third parties.
+   - Re-brand, white-label, or package the Software or any of its components as part of a
+     competing commercial QA, testing, or developer tooling product.
+   - Modify, alter, or remove any proprietary notices, copyright labels, or license headers.
+
+4. INTELLECTUAL PROPERTY
+   The Software, including its source code, architecture, Rust core engine, algorithms,
+   matchers, extensions, interfaces, and documentation, represents valuable intellectual
+   property and trade secrets of TestSpectra.
+
+5. TERMINATION
+   This license is effective until terminated. Your rights under this license will terminate
+   automatically without notice if you fail to comply with any of its terms, or upon expiration
+   of your active subscription or trial term. Upon termination, you must cease all use of
+   the Software and delete all copies in your possession.
+
+6. DISCLAIMER OF WARRANTY & LIMITATION OF LIABILITY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+   INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+   PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+   FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+   ARISING FROM THE USE OF OR INABILITY TO USE THE SOFTWARE.

package/dist/ButtonHandle.d.ts

@@ -0,0 +1,10 @@
+import { ComponentHandle } from './ComponentHandle.js';
+/**
+ * Button-specific handle returned by the demo plugin's `Spectra.findButton()` command.
+ */
+export declare class ButtonHandle extends ComponentHandle {
+    /** Activates the button (aliases `click()` with button-oriented intent). */
+    press(): Promise<void>;
+    /** Asserts the button's accessible/label text. */
+    assertLabel(expected: string | RegExp): Promise<void>;
+}

package/dist/ButtonHandle.js

@@ -0,0 +1,14 @@
+import { ComponentHandle } from './ComponentHandle.js';
+/**
+ * Button-specific handle returned by the demo plugin's `Spectra.findButton()` command.
+ */
+export class ButtonHandle extends ComponentHandle {
+    /** Activates the button (aliases `click()` with button-oriented intent). */
+    async press() {
+        await this.element.click();
+    }
+    /** Asserts the button's accessible/label text. */
+    async assertLabel(expected) {
+        await this.element.shouldHaveText(expected);
+    }
+}

package/dist/ComponentHandle.d.ts

@@ -0,0 +1,21 @@
+import type { SingleElementProxy } from '@testspectra/matchers';
+/**
+ * Universal wrapper around a single resolved element, exposing a small fluent surface that plugin
+ * commands can return. Kept generic on purpose so the plugin is not tied to any one widget type.
+ */
+export declare class ComponentHandle {
+    protected readonly element: SingleElementProxy;
+    constructor(element: SingleElementProxy);
+    /** The underlying Spectra element proxy, for escape-hatch access. */
+    get el(): SingleElementProxy;
+    /** Clicks the wrapped element. */
+    click(): Promise<void>;
+    /** Returns the wrapped element's text content. */
+    getText(): Promise<string>;
+    /** Asserts the wrapped element's text matches `expected`. */
+    shouldHaveText(expected: string | RegExp): Promise<void>;
+    /** Asserts the wrapped element is visible. */
+    shouldBeVisible(): Promise<void>;
+    /** Asserts the wrapped element exists in the DOM. */
+    shouldExist(): Promise<void>;
+}

package/dist/ComponentHandle.js

@@ -0,0 +1,34 @@
+/**
+ * Universal wrapper around a single resolved element, exposing a small fluent surface that plugin
+ * commands can return. Kept generic on purpose so the plugin is not tied to any one widget type.
+ */
+export class ComponentHandle {
+    element;
+    constructor(element) {
+        this.element = element;
+    }
+    /** The underlying Spectra element proxy, for escape-hatch access. */
+    get el() {
+        return this.element;
+    }
+    /** Clicks the wrapped element. */
+    async click() {
+        await this.element.click();
+    }
+    /** Returns the wrapped element's text content. */
+    async getText() {
+        return await this.element.getText();
+    }
+    /** Asserts the wrapped element's text matches `expected`. */
+    async shouldHaveText(expected) {
+        await this.element.shouldHaveText(expected);
+    }
+    /** Asserts the wrapped element is visible. */
+    async shouldBeVisible() {
+        await this.element.shouldBeVisible();
+    }
+    /** Asserts the wrapped element exists in the DOM. */
+    async shouldExist() {
+        await this.element.shouldExist();
+    }
+}

package/dist/common.d.ts

@@ -0,0 +1,15 @@
+import type { ButtonHandle } from './ButtonHandle.js';
+import type { ComponentHandle } from './ComponentHandle.js';
+/**
+ * Platform-common command types — declared in the `common` stem, so the generator wires them into
+ * every platform's ambient declarations (web, android, ios, mobile, common). A command must be
+ * declared in exactly one stem file that covers the platforms it supports.
+ */
+declare module '@testspectra/matchers' {
+    interface SpectraStatic {
+        /** Finds a generic component by selector and returns a universal handle. */
+        findComponent(selector: string): ComponentHandle;
+        /** Finds a button by selector and returns a button-specific handle. */
+        findButton(selector: string): ButtonHandle;
+    }
+}

package/dist/common.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/plugin-demo
+ *
+ * Demo TestSpectra plugin. It is intentionally universal — a small component-interaction kit —
+ * and registers `Spectra` commands via `Spectra.registerCommand()`:
+ *
+ * - `Spectra.findComponent(selector)` → `ComponentHandle` (common: web + android + ios)
+ * - `Spectra.findButton(selector)` → `ButtonHandle` (common, the button-specific command)
+ * - `Spectra.findByCss(cssSelector)` → `ComponentHandle` (web only)
+ *
+ * Types are shipped as per-platform-stem subpath entries (`./common`, `./web`) which the type
+ * generator wires into the matching platform ambient declarations.
+ *
+ * Declare it in `spectra.config.ts`:
+ *
+ * ```ts
+ * executionConfig: { plugins: ['@testspectra/plugin-demo'] }
+ * ```
+ */
+import type { SpectraPlugin } from '@testspectra/matchers';
+declare const plugin: SpectraPlugin;
+export default plugin;
+export { ButtonHandle } from './ButtonHandle.js';
+export { ComponentHandle } from './ComponentHandle.js';

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/plugin-demo
+ *
+ * Demo TestSpectra plugin. It is intentionally universal — a small component-interaction kit —
+ * and registers `Spectra` commands via `Spectra.registerCommand()`:
+ *
+ * - `Spectra.findComponent(selector)` → `ComponentHandle` (common: web + android + ios)
+ * - `Spectra.findButton(selector)` → `ButtonHandle` (common, the button-specific command)
+ * - `Spectra.findByCss(cssSelector)` → `ComponentHandle` (web only)
+ *
+ * Types are shipped as per-platform-stem subpath entries (`./common`, `./web`) which the type
+ * generator wires into the matching platform ambient declarations.
+ *
+ * Declare it in `spectra.config.ts`:
+ *
+ * ```ts
+ * executionConfig: { plugins: ['@testspectra/plugin-demo'] }
+ * ```
+ */
+import { ButtonHandle } from './ButtonHandle.js';
+import { ComponentHandle } from './ComponentHandle.js';
+const plugin = {
+    name: '@testspectra/plugin-demo',
+    setup(spectra, { platform }) {
+        // Common commands: available on every platform.
+        spectra.registerCommands({
+            findComponent: (selector) => new ComponentHandle(spectra.get(selector)),
+            findButton: (selector) => new ButtonHandle(spectra.get(selector)),
+        });
+        // Web-only command: registered only when running against the web target.
+        if (platform === 'web') {
+            spectra.registerCommand('findByCss', (cssSelector) => new ComponentHandle(spectra.get(cssSelector)));
+        }
+    },
+};
+export default plugin;
+export { ButtonHandle } from './ButtonHandle.js';
+export { ComponentHandle } from './ComponentHandle.js';

package/dist/web.d.ts

@@ -0,0 +1,12 @@
+import type { ComponentHandle } from './ComponentHandle.js';
+/**
+ * Web-only command types — declared in the `web` stem, so `Spectra.findByCss` is only typed on the
+ * web platform (CSS selectors have no meaning on Android/iOS). The command is likewise registered
+ * only when the active platform is `web` (see `index.ts`).
+ */
+declare module '@testspectra/matchers' {
+    interface SpectraStatic {
+        /** Finds a component by raw CSS selector (web only). */
+        findByCss(cssSelector: string): ComponentHandle;
+    }
+}

package/dist/web.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@testspectra/plugin-demo",
+  "version": "1.2.0",
+  "description": "Demo TestSpectra plugin — a universal component-interaction kit that registers Spectra commands, including a button-specific one",
+  "keywords": [
+    "testspectra",
+    "spectra",
+    "plugin",
+    "component-testing"
+  ],
+  "homepage": "https://github.com/TestSpectra/testspectra-source",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TestSpectra/testspectra-source.git",
+    "directory": "tools/plugin-demo"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./common": {
+      "types": "./dist/common.d.ts"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@testspectra/matchers": "1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.3"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  }
+}