@testspectra/matchers 1.1.0 → 1.1.8-rc.2

package/dist/__tests__/matchers.test.js

@@ -89,14 +89,6 @@ describe('Matchers Assertion Library & Receiver API', () => {
             expect(runner.dragDrop('#dest')).toBe(runner);
             expect(runner._actionPayload.key).toBe('dragDrop');
         });
-        it('should support action to semantic assertion chaining', () => {
-            const runner = new SingleElementRunner('#login-btn');
-            runner.click().shouldNotBeVisible();
-            expect(runner._actionPayload.key).toBe('click');
-            const assertions = runner._assertions;
-            expect(assertions).toHaveLength(1);
-            expect(assertions[0].matcher).toBe('not.be.visible');
-        });
     });
     describe('MultiElementRunner - 6 Collection Receiver Assertions', () => {
         it('should queue all 6 collection assertions', () => {

package/dist/contract.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @packageDocumentation
+ * # PlatformDriverBridge Contract
+ *
+ * The unified abstract driver contract consumed by `@testspectra/matchers` element proxies,
+ * fluent matchers, and the `Spectra` automation object. Every platform-specific driver
+ * (`WebCdpDriverBridge`, `AndroidTcpDriverBridge`) implements this interface so that the
+ * DSL layer contains zero platform branching.
+ */
+import type { CDPNetworkEntry, MockInterceptHandle, MockRule, ScopedSelector, ScrollOptions, SpectraBrowserBridge, SwipeOptions } from './types.js';
+/**
+ * Runtime configuration injected by the Rust orchestrator via `globalThis.__TESTSPECTRA_CONFIG__`.
+ */
+export interface RuntimeWorkerConfig {
+    workerId?: number;
+    rootDir: string;
+    testFilePath?: string;
+    testFiles?: Array<{
+        id: string;
+        title: string;
+        filePath: string;
+        suite: string;
+    }>;
+    activePlatform: string;
+    configuredBaseUrl: string;
+    cdpWsUrl: string;
+    driverServerUrl: string;
+    manifest?: Record<string, any>;
+    /** Target app package (Android). Paired with androidSerial/adbPath for on-demand adb actions. */
+    appPackage?: string;
+    /** Target adb device serial for this worker (Android only). */
+    androidSerial?: string;
+    /** Resolved `adb` binary path (Android only), paired with androidSerial above. */
+    adbPath?: string;
+    /** Host port this worker's own MobileMockProxyServer should listen on (Android only) — derived
+     * per-device the same way androidSerial/the driver-server port already are, so each device in
+     * a multi-device run gets its own proxy instead of every worker racing for one shared port. */
+    mockProxyPort?: number;
+    implicitWaitMs?: number;
+    timeoutMs?: number;
+    stepDelayMs?: number;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.networkMonitoringEnabled` (default: true). */
+    networkMonitoringEnabled?: boolean;
+    /** Mirrors `spectra.config.ts`'s `executionConfig.monitoredDomains`. Empty/absent = capture all. */
+    monitoredDomains?: {
+        domain: string;
+        enabled: boolean;
+    }[];
+    /** Mirrors `spectra.config.ts`'s `executionConfig.environmentVariables`. */
+    environmentVariables?: Record<string, string>;
+}
+/**
+ * Cross-cutting shared runtime state injected into the assembled worker script.
+ *
+ * The worker runtime is emitted as a single self-contained TypeScript module (concatenated
+ * by the Rust orchestrator). This object is created once in the harness prelude and mutated
+ * in place (`activeDriver` is bound after the platform bridge is instantiated), so fragments
+ * access it lazily at call-time through `globalThis.__TS_RUNTIME__`.
+ */
+export interface RuntimeContext {
+    config: RuntimeWorkerConfig;
+    activeDriver: PlatformDriverBridge | null;
+    mobileMockRules: MockRule[];
+    lastFocusedSelector: string | null;
+    currentTargetItem?: any;
+    emitEvent(tag: string, payload: string): void;
+    trackStep<T>(category: 'action' | 'assertion' | 'browser', payloadObj: Record<string, any>, fn: () => Promise<T>): Promise<T>;
+    pollCondition(fn: () => Promise<boolean> | boolean, timeoutMs?: number, intervalMs?: number): Promise<boolean>;
+    getImplicitWaitMs(): number;
+    getAssertionTimeoutMs(): number;
+    matchesUrlPattern(pattern: string, url: string): boolean;
+    /** Whether a captured network request/response for `url` should be recorded, per
+     * `config.networkMonitoringEnabled` / `config.monitoredDomains`. */
+    shouldRecordNetworkEntry(url: string): boolean;
+    createMockHandle(rule: MockRule): MockInterceptHandle;
+    parseMockRule(patternOrOptions?: any, maybeMethodOrHandler?: any, maybeFixture?: any, maybeOptions?: any): MockRule;
+    recordDuration?: (label: string, category: string, durationMs: number, extra?: Record<string, unknown>) => void;
+    withDuration?: <T>(label: string, category: string, fn: () => Promise<T>, extra?: Record<string, unknown>) => Promise<T>;
+    durationLogPath?: string | null;
+    createElementActions?: (selector: string | ScopedSelector, index: number | null) => Record<string, any>;
+    createElementState?: (selector: string | ScopedSelector, index: number | null) => Record<string, any>;
+    createElementAssertions?: (selector: string | ScopedSelector, index: number | null, state: Record<string, any>) => Record<string, any>;
+    createElementProxy?: (selector: string | ScopedSelector, index?: number | null) => any;
+    createCollectionProxy?: (selector: string | ScopedSelector) => any;
+    resolveTargetProxy?: (target: any) => any;
+    buildSpectra?: () => any;
+    cdpBridgeClass?: any;
+    androidBridgeClass?: any;
+    mobileMockProxyClass?: any;
+    mobileMockProxy?: any;
+    beforeHook?: (() => Promise<void> | void) | null;
+    afterHook?: (() => Promise<void> | void) | null;
+    beforeEachHook?: (() => Promise<void> | void) | null;
+    afterEachHook?: (() => Promise<void> | void) | null;
+    bootstrapEnvironment?: () => Promise<void>;
+    runSuite?: () => Promise<void>;
+}
+/**
+ * The unified platform driver contract. It extends the browser surface documented in
+ * `SpectraBrowserBridge` (navigation, script execution, network interception, browser-level
+ * assertions) with the element interaction and state-inspection methods needed by the DSL,
+ * so the `tools/matchers` layer never branches on `activePlatform`.
+ */
+export interface PlatformDriverBridge extends SpectraBrowserBridge {
+    /** Establishes connection to the underlying runtime endpoint (WebSocket / TCP Socket). */
+    connect(): Promise<void>;
+    /** Cleans up open connections, servers, and listeners. */
+    close(): Promise<void>;
+    /** Navigates to target URL (Web) or Activity / Deep Link (Android). */
+    navigate(targetUrl: string): Promise<void>;
+    /** Navigates one step backward in browser/navigation history. */
+    back(): Promise<void>;
+    /** Navigates one step forward in browser/navigation history. */
+    forward(): Promise<void>;
+    /** Reloads / refreshes the current active page. */
+    refresh(): Promise<void>;
+    /** Sets the browser viewport dimensions (width and height in pixels). */
+    setViewport(width: number, height: number): Promise<void>;
+    /** Pauses execution for the given duration in milliseconds. */
+    pause(ms: number): Promise<void>;
+    /** Intercepts and mocks HTTP network requests matching the specified pattern or options. */
+    intercept(patternOrOptions: string | {
+        url: string;
+        method?: string;
+        response?: unknown;
+    }, method?: string, fixture?: unknown, options?: {
+        statusCode?: number;
+        headers?: Record<string, string>;
+        delayMs?: number;
+    }): Promise<MockInterceptHandle>;
+    click(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    doubleClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    rightClick(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    setValue(selector: string | ScopedSelector, value: unknown, index?: number | null): Promise<void>;
+    clearValue(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    select(selector: string | ScopedSelector, option: string, index?: number | null): Promise<void>;
+    hover(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    focus(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    dragDrop(sourceSelector: string | ScopedSelector, targetSelector: string, sourceIndex?: number | null): Promise<void>;
+    longPress(selector: string | ScopedSelector, duration: number, index?: number | null): Promise<void>;
+    scrollIntoView(selector: string | ScopedSelector, index?: number | null): Promise<void>;
+    getText(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+    getValue(selector: string | ScopedSelector, index?: number | null): Promise<string>;
+    isDisplayed(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isExisting(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isEnabled(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isSelected(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isFocused(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    isClickable(selector: string | ScopedSelector, index?: number | null): Promise<boolean>;
+    hasClass(selector: string | ScopedSelector, className: string, index?: number | null): Promise<boolean>;
+    getAttribute(selector: string | ScopedSelector, name: string, index?: number | null): Promise<string | null>;
+    getCSSProperty(selector: string | ScopedSelector, name: string, index?: number | null): Promise<{
+        value: string;
+    }>;
+    count(selector: string | ScopedSelector): Promise<number>;
+    pressKey(key: string | number): Promise<void>;
+    scroll(options?: ScrollOptions): Promise<void>;
+    swipe(options: SwipeOptions): Promise<void>;
+    /**
+     * Grants an Android runtime permission on demand (e.g. right after confirming an in-app
+     * rationale dialog), via `adb shell pm grant` on the host. No-op on platforms without an
+     * OS-level runtime permission model (e.g. web).
+     */
+    grantPermission(name: string): Promise<void>;
+    /** Clears all active network interception rules. */
+    clearMocks(): void;
+    mockRules: MockRule[];
+    consoleErrors: string[];
+    recordedNetwork: CDPNetworkEntry[];
+}
+declare global {
+    var __TS_RUNTIME__: RuntimeContext;
+}

package/dist/contract.js

@@ -0,0 +1,10 @@
+/**
+ * @packageDocumentation
+ * # PlatformDriverBridge Contract
+ *
+ * The unified abstract driver contract consumed by `@testspectra/matchers` element proxies,
+ * fluent matchers, and the `Spectra` automation object. Every platform-specific driver
+ * (`WebCdpDriverBridge`, `AndroidTcpDriverBridge`) implements this interface so that the
+ * DSL layer contains zero platform branching.
+ */
+export {};

package/dist/index.d.ts

@@ -5,4 +5,5 @@
  * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
 export * from './types.js';
+export * from './contract.js';
 export * from './proto.js';

package/dist/index.js

@@ -5,4 +5,5 @@
  * Canonical TypeScript contracts, action/assertion types, and ambient type definitions for TestSpectra.
  */
 export * from './types.js';
+export * from './contract.js';
 export * from './proto.js';

package/dist/proto.d.ts

@@ -16,6 +16,14 @@ declare global {
      * Global step library injected by TestSpectra runner.
      */
     var Step: Record<string, any>;
+    /**
+     * Typed shape of `Spectra.env`. Empty by default — each `spectra.config.ts`
+     * `executionConfig.environmentVariables` key is merged in as a `readonly <KEY>: string` member
+     * by the CLI's generated `.testspectra/types/env.d.ts` (plain TypeScript interface merging, the
+     * same mechanism `@types/node` uses to let projects augment `NodeJS.ProcessEnv`).
+     */
+    interface SpectraEnv {
+    }
     namespace WebdriverIO {
         interface Browser extends SpectraBrowserBridge {
         }

package/dist/runner/collection.d.ts

@@ -1,4 +1,4 @@
-import { CollectionReceiverAssertions } from '../types.js';
+import { CollectionReceiverAssertions, MultiElementMatcher } from '../types.js';
 import { SingleElementRunner } from './single.js';
 /**
  * Fluent assertion, filtering, and iteration runner for multi-element collections.
@@ -26,7 +26,6 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
     private _selector;
     private _assertions;
     constructor(selector: string);
-    private _pushAssertion;
     /**
      * Asserts that the collection contains exactly `count` elements.
      */
@@ -51,6 +50,19 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      * Asserts that the collection is not empty (contains at least 1 element).
      */
     shouldNotBeEmpty(): this;
+    /**
+     * Queues an assertion matcher against the multi-element collection.
+     *
+     * @param matcher - Multi-element matcher string (e.g. `'have.length'`, `'be.empty'`).
+     * @param args - Expected values or limits for the matcher.
+     * @example
+     * ```ts
+     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
+     * await Spectra.getAll(".error-badge").should("be.empty");
+     * ```
+     * @returns Current collection runner instance for chaining.
+     */
+    should(matcher: MultiElementMatcher, ...args: any[]): this;
     /**
      * Returns a `SingleElementRunner` targeting the element at the specified 0-based index.
      *
@@ -77,7 +89,7 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      *
      * @example
      * ```ts
-     * await Spectra.getAll(".step-indicator").last().shouldHaveClass("current");
+     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
      * ```
      * @returns `SingleElementRunner` for the last element.
      */
@@ -89,7 +101,7 @@ export declare class MultiElementRunner implements PromiseLike<void>, Collection
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.shouldBeVisible();
+     *   await item.should("be.visible");
      * });
      * ```
      */

package/dist/runner/collection.js

@@ -29,46 +29,58 @@ export class MultiElementRunner {
     constructor(selector) {
         this._selector = selector;
     }
-    _pushAssertion(matcher, args = []) {
-        this._assertions.push({ matcher, args });
-        return this;
-    }
     // --- Collection Assertions ---
     /**
      * Asserts that the collection contains exactly `count` elements.
      */
     shouldHaveLength(count) {
-        return this._pushAssertion('have.length', [count]);
+        return this.should('have.length', count);
     }
     /**
      * Asserts that the collection does not contain `count` elements.
      */
     shouldNotHaveLength(count) {
-        return this._pushAssertion('not.have.length', [count]);
+        return this.should('not.have.length', count);
     }
     /**
      * Asserts that the collection contains more than `min` elements.
      */
     shouldHaveLengthGreaterThan(min) {
-        return this._pushAssertion('have.length.greaterThan', [min]);
+        return this.should('have.length.greaterThan', min);
     }
     /**
      * Asserts that the collection contains less than `max` elements.
      */
     shouldHaveLengthLessThan(max) {
-        return this._pushAssertion('have.length.lessThan', [max]);
+        return this.should('have.length.lessThan', max);
     }
     /**
      * Asserts that the collection is empty (contains 0 elements).
      */
     shouldBeEmpty() {
-        return this._pushAssertion('be.empty');
+        return this.should('be.empty');
     }
     /**
      * Asserts that the collection is not empty (contains at least 1 element).
      */
     shouldNotBeEmpty() {
-        return this._pushAssertion('not.be.empty');
+        return this.should('not.be.empty');
+    }
+    /**
+     * Queues an assertion matcher against the multi-element collection.
+     *
+     * @param matcher - Multi-element matcher string (e.g. `'have.length'`, `'be.empty'`).
+     * @param args - Expected values or limits for the matcher.
+     * @example
+     * ```ts
+     * await Spectra.getAll(".product-card").should("have.length.greaterThan", 0);
+     * await Spectra.getAll(".error-badge").should("be.empty");
+     * ```
+     * @returns Current collection runner instance for chaining.
+     */
+    should(matcher, ...args) {
+        this._assertions.push({ matcher, args });
+        return this;
     }
     // --- Item Navigation ---
     /**
@@ -110,7 +122,7 @@ export class MultiElementRunner {
      *
      * @example
      * ```ts
-     * await Spectra.getAll(".step-indicator").last().shouldHaveClass("current");
+     * await Spectra.getAll(".step-indicator").last().should("have.class", "current");
      * ```
      * @returns `SingleElementRunner` for the last element.
      */
@@ -135,7 +147,7 @@ export class MultiElementRunner {
      * @example
      * ```ts
      * await Spectra.getAll(".checkbox").each(async (item, index) => {
-     *   await item.shouldBeVisible();
+     *   await item.should("be.visible");
      * });
      * ```
      */

package/dist/runner/single.d.ts

@@ -1,4 +1,4 @@
-import { ElementReceiverAssertions, ElementTarget, TypeOptions } from '../types.js';
+import { ElementReceiverAssertions, ElementTarget, SingleElementMatcher, TypeOptions } from '../types.js';
 /**
  * Fluent interaction and assertion runner for a single element or browser context.
  *
@@ -122,7 +122,6 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      * Scrolls the target element into view.
      */
     scrollIntoView(): this;
-    private _pushAssertion;
     /**
      * Asserts that the target element is displayed and visible to the user.
      */
@@ -227,6 +226,33 @@ export declare class SingleElementRunner implements PromiseLike<void>, ElementRe
      * Asserts that the target element does not have the specified computed CSS property value.
      */
     shouldNotHaveCss(property: string, value: string): this;
+    /**
+     * Queues an assertion matcher against the current target element or page.
+     *
+     * @param matcher - Single element matcher string (e.g. `'be.visible'`, `'have.text'`).
+     * @param args - Additional parameters for the matcher (e.g. expected text or value).
+     * @example
+     * ```ts
+     * await Spectra.get("#status-badge").should("be.visible");
+     * await Spectra.get("#username").should("have.value", "alice");
+     * await Spectra.get("#banner").should("have.class", "alert-success");
+     * ```
+     * @returns Current runner instance for method chaining.
+     */
+    should(matcher: SingleElementMatcher, ...args: any[]): this;
+    /**
+     * Queues an assertion matcher targeting a specific element.
+     *
+     * @param target - Custom element target for this specific assertion.
+     * @param matcher - Single element matcher string.
+     * @param args - Additional parameters for the matcher.
+     * @example
+     * ```ts
+     * await Spectra.should(LoginPage.submitBtn, "be.enabled");
+     * ```
+     * @returns Current runner instance for method chaining.
+     */
+    should(target: ElementTarget, matcher: SingleElementMatcher, ...args: any[]): this;
     /**
      * Standard Promise `then` implementation.
      * Executes queued action first (if any), followed sequentially by all queued assertions.

package/dist/runner/single.js

@@ -242,172 +242,191 @@ export class SingleElementRunner {
         };
         return this;
     }
-    _pushAssertion(matcher, args = []) {
-        this._assertions.push({
-            target: this._target,
-            matcher,
-            args,
-        });
-        return this;
-    }
     // --- Fluent Assertion Matchers ---
     /**
      * Asserts that the target element is displayed and visible to the user.
      */
     shouldBeVisible() {
-        return this._pushAssertion('be.visible');
+        return this.should('be.visible');
     }
     /**
      * Asserts that the target element is not displayed or hidden from view.
      */
     shouldNotBeVisible() {
-        return this._pushAssertion('not.be.visible');
+        return this.should('not.be.visible');
     }
     /**
      * Asserts that the target element exists in the DOM.
      */
     shouldExist() {
-        return this._pushAssertion('exist');
+        return this.should('exist');
     }
     /**
      * Asserts that the target element does not exist in the DOM.
      */
     shouldNotExist() {
-        return this._pushAssertion('not.exist');
+        return this.should('not.exist');
     }
     /**
      * Asserts that the target element is clickable.
      */
     shouldBeClickable() {
-        return this._pushAssertion('be.clickable');
+        return this.should('be.clickable');
     }
     /**
      * Asserts that the target element is not clickable.
      */
     shouldNotBeClickable() {
-        return this._pushAssertion('not.be.clickable');
+        return this.should('not.be.clickable');
     }
     /**
      * Asserts that the target element is enabled (not disabled).
      */
     shouldBeEnabled() {
-        return this._pushAssertion('be.enabled');
+        return this.should('be.enabled');
     }
     /**
      * Asserts that the target element is disabled.
      */
     shouldBeDisabled() {
-        return this._pushAssertion('be.disabled');
+        return this.should('be.disabled');
     }
     /**
      * Asserts that the target checkbox or radio element is checked.
      */
     shouldBeChecked() {
-        return this._pushAssertion('be.checked');
+        return this.should('be.checked');
     }
     /**
      * Asserts that the target checkbox or radio element is not checked.
      */
     shouldNotBeChecked() {
-        return this._pushAssertion('not.be.checked');
+        return this.should('not.be.checked');
     }
     /**
      * Asserts that the target element currently has focus.
      */
     shouldBeFocused() {
-        return this._pushAssertion('be.focused');
+        return this.should('be.focused');
     }
     /**
      * Asserts that the target element does not have focus.
      */
     shouldNotBeFocused() {
-        return this._pushAssertion('not.be.focused');
+        return this.should('not.be.focused');
     }
     /**
      * Asserts that the target element has exact inner text matching the expected value.
      */
     shouldHaveText(expected) {
-        return this._pushAssertion('have.text', [expected]);
+        return this.should('have.text', expected);
     }
     /**
      * Asserts that the target element does not have inner text matching the expected value.
      */
     shouldNotHaveText(expected) {
-        return this._pushAssertion('not.have.text', [expected]);
+        return this.should('not.have.text', expected);
     }
     /**
      * Asserts that the target element's text contains the given substring.
      */
     shouldContainText(substring) {
-        return this._pushAssertion('contain.text', [substring]);
+        return this.should('contain.text', substring);
     }
     /**
      * Asserts that the target element's text does not contain the given substring.
      */
     shouldNotContainText(substring) {
-        return this._pushAssertion('not.contain.text', [substring]);
+        return this.should('not.contain.text', substring);
     }
     /**
      * Asserts that the target input element has the exact expected value.
      */
     shouldHaveValue(value) {
-        return this._pushAssertion('have.value', [value]);
+        return this.should('have.value', value);
     }
     /**
      * Asserts that the target input element does not have the expected value.
      */
     shouldNotHaveValue(value) {
-        return this._pushAssertion('not.have.value', [value]);
+        return this.should('not.have.value', value);
     }
     /**
      * Asserts that the target input element's value contains the given substring.
      */
     shouldContainValue(substring) {
-        return this._pushAssertion('contain.value', [substring]);
+        return this.should('contain.value', substring);
     }
     /**
      * Asserts that the target input element's value does not contain the given substring.
      */
     shouldNotContainValue(substring) {
-        return this._pushAssertion('not.contain.value', [substring]);
+        return this.should('not.contain.value', substring);
     }
     /**
      * Asserts that the target element has the specified HTML attribute and optional value.
      */
     shouldHaveAttribute(name, value) {
-        return value !== undefined
-            ? this._pushAssertion('have.attr', [name, value])
-            : this._pushAssertion('have.attr', [name]);
+        return value !== undefined ? this.should('have.attr', name, value) : this.should('have.attr', name);
     }
     /**
      * Asserts that the target element does not have the specified HTML attribute.
      */
     shouldNotHaveAttribute(name) {
-        return this._pushAssertion('not.have.attr', [name]);
+        return this.should('not.have.attr', name);
     }
     /**
      * Asserts that the target element has the specified CSS class.
      */
     shouldHaveClass(className) {
-        return this._pushAssertion('have.class', [className]);
+        return this.should('have.class', className);
     }
     /**
      * Asserts that the target element does not have the specified CSS class.
      */
     shouldNotHaveClass(className) {
-        return this._pushAssertion('not.have.class', [className]);
+        return this.should('not.have.class', className);
     }
     /**
      * Asserts that the target element has the specified computed CSS property value.
      */
     shouldHaveCss(property, value) {
-        return this._pushAssertion('have.css', [property, value]);
+        return this.should('have.css', property, value);
     }
     /**
      * Asserts that the target element does not have the specified computed CSS property value.
      */
     shouldNotHaveCss(property, value) {
-        return this._pushAssertion('not.have.css', [property, value]);
+        return this.should('not.have.css', property, value);
+    }
+    should(a, b, ...rest) {
+        const isFirstArgMatcher = typeof a === 'string' &&
+            (a.includes('.') ||
+                a.includes('exist') ||
+                a.includes('visible') ||
+                a.includes('clickable') ||
+                a.includes('focused') ||
+                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 ---
     /**

package/dist/semantic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/matchers - Semantic Natural Language Formatter
+ *
+ * Formats commands, actions, and assertions into clean, grammatically
+ * correct English sentences for real-time reporting.
+ */
+export declare function formatSemanticTarget(target: any, isCollection?: boolean): string;
+export declare function formatSemanticAction(action: string, target: any, args?: any[]): string;
+export declare function formatSemanticMatcher(target: any, matcher: string, args?: any[], isCollection?: boolean): string;
+export declare function formatSemanticBrowser(method: string, args?: any[]): string;