chore: rename checkResponseFormat to hasResponseFormatIssues and update references with improved JSDoc documentation (#3886)

Signed-off-by: Michał Walczak <[email protected]>

Author: mwb-al

packages/server/tests/acceptance/conformityTests.spec.ts

@@ -34,7 +34,7 @@ import {
   transaction2930,
 } from './data/conformity/utils/transactions';
 import { getLatestBlockHash, sendRequestToRelay, signAndSendRawTransaction } from './data/conformity/utils/utils';
-import { checkResponseFormat, isResponseValid } from './data/conformity/utils/validations';
+import { hasResponseFormatIssues, isResponseValid } from './data/conformity/utils/validations';
 
 const directoryPath = path.resolve(__dirname, '../../../../node_modules/execution-apis/tests');
 const overwritesDirectoryPath = path.resolve(__dirname, 'data/conformity/overwrites');
@@ -60,14 +60,14 @@ const synthesizeTestCases = function (testCases: TestCases, updateParamIfNeeded:
       try {
         const req = updateParamIfNeeded(testName, JSON.parse(testCases[testName].request));
         const res = await sendRequestToRelay(RELAY_URL, req, false);
-        const hasMissingKeys: boolean = checkResponseFormat(res, JSON.parse(testCases[testName].response));
+        const isResFormatInvalid: boolean = hasResponseFormatIssues(res, JSON.parse(testCases[testName].response));
 
         if (schema && schema.pattern) {
           const check = isResponseValid(schema, res);
           expect(check).to.be.true;
         }
 
-        expect(hasMissingKeys).to.be.false;
+        expect(isResFormatInvalid).to.be.false;
         expect(isErrorStatusExpected).to.be.false;
       } catch (e: any) {
         expect(isErrorStatusExpected).to.be.true;
@@ -318,7 +318,7 @@ describe('@api-conformity', async function () {
             });
             await new Promise((r) => setTimeout(r, 500));
 
-            const hasMissingKeys: boolean = checkResponseFormat(response, JSON.parse(testCases[testName].response));
+            const hasMissingKeys: boolean = hasResponseFormatIssues(response, JSON.parse(testCases[testName].response));
             expect(hasMissingKeys).to.be.false;
           });
         }

packages/server/tests/acceptance/data/conformity/utils/processors.ts

@@ -4,7 +4,7 @@ import { expect } from 'chai';
 import { FileContent } from './interfaces';
 import { updateRequestParams } from './overwrites';
 import { sendRequestToRelay } from './utils';
-import { checkResponseFormat, findSchema, isResponseValid } from './validations';
+import { findSchema, hasResponseFormatIssues, isResponseValid } from './validations';
 
 /**
  * Splits a given input string into distinct segments representing the request, the response, and optional wildcard fields.
@@ -83,7 +83,7 @@ export async function processFileContent(relayUrl: string, directory: string, fi
 
   if (needError) {
     console.log('Validating an error response.');
-    const valid = checkResponseFormat(response, content.response, wildcards);
+    const valid = hasResponseFormatIssues(response, content.response, wildcards);
     expect(valid).to.be.false;
     console.log('Error response validation finished.');
   } else {
@@ -99,7 +99,7 @@ export async function processFileContent(relayUrl: string, directory: string, fi
       }
     } else {
       console.log('Using response format check (key-by-key comparison).');
-      const hasMissingKeys = checkResponseFormat(response, JSON.parse(content.response), wildcards);
+      const hasMissingKeys = hasResponseFormatIssues(response, JSON.parse(content.response), wildcards);
       console.log(`Missing keys check result: ${hasMissingKeys}`);
       expect(hasMissingKeys).to.be.false;
     }

packages/server/tests/acceptance/data/conformity/utils/validations.ts

@@ -11,7 +11,47 @@ const execApisOpenRpcData = require('../../../../../../../openrpc_exec_apis.json
 const ajv = new Ajv({ strict: false });
 addFormats(ajv);
 
-export function checkResponseFormat(
+/**
+ * Validates response format by comparing actual response against expected response structure.
+ *
+ * @param actualResponse - The actual response received from the API call
+ * @param expectedResponse - The expected response structure to validate against (can be object, string, or ErrorResponse)
+ * @param wildcards - Array of property paths to ignore during validation (default: empty array)
+ * @returns {boolean} Returns true if the response format has issues (validation failed), false if format is valid
+ *
+ * @description
+ * This function performs comprehensive response validation including:
+ * - Parsing expected response if provided as string
+ * - Checking error state consistency between actual and expected responses
+ * - Missing key detection in response structure
+ * - Deep value comparison with wildcard support
+ *
+ * @example
+ * ```typescript
+ * const actualResponse = { result: "0x123", id: 1 };
+ * const expectedResponse = '{"result": "0x123", "id": 1}';
+ * const hasIssues = hasResponseFormatIssues(actualResponse, expectedResponse);
+ * console.log(hasIssues); // false - format is valid
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const actualResponse = { result: "0x123" };
+ * const expectedResponse = { result: "0x123", id: 1 };
+ * const hasIssues = hasResponseFormatIssues(actualResponse, expectedResponse);
+ * console.log(hasIssues); // true - missing 'id' key
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const actualResponse = { result: "0x123", timestamp: "2023-01-01" };
+ * const expectedResponse = { result: "0x123", timestamp: "2023-01-02" };
+ * const wildcards = ["timestamp"];
+ * const hasIssues = hasResponseFormatIssues(actualResponse, expectedResponse, wildcards);
+ * console.log(hasIssues); // false - timestamp ignored due to wildcard
+ * ```
+ */
+export function hasResponseFormatIssues(
   actualResponse: Record<string, unknown> | ErrorResponse | JsonRpcResponse,
   expectedResponse: Record<string, unknown> | string | ErrorResponse,
   wildcards: string[] = [],