@skyramp/skyramp 1.3.11 → 1.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.3.11",
+  "version": "1.3.12",
   "description": "module for leveraging skyramp cli functionality",
   "scripts": {
     "lint": "eslint 'src/**/*.js' 'src/**/*.ts' --fix",
@@ -26,12 +26,12 @@
     "@aws-sdk/client-s3": "^3.812.0",
     "fs": "^0.0.1-security",
     "js-yaml": "^4.1.0",
-    "koffi": "2.5.12",
+    "koffi": "^2.15.0",
     "zod": "^3.25.3"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^6.14.0",
     "@typescript-eslint/parser": "^6.14.0",
-    "eslint": "^8.55.0"
+    "eslint": "^8.57.1"
   }
 }

package/src/classes/MockV2.d.ts

@@ -10,7 +10,7 @@ export class MockV2 {
    * The URL of the service to mock
    */
   URL: string;
-  
+
   /**
    * The path to mock (e.g., "/api/v1/products")
    */
@@ -20,7 +20,7 @@ export class MockV2 {
    * The HTTP method (GET, POST, PUT, DELETE, etc.)
    */
   method: string;
-  
+
   /**
    * The HTTP status code to return
    */
@@ -30,19 +30,30 @@ export class MockV2 {
    * The response body to return
    */
   responseBody: string;
-  
+
   /**
    * Optional request body to match
    */
   requestBody?: string | null;
-  
+
   /**
    * Optional data override object
    */
   dataOverride?: Record<string, unknown> | null;
 
   /**
-   * Creates a new MockV2 instance
+   * Optional client ID for mock identification
+   */
+  clientID?: string | null;
+
+  /**
+   * Creates a new MockV2 instance using an options object
+   * @param options - Configuration options for the mock
+   */
+  constructor(options: MockV2Options);
+
+  /**
+   * Creates a new MockV2 instance using positional arguments
    * @param URL - The URL of the service to mock
    * @param path - The path path to mock (e.g., "/api/v1/products")
    * @param method - The HTTP method (GET, POST, PUT, DELETE, etc.)
@@ -73,6 +84,7 @@ export class MockV2 {
     response_body: string;
     request_body?: string;
     data_override?: Record<string, unknown>;
+    client_id?: string;
   };
 
   /**

package/src/classes/MockV2.js

@@ -5,23 +5,52 @@
 class MockV2 {
   /**
    * Represents a mock object configuration for API endpoint mocking.
-   * @param {Object} [options={}] - The options for creating the mock.
-   * @param {string} [options.url=''] - The URL of the service to mock
-   * @param {string} [options.path=''] - The path to mock (e.g., "/api/v1/products")
-   * @param {string} [options.method=''] - The HTTP method (GET, POST, PUT, DELETE, etc.)
-   * @param {number} [options.statusCode=201] - The HTTP status code to return
-   * @param {string} [options.responseBody=''] - The response body to return
-   * @param {string} [options.requestBody=''] - Optional request body to match
-   * @param {Object.<string, *>} [options.dataOverride={}] - Optional data override object
+   * Supports both positional arguments and options object patterns.
+   *
+   * @example
+   * // Positional arguments
+   * new MockV2("http://localhost:8080", "/api/v1/products", 8080, "POST", 201, "{}")
+   *
+   * @example
+   * // Options object (preferred)
+   * new MockV2({
+   *   url: "http://localhost:8080",
+   *   path: "/api/v1/products",
+   *   method: "POST",
+   *   responseStatusCode: 201
+   * })
+   *
+   * @param {string|Object} URLOrOptions - URL string or options object
+   * @param {string} [path] - The endpoint path (positional only)
+   * @param {string} [method] - The HTTP method (positional only)
+   * @param {number} [statusCode] - The status code (positional only)
+   * @param {string} [responseBody] - The response body (positional only)
+   * @param {string} [requestBody] - Optional request body to match
+   * @param {Object} [dataOverride] - Optional data override object
    */
-  constructor(options = {}) {
-    this.url = options.url || '';
-    this.path = options.path || '';
-    this.method = options.method || '';
-    this.statusCode = options.statusCode || 201;
-    this.responseBody = options.responseBody || '';
-    this.requestBody = options.requestBody || '';
-    this.dataOverride = options.dataOverride || {}; 
+  constructor(URLOrOptions, path, method, statusCode, responseBody, requestBody = null, dataOverride = null) {
+    // Handle options object pattern
+    if (typeof URLOrOptions === 'object' && URLOrOptions !== null) {
+      const options = URLOrOptions;
+      this.url = options.url || '';
+      this.path = options.path || '';
+      this.method = options.method || '';
+      this.statusCode = options.statusCode || 201;
+      this.responseBody = (options.body !== undefined ? options.body : options.responseBody) || '';
+      this.requestBody = options.requestBody || null;
+      this.dataOverride = options.dataOverride || null;
+      this.clientID = options.clientID || null;
+    } else {
+      // Handle positional arguments pattern
+      this.url = URLOrOptions;
+      this.path = path;
+      this.method = method;
+      this.statusCode = statusCode;
+      this.responseBody = responseBody;
+      this.requestBody = requestBody;
+      this.dataOverride = dataOverride;
+      this.clientID = null;
+    }
   }
 
   /**
@@ -45,6 +74,10 @@ class MockV2 {
       result.data_override = this.dataOverride;
     }
 
+    if (this.clientID !== null) {
+      result.client_id = this.clientID;
+    }
+
     return result;
   }
 

package/src/classes/SkyrampClient.d.ts

@@ -138,6 +138,13 @@ interface GenerateRestTestOptions {
   unblock?: boolean;
   entrypoint?: string;
   chainingKey?: string;
+  parentRequestData?: Record<string, string> | string;
+  parentStatusCode?: Record<string, string> | string;
+  requestAware?: boolean;
+  providerMode?: boolean;
+  consumerMode?: boolean;
+  providerOutput?: string;
+  consumerOutput?: string;
 }
 
 interface GenerateRestMockOptions {
@@ -157,6 +164,7 @@ interface GenerateRestMockOptions {
   responseStatusCode?: string;
   force?: boolean;
   deployDashboard?: boolean;
+  requestAware?: boolean;
   formParams?: string;
   pathParams?: string;
   queryParams?: string;
@@ -174,11 +182,6 @@ interface SendScenarioOptions {
   skipCertVerification?: boolean;
 }
 
-interface InitAgentOptions {
-  version: string;
-  entryPoint?: string;
-}
-
 export declare class SkyrampClient {
   constructor(
     kubeconfigPath?: string,
@@ -250,6 +253,7 @@ export declare class SkyrampClient {
     mockYamlContent: string
   ): Promise<void>;
   applyMock(mock: MockV2 | MockV2[]): Promise<void>;
+  removeAllMocks(): Promise<void>;
   testerStart(
     namespace: string,
     kubePath: string,
@@ -314,10 +318,7 @@ export declare class SkyrampClient {
 
   /**
    * Initializes the agent by checking and pulling required Docker images (executor and worker).
-   * @param {InitAgentOptions} options - The options for initializing the agent.
-   * @param {string} options.version - The version of the agent to initialize.
-   * @param {string} [options.entryPoint='vscode'] - The entry point identifier (e.g., 'vscode').
    * @returns {Promise<string>} A promise that resolves with the initialization output message.
    */
-  initAgent(options: InitAgentOptions): Promise<string>;
+  initAgent(): Promise<string>;
 }

package/src/classes/SkyrampClient.js

@@ -1,3 +1,4 @@
+const { promisify } = require('util');
 const lib = require('../lib');
 const koffi = require('koffi');
 const TrafficConfig = require('./TrafficConfig');
@@ -46,16 +47,98 @@ const runTesterStartWrapper = lib.func('runTesterStartWrapper', testerInfoType,
 const runTesterStartWrapperv1 = lib.func('runTesterStartWrapperWithGlobalHeaders', testerInfoType, ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string']);
 const applyMockDescriptionWrapper = lib.func('applyMockDescriptionWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string']);
 const applyMockObjectWrapper = lib.func('applyMockObjectWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool']);
+const removeMocksObjectWrapper = lib.func('removeMocksObjectWrapper', 'string', []);
 // NPM only: for VS code extension use
 const initTargetWrapper = lib.func('initTargetWrapper', 'string', ['string']);
 const deployTargetWrapper = lib.func('deployTargetWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'bool']);
 const deleteTargetWrapper = lib.func('deleteTargetWrapper', 'string', ['string', 'string', 'string', 'string', 'string']);
 
-const generateRestTestWrapper = lib.func('generateRestTestWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'bool', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'string', 'string']);
-const generateRestMockWrapper = lib.func('generateRestMockWrapper', 'string', ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'string', 'string', 'string', 'string', 'string', 'string']);
+const generateRestTestWrapper = lib.func('generateRestTestWrapper', 'string', [
+    'string',       // test
+    'string',       // uri
+    'string',       // methodX
+    'string',       // language
+    'string',       // framework
+    'string',       // output
+    'string',       // outputDir
+    'string',       // runtime
+    'string',       // dockerNetwork
+    'string',       // dockerWorkerPort
+    'string',       // k8sNamespace
+    'string',       // k8sConfig
+    'string',       // k8sContxt
+    'string',       // authHeader
+    'string',       // authType
+    'string',       // requestData
+    'string',       // responseData
+    'string',       // responseStatusCode
+    'bool',         // force
+    'bool',         // deployDashboard
+    'string',       // formParams
+    'string',       // pathParams
+    'string',       // queryParams
+    'string',       // apiSchema
+    'string',       // trafeFilePath
+    'string',       // generateInclude
+    'string',       // generateExclude
+    'string',       // generateNoProxy
+    'bool',         // generateInsecure
+    'string',       // assertOption
+    'bool',         // playwright
+    'string',       // playwrightOutput
+    'string',       // playwrightInput
+    'string',       // playwrightViewportSize
+    'string',       // playwrightStoragePath
+    'string',       // playwrightSaveStoragePath
+    'string',       // browser
+    'string',       // device
+    'string',       // loadCount
+    'string',       // loadDuration
+    'string',       // loadNumThreads
+    'string',       // loadRampupDuration
+    'string',       // loadRampupInterval
+    'string',       // loadTargetRPS
+    'string',       // rawTrace
+    'bool',         // unblock
+    'string',       // entrypoint
+    'string',       // chainingKey
+    'string',       // parentRequestData
+    'string',       // parentStatusCode
+    'bool',         // requestAware
+    'bool',         // providerMode
+    'bool',         // consumerMode
+    'string',       // providerOutput (contract test)
+    'string',        // consumerOutput (contract test)
+    'bool'          // skipProvisionParents
+]);
+const generateRestMockWrapper = lib.func('generateRestMockWrapper', 'string', [
+    'string',       // uri
+    'string',       // methodX
+    'string',       // language
+    'string',       // framework
+    'string',       // output
+    'string',       // outputDir
+    'string',       // runtime
+    'string',       // dockerNetwork
+    'string',       // dockerWorkerPort
+    'string',       // k8sNamespace
+    'string',       // k8sConfig
+    'string',       // k8sContext
+    'string',       // responseData
+    'string',       // responseStatusCode
+    'bool',         // force
+    'bool',         // deployDashboard
+    'bool',         // requestAware
+    'string',       // formParams
+    'string',       // pathParams
+    'string',       // queryParams
+    'string',       // apiSchema
+    'string',       // traceFilePath
+    'string'        // entryPoint
+]);
 const traceCollectWrapper = lib.func('traceCollectWrapper', 'string', ['string', 'string', 'bool', 'string', 'string']);
 const analyzeOpenapiWrapper = lib.func('analyzeOpenapiWrapper', 'string', ['string', 'string']);
-const initAgentWrapper = lib.func('initAgent', 'string', ['string', 'string']);
+const initAgentWrapper = lib.func('initAgent', 'string', []);
 
 // Load test scenario support
 const sendScenarioWrapper = lib.func('sendScenarioWrapper', contractResponseType, ['string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'string', 'bool', 'bool', 'bool']);
@@ -471,6 +554,24 @@ class SkyrampClient {
     });
   }
 
+  /**
+   * Removes all mock configurations from the worker.
+   * @returns {Promise} A promise that resolves when all mocks are removed successfully
+   */
+  async removeAllMocks() {
+    return new Promise((resolve, reject) => {
+      removeMocksObjectWrapper.async((err, res) => {
+        if (err) {
+          reject(err);
+        } else if (res) {
+          reject(new Error(res));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
   async testerStart(namespace, kubePath, kubeContext, clusterName, address, scenario) {
     const preparedScenario = scenario.prepareTestDescription();
     const testDescription = createTestDescriptionFromScenario({ scenario: preparedScenario });
@@ -788,6 +889,13 @@ class SkyrampClient {
 
   async generateRestTest(options) {
     return new Promise((resolve, reject) => {
+      const parentRequestData = typeof options.parentRequestData === 'string'
+        ? options.parentRequestData
+        : JSON.stringify(options.parentRequestData || {});
+      const parentStatusCode = typeof options.parentStatusCode === 'string'
+        ? options.parentStatusCode
+        : JSON.stringify(options.parentStatusCode || {});
+
       generateRestTestWrapper.async(
         options.testType || "",
         options.uri || "",
@@ -837,6 +945,14 @@ class SkyrampClient {
         options.unblock || false,
         options.entrypoint || "",
         options.chainingKey || "",
+        parentRequestData || "",
+        parentStatusCode || "",
+        options.requestAware || false,
+        options.providerMode || true,
+        options.consumerMode || false,
+        options.providerOutput || "",
+        options.consumerOutput || "",
+        options.skipProvisionParents || true,
         (err, res) => {
           if (err) {
             reject(err);
@@ -867,6 +983,7 @@ class SkyrampClient {
         options.responseStatusCode || "",
         options.force || false,
         options.deployDashboard || false,
+        options.requestAware || false,
         options.formParams || "",
         options.pathParams || "",
         options.queryParams || "",
@@ -1007,26 +1124,11 @@ class SkyrampClient {
 
   /**
    * Initializes the agent by checking and pulling required Docker images (executor and worker).
-   * @param {Object} options - The options for initializing the agent.
-   * @param {string} options.version - The version of the agent to initialize.
-   * @param {string} [options.entryPoint='vscode'] - The entry point identifier (e.g., 'vscode').
    * @returns {Promise<string>} A promise that resolves with the initialization output message.
    */
-  async initAgent(options) {
+  async initAgent() {
     await checkForUpdate("npm");
-    return new Promise((resolve, reject) => {
-      initAgentWrapper.async(
-        options.version || "",
-        options.entryPoint || "vscode",
-        (err, res) => {
-          if (err) {
-            reject(err);
-          } else {
-            resolve(res);
-          }
-        }
-      );
-    });
+    return promisify(initAgentWrapper.async)();
   }
 }
 

package/src/classes/SmartPlaywright.js

@@ -724,6 +724,11 @@ class SkyrampPlaywrightLocator {
         return this._skyrampPage.newSkyrampPlaywrightLocator(new_locator, null, null);
     }
 
+    contentFrame() {
+        const frameLocator = this._locator.contentFrame();
+        return new SkyrampPlaywrightFrameLocator(this._skyrampPage, frameLocator);
+    }
+
     page() {
         return this._skyrampPage._page;
     }
@@ -734,6 +739,91 @@ class SkyrampPlaywrightLocator {
     }
 }
 
+class SkyrampPlaywrightFrameLocator {
+    constructor(skyrampPage, frameLocator) {
+        this._skyrampPage = skyrampPage
+        this._frameLocator = frameLocator
+        debug(`SkyrampPlaywrightFrameLocator instantiated for ${frameLocator}`)
+        return new Proxy(this, {
+            get(wrapper, prop, receiver) {
+                if (Reflect.has(wrapper, prop)) {
+                    return Reflect.get(wrapper, prop, receiver);
+                }
+                const value = Reflect.get(wrapper._frameLocator, prop, wrapper._frameLocator);
+                if (typeof value === 'function') {
+                    return value.bind(wrapper._frameLocator);
+                }
+                return value;
+            }
+        });
+    }
+
+    locator(selector, options) {
+        const originalLocator = this._frameLocator.locator(selector, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, selector, options);
+    }
+
+    getByRole(role, options) {
+        const originalLocator = this._frameLocator.getByRole(role, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, role, options);
+    }
+
+    getByText(text, options) {
+        const originalLocator = this._frameLocator.getByText(text, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, text, options);
+    }
+
+    getByLabel(label, options) {
+        const originalLocator = this._frameLocator.getByLabel(label, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, label, options);
+    }
+
+    getByTestId(testId, options) {
+        const originalLocator = this._frameLocator.getByTestId(testId);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, testId, options);
+    }
+
+    getByTitle(title, options) {
+        const originalLocator = this._frameLocator.getByTitle(title, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, title, options);
+    }
+
+    getByPlaceholder(placeholder, options) {
+        const originalLocator = this._frameLocator.getByPlaceholder(placeholder, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, placeholder, options);
+    }
+
+    getByAltText(alt, options) {
+        const originalLocator = this._frameLocator.getByAltText(alt, options);
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, alt, options);
+    }
+
+    owner() {
+        const originalLocator = this._frameLocator.owner();
+        return this._skyrampPage.newSkyrampPlaywrightLocator(originalLocator, null, null);
+    }
+
+    frameLocator(selector) {
+        const originalFrameLocator = this._frameLocator.frameLocator(selector);
+        return new SkyrampPlaywrightFrameLocator(this._skyrampPage, originalFrameLocator);
+    }
+
+    nth(index) {
+        const originalFrameLocator = this._frameLocator.nth(index);
+        return new SkyrampPlaywrightFrameLocator(this._skyrampPage, originalFrameLocator);
+    }
+
+    first() {
+        const originalFrameLocator = this._frameLocator.first();
+        return new SkyrampPlaywrightFrameLocator(this._skyrampPage, originalFrameLocator);
+    }
+
+    last() {
+        const originalFrameLocator = this._frameLocator.last();
+        return new SkyrampPlaywrightFrameLocator(this._skyrampPage, originalFrameLocator);
+    }
+}
+
 class SkyrampPlaywrightPage {
     constructor(page, testInfo) {
         checkForUpdate("npm").catch((error) => {

package/src/function.d.ts

@@ -18,3 +18,17 @@ export function checkStatusCode(
   response: ResponseV2,
   expectedStatus: string
 ): boolean;
+
+/**
+ * Validates that a request payload matches the expected reference payload.
+ * The reference is a stripped version of the recorded payload (volatile/falsy
+ * values removed). Throws an Error with details if validation fails.
+ *
+ * @param payload   - The actual request payload (e.g. from response.request().postDataJSON()).
+ * @param reference - The expected (stripped) reference payload.
+ * @throws {Error} If the payload does not match the reference.
+ */
+export function checkRequestPayload(
+  payload: object,
+  reference: object
+): void;

package/src/function.js

@@ -41,6 +41,151 @@ const checkStatusCodeWrapper = lib.func('checkStatusCodeWrapper', 'int', ['int',
     }
   }
 
+/**
+ * Returns true if a value is "truthy" for payload comparison purposes.
+ * Truthy: true, non-empty string, non-zero number, non-empty object/array.
+ * Falsy: false, null, undefined, 0, "", empty object, empty array.
+ * @param {*} value
+ * @returns {boolean}
+ */
+function _isTruthy(value) {
+  if (value === null || value === undefined || value === false || value === 0 || value === '') {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0 && value.some(elem => _isTruthy(elem));
+  }
+  if (typeof value === 'object') {
+    return Object.keys(value).length > 0;
+  }
+  return true;
+}
+
+/**
+ * Returns true if a field key indicates a server-generated ID.
+ * @param {string} key
+ * @returns {boolean}
+ */
+function _isVolatileKey(key) {
+  return key === 'id' || key.endsWith('_id');
+}
+
+/**
+ * Returns true if a string value matches a known volatile pattern.
+ * @param {string} s
+ * @returns {boolean}
+ */
+function _isVolatileValue(value) {
+  if (typeof value === 'string') {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value) ||
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:?\d{2})$/.test(value) ||
+      /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(value) ||
+      /^[0-9a-f]{24}$/i.test(value) ||
+      /^[0-9a-f]{32,}$/i.test(value) ||
+      /^https?:\/\/\S+\/[0-9a-f]{24,}/i.test(value);
+  }
+  if (typeof value === 'number') {
+    return value >= 1_000_000_000;
+  }
+  return false;
+}
+
+/**
+ * Recursively compares an actual request payload against a stripped reference
+ * payload. Returns an array of path-annotated error strings.
+ *
+ * Rules:
+ * - Every field in reference must exist in actual with the same value.
+ * - Every truthy field in actual that is NOT in reference is an error,
+ *   unless the key or value matches a known volatile pattern.
+ * - Arrays must have the same length; null reference elements are skipped (volatile).
+ *
+ * @param {*} actual
+ * @param {*} reference
+ * @param {string} [path]
+ * @returns {string[]}
+ */
+function _comparePayload(actual, reference, path) {
+  const loc = path || 'root';
+  const errors = [];
+
+  // Null reference element means volatile/falsy — skip
+  if (reference === null || reference === undefined) {
+    return errors;
+  }
+
+  if (actual === null || actual === undefined) {
+    errors.push(`${loc}: expected ${JSON.stringify(reference)}, got ${actual}`);
+    return errors;
+  }
+
+  // Array comparison
+  if (Array.isArray(reference)) {
+    if (!Array.isArray(actual)) {
+      errors.push(`${loc}: expected array, got ${typeof actual}`);
+      return errors;
+    }
+    if (actual.length !== reference.length) {
+      errors.push(`${loc}: expected array length ${reference.length}, got ${actual.length}`);
+      return errors;
+    }
+    for (let i = 0; i < reference.length; i++) {
+      if (reference[i] === null) continue; // volatile element — skip
+      errors.push(..._comparePayload(actual[i], reference[i], `${loc}[${i}]`));
+    }
+    return errors;
+  }
+
+  // Object comparison
+  if (typeof reference === 'object') {
+    if (typeof actual !== 'object' || Array.isArray(actual)) {
+      errors.push(`${loc}: expected object, got ${Array.isArray(actual) ? 'array' : typeof actual}`);
+      return errors;
+    }
+    // Check all reference fields exist and match
+    for (const key of Object.keys(reference)) {
+      if (!(key in actual)) {
+        errors.push(`${loc}.${key}: missing (expected ${JSON.stringify(reference[key])})`);
+      } else {
+        errors.push(..._comparePayload(actual[key], reference[key], `${loc}.${key}`));
+      }
+    }
+    // Check for unexpected truthy fields in actual (skip volatile keys/values)
+    for (const key of Object.keys(actual)) {
+      if (!(key in reference) && _isTruthy(actual[key]) && !_isVolatileKey(key) && !_isVolatileValue(actual[key])) {
+        errors.push(`${loc}.${key}: unexpected truthy field (value: ${JSON.stringify(actual[key])})`);
+      }
+    }
+    return errors;
+  }
+
+  // Primitive comparison
+  if (actual !== reference) {
+    errors.push(`${loc}: expected ${JSON.stringify(reference)}, got ${JSON.stringify(actual)}`);
+  }
+
+  return errors;
+}
+
+/**
+ * Validates that a request payload matches the expected reference payload.
+ * The reference is a stripped version of the recorded payload (volatile/falsy
+ * values removed). Throws an Error with details if validation fails.
+ *
+ * @param {object} payload   - The actual request payload (e.g. from response.request().postDataJSON()).
+ * @param {object} reference - The expected (stripped) reference payload.
+ * @throws {Error} If the payload does not match the reference.
+ */
+function checkRequestPayload(payload, reference) {
+  const errors = _comparePayload(payload, reference, '');
+  if (errors.length > 0) {
+    throw new Error(
+      `Request payload validation failed:\n${errors.join('\n')}`
+    );
+  }
+}
+
   module.exports = {
-    checkStatusCode
+    checkStatusCode,
+    checkRequestPayload,
   };

package/src/index.js

@@ -17,8 +17,8 @@ const { AsyncScenario, AsyncRequest } = require('./classes/AsyncScenario');
 const { LoadTestConfig } = require('./classes/LoadTestConfig');
 const AsyncTestStatus = require('./classes/AsyncTestStatus');
 const MockV2 = require('./classes/MockV2');
-const { getValue, getResponseValue, checkSchema, iterate, pushToolEvent } = require('./utils');
-const { checkStatusCode } = require('./function');
+const { getValue, getResponseValue, checkSchema, iterate, pushToolEvent, getBaseUrl } = require('./utils');
+const { checkStatusCode, checkRequestPayload } = require('./function');
 const { newSkyrampPlaywrightPage, expect } = require('./classes/SmartPlaywright');
 const {
   workspaceConfigSchema,
@@ -54,9 +54,11 @@ module.exports = {
   getValue,
   getResponseValue,
   checkStatusCode,
+  checkRequestPayload,
   checkSchema,
   iterate,
   pushToolEvent,
+  getBaseUrl,
   newSkyrampPlaywrightPage,
   expect,
   workspaceConfigSchema,

package/src/utils.d.ts

@@ -104,3 +104,11 @@ export function checkForUpdate(component: string): Promise<void>;
  * The Skyramp YAML version constant.
  */
 export const SKYRAMP_YAML_VERSION: string;
+
+/**
+ * Returns the base URL from an environment variable, with a fallback default.
+ * @param envVar - The environment variable name
+ * @param defaultUrl - The default URL if the env var is not set
+ * @returns The resolved base URL
+ */
+export function getBaseUrl(envVar: string, defaultUrl: string): string;

package/src/utils.js

@@ -257,6 +257,10 @@ function checkForUpdate(component) {
     });
 }
 
+function getBaseUrl(envVar, defaultUrl) {
+    return process.env[envVar] ?? defaultUrl;
+}
+
 module.exports = {
   createTestDescriptionFromScenario,
   getYamlBytes,
@@ -267,5 +271,6 @@ module.exports = {
   iterate,
   pushToolEvent,
   checkForUpdate,
+  getBaseUrl,
   SKYRAMP_YAML_VERSION
 }