@testspectra/matchers 1.0.70 → 1.1.0-rc.1

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/__tests__/intercept.test.d.ts

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

package/dist/__tests__/intercept.test.js

@@ -0,0 +1,183 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Spectra } from '../spectra.js';
+import { CdpHandler } from '../intercept/cdp-handler.js';
+import { MockRegistry } from '../intercept/mock-registry.js';
+describe('Spectra.intercept Custom Command & Deflaking Architecture (docs/v2/cli/matchers-interception-reliability.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-intercept-test-'));
+        Spectra.clearMocks();
+        MockRegistry.getInstance().clearRecordedResources();
+    });
+    afterEach(() => {
+        Spectra.clearMocks();
+        MockRegistry.getInstance().clearRecordedResources();
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('correctly shifts respondOnce FIFO queue before falling back to respondWith', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/export/status',
+            method: 'GET',
+        });
+        mock.respondOnce({ status: 200, body: { status: 'pending' } });
+        mock.respondOnce({ status: 200, body: { status: 'processing' } });
+        mock.respondWith({ status: 200, body: { status: 'completed', downloadUrl: '/file.pdf' } });
+        // Call 1: should return pending
+        const call1 = {
+            id: 'req-1',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res1 = await CdpHandler.dispatchIncomingRequest(call1);
+        expect(res1.response?.body).toEqual({ status: 'pending' });
+        // Call 2: should return processing
+        const call2 = {
+            id: 'req-2',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res2 = await CdpHandler.dispatchIncomingRequest(call2);
+        expect(res2.response?.body).toEqual({ status: 'processing' });
+        // Call 3: should fall back to default completed
+        const call3 = {
+            id: 'req-3',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res3 = await CdpHandler.dispatchIncomingRequest(call3);
+        expect(res3.response?.body).toEqual({ status: 'completed', downloadUrl: '/file.pdf' });
+        // Call 4: still completed
+        const call4 = {
+            id: 'req-4',
+            url: 'https://example.com/api/v1/export/status',
+            method: 'GET',
+            timestamp: Date.now(),
+        };
+        const res4 = await CdpHandler.dispatchIncomingRequest(call4);
+        expect(res4.response?.body).toEqual({ status: 'completed', downloadUrl: '/file.pdf' });
+        expect(mock.callCount).toBe(4);
+        expect(mock.calls.length).toBe(4);
+    });
+    it('simulates network abort with specified error code', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/sync',
+            method: 'POST',
+        });
+        mock.abort('ConnectionReset');
+        const req = {
+            id: 'req-sync',
+            url: 'https://example.com/api/v1/sync',
+            method: 'POST',
+            body: { data: 'sync-payload' },
+            timestamp: Date.now(),
+        };
+        const fulfill = await CdpHandler.dispatchIncomingRequest(req);
+        expect(fulfill.aborted).toBe('ConnectionReset');
+        expect(mock.callCount).toBe(1);
+    });
+    it('supports waitForCall to await asynchronous incoming requests', async () => {
+        const mock = await Spectra.intercept({
+            url: '**/api/v1/async-task',
+            method: 'POST',
+            response: { status: 202, body: { ok: true } },
+        });
+        const waitPromise = mock.waitForCall({ timeout: 2000 });
+        // Dispatch after a brief async delay
+        setTimeout(() => {
+            CdpHandler.dispatchIncomingRequest({
+                id: 'req-async',
+                url: 'https://example.com/api/v1/async-task',
+                method: 'POST',
+                body: { started: true },
+                timestamp: Date.now(),
+            });
+        }, 50);
+        const receivedCall = await waitPromise;
+        expect(receivedCall.id).toBe('req-async');
+        expect(receivedCall.body).toEqual({ started: true });
+        expect(mock.callCount).toBe(1);
+    });
+    it('prevents mock bleeding across test cases via Spectra.clearMocks()', async () => {
+        // Step 1: Register mock in test case A
+        const mockA = await Spectra.intercept({
+            url: '**/api/v1/user/profile',
+            method: 'GET',
+            response: { status: 200, body: { user: 'Alice' } },
+        });
+        await CdpHandler.dispatchIncomingRequest({
+            id: 'req-user',
+            url: 'https://example.com/api/v1/user/profile',
+            method: 'GET',
+            timestamp: Date.now(),
+        });
+        expect(mockA.callCount).toBe(1);
+        // Step 2: Clear mocks as done in afterEach hook
+        Spectra.clearMocks();
+        // Step 3: Verify registry is clean and no mock bleeds
+        const registry = MockRegistry.getInstance();
+        const matched = registry.findMatchingHandle('GET', 'https://example.com/api/v1/user/profile');
+        expect(matched).toBeUndefined();
+    });
+    it('runs 50 consecutive iterations of mock tests with 0% flakiness', async () => {
+        for (let i = 1; i <= 50; i++) {
+            Spectra.clearMocks();
+            const mock = await Spectra.intercept({
+                url: `**/api/v1/item/${i}`,
+                method: 'GET',
+                response: { status: 200, body: { iteration: i } },
+            });
+            const req = {
+                id: `iter-${i}`,
+                url: `https://example.com/api/v1/item/${i}`,
+                method: 'GET',
+                timestamp: Date.now(),
+            };
+            const result = await CdpHandler.dispatchIncomingRequest(req);
+            expect(result.response?.body).toEqual({ iteration: i });
+            expect(mock.callCount).toBe(1);
+        }
+    });
+    it('records network traffic and exports to network-resources.json in spec format', async () => {
+        await Spectra.intercept({
+            url: '**/v1/users/me',
+            method: 'GET',
+            response: {
+                status: 200,
+                headers: { 'content-type': 'application/json' },
+                body: { id: 'usr-1', name: 'Admin' },
+            },
+        });
+        const req = {
+            id: 'req-001',
+            url: 'https://api.testspectra.dev/v1/users/me',
+            method: 'GET',
+            headers: { authorization: 'Bearer test-token' },
+            timestamp: Date.now(),
+        };
+        await CdpHandler.dispatchIncomingRequest(req);
+        const reportPath = path.join(tmpDir, 'runs', 'run-001', 'network-resources.json');
+        MockRegistry.getInstance().exportNetworkResources(reportPath);
+        expect(fs.existsSync(reportPath)).toBe(true);
+        const content = JSON.parse(fs.readFileSync(reportPath, 'utf-8'));
+        expect(Array.isArray(content)).toBe(true);
+        expect(content.length).toBe(1);
+        const entry = content[0];
+        expect(entry.id).toBe('req-001');
+        expect(entry.url).toBe('https://api.testspectra.dev/v1/users/me');
+        expect(entry.method).toBe('GET');
+        expect(entry.status).toBe(200);
+        expect(entry.resourceType).toBe('fetch');
+        expect(entry.timing).toBeDefined();
+        expect(entry.timing.total).toBeGreaterThan(0);
+        expect(entry.responseBody).toEqual({ id: 'usr-1', name: 'Admin' });
+    });
+});

package/dist/__tests__/matcher-contracts.test.d.ts

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