[Recorder] Add custom matcher support (#20404)

* CustomDefaultMatcher

* changelog

* Maor's improvements

Author: HarshaNalluru

sdk/test-utils/recorder/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## 2.0.0 (Unreleased)
 
+## 2022-02-15
+
+- Bug Fix - Fixed the bug where the `recordingId` was being ignored in the add-sanitizer requests which led the test level sanitizers to be treated as session level sanitizers.
+  [#20393](https://github.com/Azure/azure-sdk-for-js/pull/20393)
+- `CustomDefaultMatcher`- exposes the default matcher in a customizable way. Currently, this includes enabling/disabling body match, adding additional excluded headers, and enable/disable matching the order of query params in the requests.
+  [#20404](https://github.com/Azure/azure-sdk-for-js/pull/20404)
+
 ## 2022-02-04
 
 - [#19920](https://github.com/Azure/azure-sdk-for-js/pull/19920) Added support for adding polices as part of the client options with the new "additionalPolicies" array.

sdk/test-utils/recorder/src/index.ts

@@ -13,3 +13,4 @@ export {
 } from "./utils/utils";
 export { env } from "./utils/env";
 export { delay } from "./utils/delay";
+export { CustomMatcherOptions } from "./matcher";

sdk/test-utils/recorder/src/matcher.ts

@@ -5,13 +5,49 @@ import { createPipelineRequest, HttpClient } from "@azure/core-rest-pipeline";
 import { paths } from "./utils/paths";
 import { RecorderError } from "./utils/utils";
 
-export type Matcher = "HeaderlessMatcher" | "BodilessMatcher";
+export type Matcher = "HeaderlessMatcher" | "BodilessMatcher" | "CustomDefaultMatcher";
+
+/**
+ * Body the customer matcher expects.
+ */
+export interface CustomMatcherOptions {
+  /**
+   * Should the body value be compared during lookup operations?
+   */
+  compareBodies?: boolean;
+  /**
+   * Array of additional headers that should be excluded during matching.
+   */
+  excludedHeaders?: string[];
+  /**
+   * By default, the test-proxy does not sort query params before matching. Setting true will sort query params alphabetically before comparing URI.
+   */
+  ignoreQueryOrdering?: boolean;
+}
+
+/**
+ * Body the customer matcher expects.
+ *
+ * // Ignored Headers option is not exposed to the users as of now.
+ * // If needed, this can be moved into CustomMatcherOptions.
+ */
+interface InternalCustomMatcherOptions extends CustomMatcherOptions {
+  /**
+   * Array of additional headers that should be ignored during matching.
+   * Any headers that are "ignored" will not do value comparison when matching.
+   * This means that if the recording has a header that isn't in the request, a test mismatch exception will be thrown noting the lack of header in the request.
+   *
+   * This also applies if the header is present in the request but not recording.
+   */
+  ignoredHeaders?: string[];
+}
 
 export async function setMatcher(
   recorderUrl: string,
   httpClient: HttpClient,
   matcher: Matcher,
-  recordingId?: string
+  recordingId?: string,
+  matcherBody: InternalCustomMatcherOptions = { compareBodies: true, ignoreQueryOrdering: false }
 ): Promise<void> {
   const url = `${recorderUrl}${paths.admin}${paths.setMatcher}`;
 
@@ -20,7 +56,14 @@ export async function setMatcher(
   if (recordingId) {
     request.headers.set("x-recording-id", recordingId);
   }
-
+  if (matcherBody) {
+    request.body = JSON.stringify({
+      compareBodies: matcherBody.compareBodies,
+      excludedHeaders: matcherBody.excludedHeaders?.toString(),
+      ignoredHeaders: matcherBody.ignoredHeaders?.toString(),
+      ignoreQueryOrdering: matcherBody.ignoreQueryOrdering,
+    });
+  }
   const { status, bodyAsText } = await httpClient.sendRequest(request);
 
   if (status < 200 || status > 299) {

sdk/test-utils/recorder/src/recorder.ts

@@ -26,7 +26,7 @@ import { SanitizerOptions } from "./utils/utils";
 import { paths } from "./utils/paths";
 import { addSanitizers, transformsInfo } from "./sanitizer";
 import { handleEnvSetup } from "./utils/envSetupForPlayback";
-import { Matcher, setMatcher } from "./matcher";
+import { CustomMatcherOptions, Matcher, setMatcher } from "./matcher";
 import {
   DefaultHttpClient,
   HttpClient as HttpClientCoreV1,
@@ -204,13 +204,21 @@ export class Recorder {
   /**
    * Sets the matcher for the current recording to the matcher specified.
    */
-  async setMatcher(matcher: Matcher): Promise<void> {
+  async setMatcher(matcher: "HeaderlessMatcher" | "BodilessMatcher"): Promise<void>;
+  /**
+   * Sets the matcher for the current recording to the matcher specified.
+   */
+  async setMatcher(matcher: "CustomDefaultMatcher", options?: CustomMatcherOptions): Promise<void>;
+  /**
+   * Sets the matcher for the current recording to the matcher specified.
+   */
+  async setMatcher(matcher: Matcher, options?: CustomMatcherOptions): Promise<void> {
     if (isPlaybackMode()) {
       if (!this.httpClient) {
         throw new RecorderError("httpClient should be defined in playback mode");
       }
 
-      await setMatcher(this.url, this.httpClient, matcher, this.recordingId);
+      await setMatcher(this.url, this.httpClient, matcher, this.recordingId, options);
     }
   }
 

sdk/test-utils/recorder/test/testProxyTests.spec.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT license.
 
 import { ServiceClient } from "@azure/core-client";
-import { isPlaybackMode, Recorder } from "../src";
+import { CustomMatcherOptions, isPlaybackMode, Recorder } from "../src";
 import { isLiveMode, TestMode } from "../src/utils/utils";
 import { getTestServerUrl, makeRequestAndVerifyResponse, setTestMode } from "./utils/utils";
 
@@ -102,6 +102,125 @@ import { getTestServerUrl, makeRequestAndVerifyResponse, setTestMode } from "./u
           { val: "abc" }
         );
       });
+
+      describe("CustomDefaultMatcher", () => {
+        it("excludedHeaders - header value is different", async () => {
+          const headerName = `X-Test-Dynamic-Header`;
+          await recorder.start({ envSetupForPlayback: {} });
+          await recorder.setMatcher("CustomDefaultMatcher", {
+            excludedHeaders: [headerName],
+          });
+
+          const testHeader = {
+            headerName, // dynamic header
+            value: isPlaybackMode() ? "playback" : "record",
+          };
+
+          await makeRequestAndVerifyResponse(
+            client,
+            {
+              path: `/sample_response`,
+              body: "body",
+              method: "POST",
+              headers: [{ headerName: "Content-Type", value: "text/plain" }, testHeader],
+            },
+            { val: "abc" }
+          );
+        });
+
+        it("excludedHeaders - header is non-existent", async () => {
+          const headerName = `X-Test-Dynamic-Header`;
+          await recorder.start({ envSetupForPlayback: {} });
+          await recorder.setMatcher("CustomDefaultMatcher", {
+            excludedHeaders: [headerName],
+          });
+
+          const testHeader = {
+            headerName, // dynamic header
+            value: "record",
+          };
+
+          await makeRequestAndVerifyResponse(
+            client,
+            {
+              path: `/sample_response`,
+              body: "body",
+              method: "POST",
+              headers: [{ headerName: "Content-Type", value: "text/plain" }].concat(
+                !isPlaybackMode() ? [testHeader] : []
+              ),
+            },
+            { val: "abc" }
+          );
+        });
+
+        it("ignoredHeaders", async () => {
+          const headerName = `X-Test-Dynamic-Header`;
+          await recorder.start({ envSetupForPlayback: {} });
+          await recorder.setMatcher("CustomDefaultMatcher", {
+            ignoredHeaders: [headerName],
+          } as CustomMatcherOptions);
+
+          const testHeader = {
+            headerName, // dynamic header
+            value: isPlaybackMode() ? "playback" : "record",
+          };
+
+          await makeRequestAndVerifyResponse(
+            client,
+            {
+              path: `/sample_response`,
+              body: "body",
+              method: "POST",
+              headers: [{ headerName: "Content-Type", value: "text/plain" }, testHeader],
+            },
+            { val: "abc" }
+          );
+        });
+
+        it("compareBodies", async () => {
+          await recorder.start({ envSetupForPlayback: {} });
+          await recorder.setMatcher("CustomDefaultMatcher", {
+            compareBodies: false,
+            ignoredHeaders: ["Content-Length"], // adding this header since the body sizes are different
+          } as CustomMatcherOptions);
+
+          // The body shouldn't matter for the match; verify this by using a
+          // different body in playback vs record mode.
+          const body = isPlaybackMode() ? "playback" : "record";
+
+          await makeRequestAndVerifyResponse(
+            client,
+            {
+              path: `/sample_response`,
+              body,
+              method: "POST",
+              headers: [{ headerName: "Content-Type", value: "text/plain" }],
+            },
+            { val: "abc" }
+          );
+        });
+
+        it("ignoreQueryOrdering", async () => {
+          await recorder.start({ envSetupForPlayback: {} });
+          await recorder.setMatcher("CustomDefaultMatcher", {
+            ignoreQueryOrdering: true,
+          });
+
+          await makeRequestAndVerifyResponse(
+            client,
+            {
+              path: `/sample_response${
+                isPlaybackMode() ? "?first=abc&second=def" : "?second=def&first=abc"
+              }`,
+              body: undefined,
+              method: "POST",
+              headers: [{ headerName: "Content-Type", value: "text/plain" }],
+            },
+            { val: "abc" }
+          );
+        });
+      });
     });
 
     // Transforms