Core Recording

/**
 * This client manages the recorder life cycle and interacts with the proxy-tool to do the recording,
 * eventually save them in record mode and playing them back in playback mode.
 */
class Recorder {
  /** Current recording session ID */
  recordingId?: string;
  
  /**
   * Creates a new Recorder instance
   * @param testContext - Test context information for determining recording file paths (required in practice)
   * @throws Error if testContext is undefined
   */
  constructor(testContext?: TestInfo);
  
  /**
   * Starts a recording session with specified options
   * @param options - Configuration for the recording session
   */
  async start(options: RecorderStartOptions): Promise<void>;
  
  /**
   * Stops the current recording session
   */
  async stop(): Promise<void>;
  
  /**
   * Configures client options to add recorder policy for Azure SDK clients
   * @param options - Client options to configure
   * @returns Modified options with recorder policy added
   */
  configureClientOptions<T, U>(options: T & { additionalPolicies?: U[] }): T & { additionalPolicies?: U[] };
  
  /**
   * Sets a variable value for use in recordings
   * @param name - Variable name
   * @param value - Variable value
   * @returns The set value
   */
  variable(name: string, value: string): string;
  
  /**
   * Gets a variable value from recordings
   * @param name - Variable name
   * @returns The variable value
   */
  variable(name: string): string;
  
  /**
   * Adds sanitizers to the current recording session
   * @param options - Sanitizer configuration
   * @param mode - Recording modes to apply sanitizers to
   */
  async addSanitizers(options: SanitizerOptions, mode?: ("record" | "playback")[]): Promise<void>;
  
  /**
   * Adds session-level sanitizers that apply across all recording sessions
   * @param options - Sanitizer configuration
   * @param mode - Recording modes to apply sanitizers to
   */
  static async addSessionSanitizers(options: SanitizerOptions, mode?: ("record" | "playback")[]): Promise<void>;
  
  /**
   * Adds a transform to modify requests/responses during recording or playback
   * @param transform - Transform configuration
   */
  async addTransform(transform: Transform): Promise<void>;
  
  /**
   * Sets a predefined matcher for request matching during playback
   * @param matcher - Matcher type to use
   */
  async setMatcher(matcher: "HeaderlessMatcher" | "BodilessMatcher"): Promise<void>;
  
  /**
   * Sets a custom matcher with specific options for request matching during playback
   * @param matcher - Custom matcher type
   * @param options - Matcher configuration options
   */
  async setMatcher(matcher: "CustomDefaultMatcher", options?: CustomMatcherOptions): Promise<void>;
  
  /**
   * Gets information about currently configured transforms
   * @returns Transform information as string or null
   */
  async transformsInfo(): Promise<string | null | undefined>;
}

import { Recorder } from "@azure-tools/test-recorder";

// Basic recorder setup
const recorder = new Recorder(testContext);

await recorder.start({
  envSetupForPlayback: {
    "AZURE_CLIENT_ID": "fake-client-id",
    "AZURE_CLIENT_SECRET": "fake-secret",
    "AZURE_TENANT_ID": "fake-tenant-id"
  }
});

// Configure Azure SDK client
import { BlobServiceClient } from "@azure/storage-blob";
const client = new BlobServiceClient(
  connectionString, 
  recorder.configureClientOptions({})
);

// Use variables for dynamic content
const containerName = recorder.variable("containerName", `test-${Date.now()}`);

// Stop recording
await recorder.stop();

/**
 * Configuration options for starting a recording session
 */
interface RecorderStartOptions {
  /** Environment variables to set up for playback mode */
  envSetupForPlayback: Record<string, string>;
  /** Optional sanitizer configuration */
  sanitizerOptions?: SanitizerOptions;
  /** Optional TLS validation certificate */
  tlsValidationCert?: string;
  /** List of central sanitizers to remove */
  removeCentralSanitizers?: string[];
}

// Basic environment setup
const startOptions: RecorderStartOptions = {
  envSetupForPlayback: {
    "AZURE_STORAGE_CONNECTION_STRING": "fake-connection-string",
    "AZURE_CLIENT_ID": "fake-client-id"
  }
};

// With inline sanitizers
const startOptionsWithSanitizers: RecorderStartOptions = {
  envSetupForPlayback: {
    "API_KEY": "fake-api-key"
  },
  sanitizerOptions: {
    generalSanitizers: [
      { target: "real-secret", value: "sanitized-secret" }
    ]
  }
};

await recorder.start(startOptionsWithSanitizers);

/**
 * Sets a variable value for use in recordings
 * @param name - Variable name
 * @param value - Variable value to store
 * @returns The stored value
 */
variable(name: string, value: string): string;

/**
 * Gets a variable value from recordings
 * @param name - Variable name to retrieve
 * @returns The stored variable value
 */
variable(name: string): string;

// Set variables during recording for consistent playback
const uniqueId = recorder.variable("testId", `test-${Date.now()}-${Math.random()}`);
const resourceName = recorder.variable("resourceName", `resource-${uniqueId}`);

// In subsequent tests, these will return the same values from the recording
const savedId = recorder.variable("testId"); // Returns the recorded value
const savedResource = recorder.variable("resourceName"); // Returns the recorded value

// Use in Azure SDK operations
const containerClient = blobServiceClient.getContainerClient(
  recorder.variable("containerName", `test-container-${Date.now()}`)
);

/**
 * Configures client options to add recorder policy for Azure SDK clients
 * @param options - Original client options
 * @returns Modified options with recorder policy injected
 */
configureClientOptions<T, U>(options: T & { additionalPolicies?: U[] }): T & { additionalPolicies?: U[] };

import { BlobServiceClient } from "@azure/storage-blob";
import { KeyVaultSecrets } from "@azure/keyvault-secrets";

// Configure blob storage client
const blobClient = new BlobServiceClient(
  connectionString,
  recorder.configureClientOptions({
    retryOptions: { maxRetries: 3 }
  })
);

// Configure Key Vault client with custom options
const keyVaultClient = new KeyVaultSecrets(
  vaultUrl,
  credential,
  recorder.configureClientOptions({
    additionalPolicies: [customPolicy],
    requestPolicyFactories: [customPolicyFactory]
  })
);

// The recorder policy will be automatically added to capture HTTP traffic