fluentrest-ts/dist/core/request-builder.d.ts

A lightweight, fluent TypeScript API testing library inspired by Java's RestAssured. Built on top of Axios, JSONPath, and Joi for powerful request handling and response validation.

import { AxiosProxyConfig, AxiosRequestConfig } from "axios";
import { RestAssuredDefaults } from "./config";
import { LogLevel } from "./logger";
import { RequestSnapshot } from "../contracts/request-snapshot";
import { ResponseValidator } from "../contracts/response-validator-type";
/**
 * A fluent builder for configuring HTTP requests.
 * Provides `given*` and `when*` methods to define and trigger requests.
 */
export declare class RequestBuilder {
    protected config: Partial<AxiosRequestConfig>;
    protected logToFile: boolean;
    protected logLevel: LogLevel;
    private proxyOverride?;
    private proxyAgent?;
    constructor(overrides?: Partial<RestAssuredDefaults>);
    /**
     * Update the constructor to always call a utility method that handles the logic for proxy setup.
    */
    private applyProxy;
    /** Sets the base URL for the request. */
    setBaseUrl(url: string): this;
    /** Sets the timeout duration in milliseconds. */
    setTimeout(ms: number): this;
    /** Overrides the log level for this request. */
    setLogLevel(level: LogLevel): this;
    /**
     * Sets a proxy for this request.
     * Accepts either an Axios proxy config object or a proxy URL (for HTTPS tunneling).
     *
     * @param proxy Axios proxy config object or proxy URL string
     */
    setProxy(proxy: AxiosProxyConfig | string): this;
    /** Removes all proxy config (agent or classic Axios-style) for this request. */
    clearProxy(): this;
    /** Enables or disables file-based logging. */
    enableFileLogging(enable: boolean): this;
    /** Adds a request header. */
    givenHeader(key: string, value: string): this;
    /** Adds a query string parameter. */
    givenQueryParam(key: string, value: string): this;
    /**
     * Adds a JSON request body.
     * Adds a JSON string body
     * Adds multipart form-data from file paths or strings.
     * Automatically attaches files if they exist on disk.
     */
    givenBody(body: any, contentType?: string): this;
    /** Prints the current request config as a snapshot for debugging. */
    debug(): this;
    /** Returns a snapshot of the request config (used for debugging or logging). */
    getSnapshot(): RequestSnapshot;
    /**
   * Sends a GET request to the specified endpoint using the current request configuration.
   * Returns a ResponseValidator which allows chaining expectations.
   *
   * @example
   * const response = await fluentRest().whenGet("/users/1");
   */
    whenGet(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends a POST request to the specified endpoint with the current configuration.
   * Use `givenBody()` before this to attach a payload.
   *
   * @example
   * const response = await fluentRest().givenBody({ name: "John" }).whenPost("/users");
   */
    whenPost(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends a PUT request to the specified endpoint using the current request configuration.
   * Typically used for full updates to a resource.
   */
    whenPut(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends a DELETE request to the specified endpoint.
   * Useful for resource cleanup or deletion tests.
   */
    whenDelete(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends a PATCH request to the specified endpoint using the current request configuration.
   * Typically used for partial updates to a resource.
   */
    whenPatch(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends a HEAD request to the given endpoint using the current builder configuration.
   * @param endpoint - The API endpoint path to send the request to.
   * @returns A ResponseValidator for performing post-response assertions.
   */
    whenHead(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Sends an OPTIONS request to the given endpoint using the current builder configuration.
   * @param endpoint - The API endpoint path to send the request to.
   * @returns A ResponseValidator for performing post-response assertions.
   */
    whenOptions(endpoint: string): Promise<import("./response-validator").ResponseValidatorImpl>;
    /**
   * Returns the underlying Axios request configuration used in the builder including proxy settings.
   * Useful for debugging or inspection.
   * @returns The AxiosRequestConfig used in the current request builder.
   */
    getConfig(): AxiosRequestConfig;
    /**
   * Returns the log level configured for this builder instance.
   * Useful to determine logging behavior in tests.
   * @returns The active LogLevel (e.g., 'debug', 'info', 'none').
   */
    getLogLevel(): LogLevel;
    /**
   * Indicates whether logging to file is enabled for this builder instance.
   * @returns True if logs should be persisted to file, false otherwise.
   */
    shouldLogToFile(): boolean;
    /**
     * Executes a request and runs expectations in one step.
     * Useful for compact tests when you want to send a request and immediately assert the response.
     * Optionally accepts request overrides like headers, body, and query params.
     */
    sendAndExpect(method: "get" | "post" | "put" | "patch" | "delete" | "head" | "options", endpoint: string, expect: (res: ResponseValidator) => void, configOverrides?: {
        headers?: Record<string, string>;
        body?: any;
        params?: Record<string, any>;
    }): Promise<void>;
}