@testspectra/matchers 1.0.69 → 1.1.0

package/dist/intercept/mock-handle.js

@@ -0,0 +1,124 @@
+export class MockHandle {
+    rule;
+    onceQueue = [];
+    defaultResponse = null;
+    abortReason = null;
+    interceptedCalls = [];
+    waitingCallers = [];
+    constructor(rule) {
+        this.rule = rule;
+        if (rule.response) {
+            this.defaultResponse = rule.response;
+        }
+    }
+    /**
+     * Updates the default mock response for all subsequent matching requests.
+     */
+    respondWith(response) {
+        this.defaultResponse = response;
+        this.abortReason = null;
+        return this;
+    }
+    /**
+     * Queues a one-time mock response for the next matching request (FIFO queue for polling/retries).
+     */
+    respondOnce(response) {
+        this.onceQueue.push(response);
+        return this;
+    }
+    /**
+     * Simulates a network failure or connection abort.
+     */
+    abort(errorCode = 'Aborted') {
+        this.abortReason = errorCode;
+        return this;
+    }
+    /**
+     * Total matching requests intercepted so far.
+     */
+    get callCount() {
+        return this.interceptedCalls.length;
+    }
+    /**
+     * Historical array of intercepted requests.
+     */
+    get calls() {
+        return [...this.interceptedCalls];
+    }
+    /**
+     * Awaits until a matching request arrives or times out.
+     */
+    async waitForCall(options = {}) {
+        const timeout = options.timeout ?? 5000;
+        const targetCount = options.count ?? 1;
+        if (this.interceptedCalls.length >= targetCount) {
+            return this.interceptedCalls[targetCount - 1];
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const idx = this.waitingCallers.findIndex((w) => w.timer === timer);
+                if (idx !== -1)
+                    this.waitingCallers.splice(idx, 1);
+                reject(new Error(`waitForCall timed out after ${timeout}ms. Expected ${targetCount} call(s), but received ${this.interceptedCalls.length}.`));
+            }, timeout);
+            this.waitingCallers.push({
+                targetCount,
+                resolve,
+                reject,
+                timer,
+            });
+        });
+    }
+    /**
+     * Internal fulfillment method called when a request matches this rule.
+     */
+    async matchAndFulfill(req) {
+        this.interceptedCalls.push(req);
+        // Notify any waiting callers whose count requirement is met
+        for (let i = this.waitingCallers.length - 1; i >= 0; i--) {
+            const waiter = this.waitingCallers[i];
+            if (this.interceptedCalls.length >= waiter.targetCount) {
+                clearTimeout(waiter.timer);
+                waiter.resolve(req);
+                this.waitingCallers.splice(i, 1);
+            }
+        }
+        if (this.abortReason) {
+            return { aborted: this.abortReason };
+        }
+        // 1. Shift from FIFO onceQueue if available
+        if (this.onceQueue.length > 0) {
+            const nextOnce = this.onceQueue.shift();
+            return { response: nextOnce };
+        }
+        // 2. Fall back to default response
+        if (typeof this.defaultResponse === 'function') {
+            const res = await this.defaultResponse(req);
+            return { response: res };
+        }
+        if (this.defaultResponse) {
+            return { response: this.defaultResponse };
+        }
+        // Default 200 OK
+        return {
+            response: {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+                body: {},
+            },
+        };
+    }
+    /**
+     * Resets local state and queued responses.
+     */
+    clear() {
+        this.onceQueue = [];
+        this.interceptedCalls = [];
+        this.abortReason = null;
+        for (const waiter of this.waitingCallers) {
+            clearTimeout(waiter.timer);
+            waiter.reject(new Error('Mock rule cleared while waiting for call'));
+        }
+        this.waitingCallers = [];
+    }
+}

package/dist/intercept/mock-registry.d.ts

@@ -0,0 +1,18 @@
+import { MockHandle } from './mock-handle.js';
+import { InterceptRule, RecordedNetworkResource } from './types.js';
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchesUrl(pattern: string | RegExp, url: string): boolean;
+export declare function matchesMethod(ruleMethod?: string, reqMethod?: string): boolean;
+export declare class MockRegistry {
+    private static instance;
+    private handles;
+    private recordedResources;
+    static getInstance(): MockRegistry;
+    register(rule: InterceptRule): MockHandle;
+    findMatchingHandle(method: string, url: string): MockHandle | undefined;
+    clear(): void;
+    recordResource(resource: RecordedNetworkResource): void;
+    getRecordedResources(): RecordedNetworkResource[];
+    clearRecordedResources(): void;
+    exportNetworkResources(filePath: string): void;
+}

package/dist/intercept/mock-registry.js

@@ -0,0 +1,97 @@
+import fs from 'fs';
+import path from 'path';
+import { MockHandle } from './mock-handle.js';
+export function globToRegExp(glob) {
+    let regexStr = '';
+    let i = 0;
+    while (i < glob.length) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            regexStr += '.*';
+            i += 2;
+        }
+        else if (c === '*') {
+            regexStr += '[^/]*';
+            i += 1;
+        }
+        else if (['.', '?', '+', '^', '$', '[', ']', '(', ')', '{', '}', '|', '\\'].includes(c)) {
+            regexStr += `\\${c}`;
+            i += 1;
+        }
+        else {
+            regexStr += c;
+            i += 1;
+        }
+    }
+    // If glob does not start with protocol and does not start with wildcard, allow leading domain
+    if (!glob.startsWith('http://') && !glob.startsWith('https://') && !glob.startsWith('*')) {
+        return new RegExp(`(?:https?://[^/]+)?${regexStr}(?:\\?.*)?$`);
+    }
+    return new RegExp(`^${regexStr}(?:\\?.*)?$`);
+}
+export function matchesUrl(pattern, url) {
+    if (pattern instanceof RegExp) {
+        return pattern.test(url);
+    }
+    if (pattern === url) {
+        return true;
+    }
+    try {
+        const parsed = new URL(url, 'http://localhost');
+        if (pattern === parsed.pathname || pattern === `${parsed.pathname}${parsed.search}`) {
+            return true;
+        }
+    }
+    catch { }
+    const reg = globToRegExp(pattern);
+    return reg.test(url);
+}
+export function matchesMethod(ruleMethod, reqMethod = 'GET') {
+    if (!ruleMethod || ruleMethod.toUpperCase() === 'ALL') {
+        return true;
+    }
+    return ruleMethod.toUpperCase() === reqMethod.toUpperCase();
+}
+export class MockRegistry {
+    static instance;
+    handles = [];
+    recordedResources = [];
+    static getInstance() {
+        if (!MockRegistry.instance) {
+            MockRegistry.instance = new MockRegistry();
+        }
+        return MockRegistry.instance;
+    }
+    register(rule) {
+        const handle = new MockHandle(rule);
+        this.handles.unshift(handle);
+        return handle;
+    }
+    findMatchingHandle(method, url) {
+        return this.handles.find((h) => {
+            return matchesMethod(h.rule.method, method) && matchesUrl(h.rule.url, url);
+        });
+    }
+    clear() {
+        for (const h of this.handles) {
+            h.clear();
+        }
+        this.handles = [];
+    }
+    recordResource(resource) {
+        this.recordedResources.push(resource);
+    }
+    getRecordedResources() {
+        return [...this.recordedResources];
+    }
+    clearRecordedResources() {
+        this.recordedResources = [];
+    }
+    exportNetworkResources(filePath) {
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(filePath, JSON.stringify(this.recordedResources, null, 2), 'utf-8');
+    }
+}

package/dist/intercept/types.d.ts

@@ -0,0 +1,43 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS' | 'ALL';
+export type NetworkAbortReason = 'Failed' | 'Aborted' | 'TimedOut' | 'ConnectionReset' | 'AccessDenied';
+export interface MockResponse {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: any;
+    delayMs?: number;
+}
+export interface InterceptedRequest {
+    id: string;
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: any;
+    timestamp: number;
+}
+export interface InterceptRule {
+    url: string | RegExp;
+    method?: HttpMethod;
+    response?: MockResponse | ((request: InterceptedRequest) => MockResponse | Promise<MockResponse>);
+}
+export interface NetworkResourceTiming {
+    dns: number;
+    tcp: number;
+    ssl: number;
+    ttfb: number;
+    download: number;
+    total: number;
+}
+export interface RecordedNetworkResource {
+    id: string;
+    url: string;
+    method: string;
+    status: number;
+    statusText: string;
+    resourceType: string;
+    requestHeaders?: Record<string, string>;
+    responseHeaders?: Record<string, string>;
+    requestBody?: any;
+    responseBody?: any;
+    timing: NetworkResourceTiming;
+    transferSize: number;
+}

package/dist/intercept/types.js

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

package/dist/matchers.d.ts

@@ -1,4 +1,4 @@
-import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from "./types.js";
+import { SingleElementMatcher, MultiElementMatcher, ElementTarget } from './types.js';
 /**
  * Resolves an ElementTarget (selector string, WebdriverIO.Element, or ChainablePromiseElement)
  * to an actionable WebdriverIO.Element.
@@ -23,3 +23,7 @@ export declare function executeSingleMatcher(target: ElementTarget | undefined,
  * @param args - Expected values or count limits.
  */
 export declare function executeMultiMatcher(selector: string, matcher: MultiElementMatcher, args: any[]): Promise<void>;
+/**
+ * Executes browser-level context assertions.
+ */
+export declare function executeBrowserAssertion(assertion: 'shouldHaveUrl' | 'shouldContainUrl' | 'shouldHaveTitle' | 'shouldContainTitle' | 'shouldBePageLoaded' | 'shouldHaveNoConsoleErrors', args?: any[]): Promise<void>;

package/dist/matchers.js

@@ -6,7 +6,7 @@
  * @returns Resolved WebdriverIO.Element instance.
  */
 export async function resolveElement(target) {
-    if (typeof target === "string") {
+    if (typeof target === 'string') {
         const el = await $(target);
         return el;
     }
@@ -21,23 +21,20 @@ export async function resolveElement(target) {
  * @param args - Arguments passed to the matcher.
  */
 export async function executeSingleMatcher(target, matcher, args) {
-    const isBrowserLevel = matcher === "have.url" ||
-        matcher === "contain.url" ||
-        matcher === "have.title" ||
-        matcher === "contain.title";
+    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":
+            case 'have.url':
                 await expect(browser).toHaveUrl(expected);
                 break;
-            case "contain.url":
+            case 'contain.url':
                 await expect(browser).toHaveUrl(expect.stringContaining(expected));
                 break;
-            case "have.title":
+            case 'have.title':
                 await expect(browser).toHaveTitle(expected);
                 break;
-            case "contain.title":
+            case 'contain.title':
                 await expect(browser).toHaveTitle(expect.stringContaining(expected));
                 break;
         }
@@ -48,48 +45,75 @@ export async function executeSingleMatcher(target, matcher, args) {
     }
     const el = await resolveElement(target);
     switch (matcher) {
-        case "be.visible":
+        case 'be.visible':
             await expect(el).toBeDisplayed();
             break;
-        case "not.be.visible":
+        case 'not.be.visible':
             await expect(el).not.toBeDisplayed();
             break;
-        case "exist":
+        case 'exist':
             await expect(el).toExist();
             break;
-        case "not.exist":
+        case 'not.exist':
             await expect(el).not.toExist();
             break;
-        case "be.enabled":
+        case 'be.clickable':
+            await expect(el).toBeClickable();
+            break;
+        case 'not.be.clickable':
+            await expect(el).not.toBeClickable();
+            break;
+        case 'be.enabled':
             await expect(el).toBeEnabled();
             break;
-        case "be.disabled":
+        case 'be.disabled':
             await expect(el).toBeDisabled();
             break;
-        case "be.checked":
-        case "be.selected":
+        case 'be.checked':
+        case 'be.selected':
             await expect(el).toBeSelected();
             break;
-        case "not.be.checked":
-        case "not.be.selected":
+        case 'not.be.checked':
+        case 'not.be.selected':
             await expect(el).not.toBeSelected();
             break;
-        case "have.value":
+        case 'be.focused':
+            await expect(el).toBeFocused();
+            break;
+        case 'not.be.focused':
+            await expect(el).not.toBeFocused();
+            break;
+        case 'have.value':
             await expect(el).toHaveValue(args[0]);
             break;
-        case "contain.value":
+        case 'not.have.value':
+            await expect(el).not.toHaveValue(args[0]);
+            break;
+        case 'contain.value':
             await expect(el).toHaveValue(expect.stringContaining(args[0]));
             break;
-        case "have.text":
+        case 'not.contain.value':
+            await expect(el).not.toHaveValue(expect.stringContaining(args[0]));
+            break;
+        case 'have.text':
             await expect(el).toHaveText(args[0]);
             break;
-        case "contain.text":
+        case 'not.have.text':
+            await expect(el).not.toHaveText(args[0]);
+            break;
+        case 'contain.text':
             await expect(el).toHaveText(expect.stringContaining(args[0]));
             break;
-        case "have.class":
+        case 'not.contain.text':
+            await expect(el).not.toHaveText(expect.stringContaining(args[0]));
+            break;
+        case 'have.class':
             await expect(el).toHaveElementClass(args[0]);
             break;
-        case "have.attr":
+        case 'not.have.class':
+            await expect(el).not.toHaveElementClass(args[0]);
+            break;
+        case 'have.attr':
             if (args.length >= 2) {
                 await expect(el).toHaveAttribute(args[0], args[1]);
             }
@@ -97,6 +121,15 @@ export async function executeSingleMatcher(target, matcher, args) {
                 await expect(el).toHaveAttribute(args[0]);
             }
             break;
+        case 'not.have.attr':
+            await expect(el).not.toHaveAttribute(args[0]);
+            break;
+        case 'have.css':
+            await expect(el).toHaveStyle({ [args[0]]: args[1] });
+            break;
+        case 'not.have.css':
+            await expect(el).not.toHaveStyle({ [args[0]]: args[1] });
+            break;
         default:
             throw new Error(`Unsupported matcher: ${matcher}`);
     }
@@ -111,19 +144,73 @@ export async function executeSingleMatcher(target, matcher, args) {
 export async function executeMultiMatcher(selector, matcher, args) {
     const elements = await $$(selector);
     switch (matcher) {
-        case "have.length":
+        case 'have.length':
             await expect(elements).toBeElementsArrayOfSize(args[0]);
             break;
-        case "have.length.greaterThan":
+        case 'not.have.length':
+            await expect(elements).not.toBeElementsArrayOfSize(args[0]);
+            break;
+        case 'have.length.greaterThan':
             await expect(elements).toBeElementsArrayOfSize({ gte: args[0] + 1 });
             break;
-        case "be.empty":
+        case 'have.length.lessThan':
+            await expect(elements).toBeElementsArrayOfSize({ lte: Math.max(0, args[0] - 1) });
+            break;
+        case 'be.empty':
             await expect(elements).toBeElementsArrayOfSize(0);
             break;
-        case "exist":
+        case 'not.be.empty':
+            await expect(elements).toBeElementsArrayOfSize({ gte: 1 });
+            break;
+        case 'exist':
             await expect(elements).toBeElementsArrayOfSize({ gte: 1 });
             break;
         default:
             throw new Error(`Unsupported multi-element matcher: ${matcher}`);
     }
 }
+/**
+ * Executes browser-level context assertions.
+ */
+export async function executeBrowserAssertion(assertion, args = []) {
+    const b = typeof browser !== 'undefined' ? browser : globalThis.browser;
+    if (!b)
+        throw new Error('WebdriverIO browser instance is not available.');
+    switch (assertion) {
+        case 'shouldHaveUrl':
+            await expect(b).toHaveUrl(args[0]);
+            break;
+        case 'shouldContainUrl':
+            await expect(b).toHaveUrl(new RegExp(String(args[0]).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            break;
+        case 'shouldHaveTitle':
+            await expect(b).toHaveTitle(args[0]);
+            break;
+        case 'shouldContainTitle':
+            await expect(b).toHaveTitle(new RegExp(String(args[0]).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            break;
+        case 'shouldBePageLoaded':
+            await b.waitUntil(async () => {
+                const state = await b.execute(() => document.readyState);
+                return state === 'complete';
+            }, { timeout: 10000, timeoutMsg: 'Expected page to be fully loaded (document.readyState === "complete")' });
+            break;
+        case 'shouldHaveNoConsoleErrors':
+            try {
+                const logs = await b.getLogs?.('browser');
+                if (Array.isArray(logs)) {
+                    const severeLogs = logs.filter((log) => log.level === 'SEVERE');
+                    if (severeLogs.length > 0) {
+                        throw new Error(`Browser console has errors: ${severeLogs.map((l) => l.message).join('; ')}`);
+                    }
+                }
+            }
+            catch (err) {
+                if (err.message && err.message.includes('Browser console has errors'))
+                    throw err;
+            }
+            break;
+        default:
+            throw new Error(`Unsupported browser assertion: ${assertion}`);
+    }
+}