@seontechnologies/playwright-utils 3.10.0

package/dist/cjs/recurse/recurse.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Custom error for timeout scenarios during polling
+ */
+export declare class RecurseTimeoutError extends Error {
+    readonly timeout: number;
+    readonly iterations: number;
+    readonly lastValue?: unknown | undefined;
+    constructor(message: string, timeout: number, iterations: number, lastValue?: unknown | undefined);
+}
+/**
+ * Custom error for command execution failures during polling
+ */
+export declare class RecurseCommandError extends Error {
+    readonly iteration: number;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, iteration: number, originalError?: Error | undefined);
+}
+/**
+ * Custom error for predicate evaluation failures
+ */
+export declare class RecursePredicateError extends Error {
+    readonly iteration: number;
+    readonly value?: unknown | undefined;
+    readonly originalError?: Error | undefined;
+    constructor(message: string, iteration: number, value?: unknown | undefined, originalError?: Error | undefined);
+}
+/**
+ * Custom error for internal state violations or programming bugs
+ */
+export declare class RecurseInternalError extends Error {
+    readonly iteration: number;
+    readonly context?: string | undefined;
+    constructor(message: string, iteration: number, context?: string | undefined);
+}
+/** data passed to log function */
+type RecurseLogData = {
+    value: any;
+    iteration: number;
+    elapsed: number;
+    timeout: number;
+    successful: boolean;
+};
+/** data passed to post function */
+type RecursePostData<T> = {
+    value: T;
+    iteration: number;
+    elapsed: number;
+    timeout: number;
+    successful: boolean;
+};
+type RecurseOptions = {
+    timeout?: number;
+    interval?: number;
+    log?: boolean | string | ((value: any, data: RecurseLogData) => void);
+    error?: string;
+    post?: (data: RecursePostData<any>) => void | Promise<void>;
+};
+export type RecurseParams<T> = {
+    command: () => Promise<T>;
+    predicate: (value: T) => boolean | void;
+    options?: RecurseOptions;
+};
+/**
+ * Re-runs a function until the predicate returns true or timeout is reached
+ * Similar to cypress-recurse API but using Playwright's expect.poll
+ *
+ * @param command Function that returns a value to test
+ * @param predicate Function that tests the value and returns true when the condition is met
+ * @param options Configuration options
+ * @returns The value from the command function when predicate returns true
+ *
+ * @example
+ * // Poll until session becomes active
+ * test('wait for activation', async ({ recurse }) => {
+ *   const session = await recurse(
+ *     () => apiRequest({ method: 'GET', url: '/session' }),
+ *     (response) => response.body.status === 'ACTIVE',
+ *     { timeout: 60000, interval: 2000 }
+ *   );
+ *
+ *   expect(session.body.id).toBeDefined();
+ * });
+ *
+ * @example
+ * // Poll with custom logging
+ * test('custom logging', async ({ recurse }) => {
+ *   await recurse(
+ *     () => fetchData(),
+ *     (data) => data.isReady,
+ *     {
+ *       log: 'Waiting for data to be ready',
+ *       timeout: 15000
+ *     }
+ *   );
+ * });
+ */
+/**
+ * Re-runs a function until the predicate returns true or timeout is reached
+ * This follows the cypress-recurse API but uses Playwright's expect.poll
+ *
+ * @param command Function that returns a value to test
+ * @param predicate Function that tests the value and returns true when the condition is met
+ * @param options Configuration options
+ * @returns The value from the command function when predicate returns true
+ */
+export declare function recurse<T>(command: () => Promise<T>, predicate: (value: T) => boolean | void, options?: RecurseOptions): Promise<T>;
+export {};
+//# sourceMappingURL=recurse.d.ts.map

package/dist/cjs/recurse/recurse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurse.d.ts","sourceRoot":"","sources":["../../../src/recurse/recurse.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,OAAO,EAAE,MAAM;aACf,UAAU,EAAE,MAAM;aAClB,SAAS,CAAC,EAAE,OAAO;gBAHnC,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,OAAO,YAAA;CAKtC;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,SAAS,EAAE,MAAM;aACjB,aAAa,CAAC,EAAE,KAAK;gBAFrC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,KAAK,YAAA;CAKxC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAG5B,SAAS,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,OAAO;aACf,aAAa,CAAC,EAAE,KAAK;gBAHrC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,OAAO,YAAA,EACf,aAAa,CAAC,EAAE,KAAK,YAAA;CAKxC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAG3B,SAAS,EAAE,MAAM;aACjB,OAAO,CAAC,EAAE,MAAM;gBAFhC,OAAO,EAAE,MAAM,EACC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AASD,kCAAkC;AAClC,KAAK,cAAc,GAAG;IACpB,KAAK,EAAE,GAAG,CAAA;IACV,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,mCAAmC;AACnC,KAAK,eAAe,CAAC,CAAC,IAAI;IACxB,KAAK,EAAE,CAAC,CAAA;IACR,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,CAAC,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC,CAAA;IACrE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5D,CAAA;AAiPD,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAA;IACzB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,IAAI,CAAA;IACvC,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,GAAG,IAAI,EACvC,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAsBZ"}

package/dist/cjs/recurse/recurse.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecurseInternalError = exports.RecursePredicateError = exports.RecurseCommandError = exports.RecurseTimeoutError = void 0;
+exports.recurse = recurse;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// utilities for polling and retrying operations using Playwright's expect.poll mechanism
+const test_1 = require("@playwright/test");
+const internal_1 = require("../internal");
+// =========================================================================
+// Enhanced Error Types for Recurse Operations
+// =========================================================================
+/**
+ * Custom error for timeout scenarios during polling
+ */
+class RecurseTimeoutError extends Error {
+    constructor(message, timeout, iterations, lastValue) {
+        super(message);
+        this.timeout = timeout;
+        this.iterations = iterations;
+        this.lastValue = lastValue;
+        this.name = 'RecurseTimeoutError';
+    }
+}
+exports.RecurseTimeoutError = RecurseTimeoutError;
+/**
+ * Custom error for command execution failures during polling
+ */
+class RecurseCommandError extends Error {
+    constructor(message, iteration, originalError) {
+        super(message);
+        this.iteration = iteration;
+        this.originalError = originalError;
+        this.name = 'RecurseCommandError';
+    }
+}
+exports.RecurseCommandError = RecurseCommandError;
+/**
+ * Custom error for predicate evaluation failures
+ */
+class RecursePredicateError extends Error {
+    constructor(message, iteration, value, originalError) {
+        super(message);
+        this.iteration = iteration;
+        this.value = value;
+        this.originalError = originalError;
+        this.name = 'RecursePredicateError';
+    }
+}
+exports.RecursePredicateError = RecursePredicateError;
+/**
+ * Custom error for internal state violations or programming bugs
+ */
+class RecurseInternalError extends Error {
+    constructor(message, iteration, context) {
+        super(message);
+        this.iteration = iteration;
+        this.context = context;
+        this.name = 'RecurseInternalError';
+    }
+}
+exports.RecurseInternalError = RecurseInternalError;
+/** default options for the recurse function */
+const RecurseDefaults = {
+    timeout: 30000, // 30 seconds
+    interval: 1000, // 1 second
+    log: false
+};
+/**
+ * Creates a state object with shared information for the polling operation
+ * @example
+ * const state = createPollingState(
+ *   () => fetchData(),
+ *   (data) => data.status === 'ready',
+ *   { timeout: 5000, interval: 500 }
+ * )
+ */
+const createPollingState = (command, predicate, options = {}) => ({
+    command,
+    predicate,
+    options,
+    timeout: options.timeout ?? RecurseDefaults.timeout,
+    interval: options.interval ?? RecurseDefaults.interval,
+    errorMessage: options.error ??
+        'Recursion timed out without finding a value that satisfies the predicate',
+    startTime: Date.now(),
+    iteration: 0,
+    lastValue: null,
+    wasSuccessful: false
+});
+const getElapsedTime = (startTime) => Date.now() - startTime;
+/**
+ * Logs attempts during polling with their status
+ * @example
+ * // logs: "Attempt #2 (1500ms): RETRY"
+ * await logAttempt(state, value, false)
+ *
+ * // logs: "Attempt #3 (2000ms): SUCCESS"
+ * await logAttempt(state, value, true)
+ */
+const logAttempt = async (state, value, successful) => {
+    if (!state.options.log)
+        return;
+    const elapsed = getElapsedTime(state.startTime);
+    const { iteration, timeout } = state;
+    if (typeof state.options.log === 'function') {
+        state.options.log(value, {
+            value,
+            iteration,
+            elapsed,
+            timeout,
+            successful
+        });
+    }
+    if (typeof state.options.log === 'string') {
+        // For string logs, we don't log individual attempts
+        // The final success will be logged in logSuccess()
+        return;
+    }
+    if (successful) {
+        await (0, internal_1.getLogger)().success(`Attempt #${iteration} (${elapsed}ms): SUCCESS`);
+    }
+    else {
+        await (0, internal_1.getLogger)().info(`Attempt #${iteration} (${elapsed}ms): RETRY`);
+    }
+};
+/**
+ * Logs the beginning of a polling operation
+ * @example
+ * // logs: "Polling until condition is met (timeout: 30000ms, interval: 1000ms)"
+ * await logInitialStep(state)
+ */
+const logInitialStep = async (state) => {
+    const { options, timeout, interval } = state;
+    if (options.log && typeof options.log === 'string') {
+        await (0, internal_1.getLogger)().step(`Polling: ${options.log}`);
+    }
+    else {
+        await (0, internal_1.getLogger)().step(`Polling until condition is met (timeout: ${timeout}ms, interval: ${interval}ms)`);
+    }
+};
+/**
+ * Logs the successful completion of a polling operation
+ * @example
+ * // logs: "Polling completed successfully after 3 iterations"
+ * await logSuccess(state)
+ */
+const logSuccess = async (state) => {
+    const { options, iteration, wasSuccessful } = state;
+    if (!wasSuccessful || !options.log)
+        return;
+    if (typeof options.log === 'string') {
+        await (0, internal_1.getLogger)().step(`✅ ${options.log} - completed successfully after ${iteration} iterations`);
+    }
+    else {
+        await (0, internal_1.getLogger)().step(`✅ Polling completed successfully after ${iteration} iterations`);
+    }
+};
+/**
+ * Executes the post callback function if configured
+ * @example
+ * // Will call options.post with the result data
+ * await executePostCallback(state)
+ */
+const executePostCallback = async (state) => {
+    const { options, wasSuccessful, lastValue, startTime, iteration, timeout } = state;
+    if (!options.post || !wasSuccessful || !lastValue)
+        return;
+    const elapsed = getElapsedTime(startTime);
+    const postData = {
+        value: lastValue,
+        iteration,
+        elapsed,
+        timeout,
+        successful: wasSuccessful
+    };
+    await options.post(postData);
+};
+/**
+ * Core polling implementation using Playwright's `expect.poll` with enhanced error handling
+ * https://playwright.dev/docs/test-assertions#expectpoll
+ * @example
+ * // Repeatedly calls the command function until predicate returns true
+ * await executePolling(state)
+ */
+const executePolling = async (state) => {
+    try {
+        await test_1.expect
+            .poll(async () => {
+            state.iteration += 1;
+            let value;
+            try {
+                value = await state.command();
+                state.lastValue = value;
+            }
+            catch (error) {
+                const commandError = new RecurseCommandError(`Command failed on iteration ${state.iteration}`, state.iteration, error instanceof Error ? error : new Error(String(error)));
+                throw commandError;
+            }
+            let successful = false;
+            try {
+                // Handle both boolean returns and assertions that might throw
+                const result = state.predicate(value);
+                // If predicate doesn't return anything but has assertions,
+                // treat as true since it didn't throw
+                successful = result === undefined ? true : !!result;
+            }
+            catch (error) {
+                // If assertion fails, treat as false but store the error for potential debugging
+                successful = false;
+                // Only throw predicate errors if they seem unintentional (not assertion failures)
+                if (error instanceof Error && !error.message.includes('expect(')) {
+                    throw new RecursePredicateError(`Predicate evaluation failed on iteration ${state.iteration}`, state.iteration, value, error);
+                }
+            }
+            await logAttempt(state, value, successful);
+            if (successful) {
+                state.wasSuccessful = true;
+                return true;
+            }
+            return false;
+        }, {
+            message: state.errorMessage,
+            timeout: state.timeout,
+            intervals: [state.interval]
+        })
+            .toBeTruthy();
+    }
+    catch (error) {
+        // Re-throw our custom errors
+        if (error instanceof RecurseCommandError ||
+            error instanceof RecursePredicateError) {
+            throw error;
+        }
+        // If Playwright's expect.poll times out, wrap it in our timeout error
+        if (error instanceof Error && error.message.includes('Timeout')) {
+            throw new RecurseTimeoutError(`${state.errorMessage} (${state.timeout}ms timeout exceeded)`, state.timeout, state.iteration, state.lastValue);
+        }
+        // Fallback for unexpected errors
+        throw error;
+    }
+};
+/**
+ * Re-runs a function until the predicate returns true or timeout is reached
+ * Similar to cypress-recurse API but using Playwright's expect.poll
+ *
+ * @param command Function that returns a value to test
+ * @param predicate Function that tests the value and returns true when the condition is met
+ * @param options Configuration options
+ * @returns The value from the command function when predicate returns true
+ *
+ * @example
+ * // Poll until session becomes active
+ * test('wait for activation', async ({ recurse }) => {
+ *   const session = await recurse(
+ *     () => apiRequest({ method: 'GET', url: '/session' }),
+ *     (response) => response.body.status === 'ACTIVE',
+ *     { timeout: 60000, interval: 2000 }
+ *   );
+ *
+ *   expect(session.body.id).toBeDefined();
+ * });
+ *
+ * @example
+ * // Poll with custom logging
+ * test('custom logging', async ({ recurse }) => {
+ *   await recurse(
+ *     () => fetchData(),
+ *     (data) => data.isReady,
+ *     {
+ *       log: 'Waiting for data to be ready',
+ *       timeout: 15000
+ *     }
+ *   );
+ * });
+ */
+/**
+ * Re-runs a function until the predicate returns true or timeout is reached
+ * This follows the cypress-recurse API but uses Playwright's expect.poll
+ *
+ * @param command Function that returns a value to test
+ * @param predicate Function that tests the value and returns true when the condition is met
+ * @param options Configuration options
+ * @returns The value from the command function when predicate returns true
+ */
+async function recurse(command, predicate, options = {}) {
+    // create the shared polling state
+    const state = createPollingState(command, predicate, options);
+    await logInitialStep(state);
+    await executePolling(state);
+    await logSuccess(state);
+    await executePostCallback(state);
+    // validate and return the result
+    if (!state.lastValue) {
+        throw new RecurseInternalError('Internal error: Recursion completed but no value was stored', state.iteration, 'This indicates a programming bug in the polling logic');
+    }
+    return state.lastValue;
+}
+//# sourceMappingURL=recurse.js.map

package/dist/cjs/recurse/recurse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurse.js","sourceRoot":"","sources":["../../../src/recurse/recurse.ts"],"names":[],"mappings":"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"}

package/dist/esm/api-request/api-request-fixture.d.ts

@@ -0,0 +1,47 @@
+import type { ApiRequestParams } from './api-request';
+import type { EnhancedApiPromise } from './schema-validation/internal/promise-extension';
+/**
+ * Type for the apiRequest fixture parameters - exactly like ApiRequestParams but without the 'request' property
+ * which is handled internally by the fixture.
+ */
+export type ApiRequestFixtureParams = Omit<ApiRequestParams, 'request'>;
+export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & {
+    /**
+     * Simplified helper for making API requests and returning the status and JSON body.
+     * This helper automatically performs the request based on the provided method, path, body, and headers.
+     * It handles URL construction with proper slash handling and response parsing based on content type.
+     *
+     * IMPORTANT: When using the fixture version, you do NOT need to provide the 'request' parameter,
+     * as it's automatically injected by the fixture.
+     *
+     * @example
+     * // GET request to an endpoint
+     * test('fetch user data', async ({ apiRequest }) => {
+     *   const { status, body } = await apiRequest<UserResponse>({
+     *     method: 'GET',
+     *     path: '/api/users/123',  // Note: use 'path' not 'url'
+     *     headers: { 'Authorization': 'Bearer token' }
+     *   });
+     *
+     *   expect(status).toBe(200);
+     *   expect(body.name).toBe('John Doe');
+     * });
+     *
+     * @example
+     * // POST request with a body
+     * test('create new item', async ({ apiRequest }) => {
+     *   const { status, body } = await apiRequest<CreateItemResponse>({
+     *     method: 'POST',
+     *     path: '/api/items',  // Note: use 'path' not 'url'
+     *     baseUrl: 'https://api.example.com', // override default baseURL
+     *     body: { name: 'New Item', price: 19.99 },
+     *     headers: { 'Content-Type': 'application/json' }
+     *   });
+     *
+     *   expect(status).toBe(201);
+     *   expect(body.id).toBeDefined();
+     * });
+     */
+    apiRequest: <T = unknown>(params: ApiRequestFixtureParams) => EnhancedApiPromise<T>;
+}, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+//# sourceMappingURL=api-request-fixture.d.ts.map

package/dist/esm/api-request/api-request-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-request-fixture.d.ts","sourceRoot":"","sources":["../../../src/api-request/api-request-fixture.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAA;AAExF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,IAAI,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAA;AAEvE,eAAO,MAAM,IAAI;IACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;gBACS,CAAC,CAAC,GAAG,OAAO,EACtB,MAAM,EAAE,uBAAuB,KAC5B,kBAAkB,CAAC,CAAC,CAAC;wGA+B1B,CAAA"}

package/dist/esm/api-request/api-request-fixture.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.test = void 0;
+const test_1 = require("@playwright/test");
+const api_request_1 = require("./api-request");
+exports.test = test_1.test.extend({
+    apiRequest: async ({ request, baseURL, page }, use) => {
+        const apiRequest = ({ method, path, baseUrl, configBaseUrl = baseURL, body = null, headers, params, uiMode = false, testStep }) => {
+            return (0, api_request_1.apiRequest)({
+                request,
+                method,
+                path,
+                baseUrl,
+                configBaseUrl,
+                body,
+                headers,
+                params,
+                uiMode,
+                testStep,
+                page // Pass page context for UI mode
+            });
+        };
+        await use(apiRequest);
+    }
+});
+//# sourceMappingURL=api-request-fixture.js.map

package/dist/esm/api-request/api-request-fixture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-request-fixture.js","sourceRoot":"","sources":["../../../src/api-request/api-request-fixture.ts"],"names":[],"mappings":";;;AAAA,2CAA+C;AAC/C,+CAAgE;AAUnD,QAAA,IAAI,GAAG,WAAI,CAAC,MAAM,CAwC5B;IACD,UAAU,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QACpD,MAAM,UAAU,GAAG,CAAc,EAC/B,MAAM,EACN,IAAI,EACJ,OAAO,EACP,aAAa,GAAG,OAAO,EACvB,IAAI,GAAG,IAAI,EACX,OAAO,EACP,MAAM,EACN,MAAM,GAAG,KAAK,EACd,QAAQ,EACgB,EAAyB,EAAE;YACnD,OAAO,IAAA,wBAAkB,EAAI;gBAC3B,OAAO;gBACP,MAAM;gBACN,IAAI;gBACJ,OAAO;gBACP,aAAa;gBACb,IAAI;gBACJ,OAAO;gBACP,MAAM;gBACN,MAAM;gBACN,QAAQ;gBACR,IAAI,CAAC,gCAAgC;aACtC,CAAC,CAAA;QACJ,CAAC,CAAA;QAED,MAAM,GAAG,CAAC,UAAU,CAAC,CAAA;IACvB,CAAC;CACF,CAAC,CAAA"}

package/dist/esm/api-request/api-request.d.ts

@@ -0,0 +1,108 @@
+import { type APIRequestContext, type Page } from '@playwright/test';
+import { type EnhancedApiPromise } from './schema-validation/internal/promise-extension';
+/** Retry configuration for API requests (like Cypress - only retries 5xx server errors, never 4xx client errors) */
+export type ApiRetryConfig = {
+    /** Maximum number of retry attempts for server errors (default: 3) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 100ms) */
+    initialDelayMs?: number;
+    /** Exponential backoff multiplier (default: 2) */
+    backoffMultiplier?: number;
+    /** Maximum delay between retries in milliseconds (default: 5000ms) */
+    maxDelayMs?: number;
+    /** Whether to add random jitter to delays (default: true) */
+    enableJitter?: boolean;
+    /** Which status codes to retry (default: [500, 502, 503, 504] - only 5xx server errors) */
+    retryStatusCodes?: number[];
+};
+/** Custom error type for API request failures */
+export declare class ApiRequestError extends Error {
+    readonly status: number;
+    readonly response?: unknown | undefined;
+    readonly attempt?: number | undefined;
+    constructor(message: string, status: number, response?: unknown | undefined, attempt?: number | undefined);
+}
+/** Network-level error for connection issues */
+export declare class ApiNetworkError extends Error {
+    readonly originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+export type ApiRequestParams = {
+    request: APIRequestContext;
+    method: 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD';
+    path: string;
+    baseUrl?: string;
+    configBaseUrl?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    params?: Record<string, string | boolean | number>;
+    testStep?: boolean;
+    uiMode?: boolean;
+    page?: Page;
+    /** Retry configuration for handling failed requests (enabled by default like Cypress - set maxRetries: 0 to disable) */
+    retryConfig?: ApiRetryConfig;
+};
+export type ApiRequestResponse<T = unknown> = {
+    status: number;
+    body: T;
+};
+/**
+ * Simplified helper for making API requests and returning the status and JSON body.
+ * This helper automatically performs the request based on the provided method, path, body, and headers.
+ * It handles URL construction with proper slash handling and response parsing based on content type.
+ *
+ * @param {Object} params - The parameters for the request.
+ * @param {APIRequestContext} params.request - The Playwright request object, used to make the HTTP request.
+ * @param {string} params.method - The HTTP method to use (POST, GET, PUT, DELETE, PATCH, HEAD).
+ * @param {string} params.path - The path or endpoint to send the request to (e.g., '/api/users').
+ * @param {string} [params.baseUrl] - The base URL to prepend to the path (e.g., 'https://api.example.com').
+ * @param {string} [params.configBaseUrl] - Fallback base URL, typically from Playwright config.
+ * @param {unknown} [params.body=null] - The body to send with the request (for POST, PUT, and PATCH requests).
+ * @param {Record<string, string> | undefined} [params.headers] - The headers to include with the request.
+ * @param {Record<string, string | boolean | number> | undefined} [params.params] - Query parameters to include with the request.
+ * @returns {Promise<ApiRequestResponse<T>>} - An object containing the status code and the parsed response body.
+ *    - `status`: The HTTP status code returned by the server.
+ *    - `body`: The parsed response body from the server, typed as T.
+ *
+ * @example
+ * // GET request with default retry behavior (like Cypress - only retries 5xx server errors)
+ * test('fetch user data', async ({ apiRequest }) => {
+ *   const { status, body } = await apiRequest<UserResponse>({
+ *     method: 'GET',
+ *     url: '/api/users/123',
+ *     headers: { 'Authorization': 'Bearer token' }
+ *     // Automatically retries 500, 502, 503, 504 errors (3 attempts with exponential backoff)
+ *     // Never retries 4xx client errors (400, 401, 403, 404, etc.)
+ *   });
+ *
+ *   expect(status).toBe(200);
+ *   expect(body.name).toBe('John Doe');
+ * });
+ *
+ * @example
+ * // 4xx errors fail immediately without retry (good for idempotency)
+ * test('handle validation error', async ({ apiRequest }) => {
+ *   const { status, body } = await apiRequest({
+ *     method: 'POST',
+ *     url: '/api/users',
+ *     body: { name: '' } // Invalid data
+ *     // 400 Bad Request will NOT be retried - fails fast
+ *   });
+ *
+ *   expect(status).toBe(400);
+ * });
+ *
+ * @example
+ * // Disable retry when testing error scenarios
+ * test('test server error handling', async ({ apiRequest }) => {
+ *   const { status } = await apiRequest({
+ *     method: 'GET',
+ *     url: '/api/fail-endpoint',
+ *     retryConfig: { maxRetries: 0 } // Disable retry to test error handling
+ *   });
+ *
+ *   expect(status).toBe(500);
+ * });
+ */
+export declare const apiRequest: <T = unknown>(options: ApiRequestParams) => EnhancedApiPromise<T>;
+//# sourceMappingURL=api-request.d.ts.map

package/dist/esm/api-request/api-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-request.d.ts","sourceRoot":"","sources":["../../../src/api-request/api-request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAYpE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,gDAAgD,CAAA;AAEvD,oHAAoH;AACpH,MAAM,MAAM,cAAc,GAAG;IAC3B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC5B,CAAA;AAED,iDAAiD;AACjD,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;aACd,QAAQ,CAAC,EAAE,OAAO;aAClB,OAAO,CAAC,EAAE,MAAM;gBAHhC,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,OAAO,YAAA,EAClB,OAAO,CAAC,EAAE,MAAM,YAAA;CAKnC;AAED,gDAAgD;AAChD,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,aAAa,CAAC,EAAE,KAAK;gBADrC,OAAO,EAAE,MAAM,EACC,aAAa,CAAC,EAAE,KAAK,YAAA;CAKxC;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,iBAAiB,CAAA;IAC1B,MAAM,EAAE,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IAC5D,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,CAAA;IAClD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,wHAAwH;IACxH,WAAW,CAAC,EAAE,cAAc,CAAA;CAC7B,CAAA;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC5C,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,CAAA;CACR,CAAA;AAkSD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,GAAG,OAAO,EACpC,SAAS,gBAAgB,KACxB,kBAAkB,CAAC,CAAC,CA6BtB,CAAA"}