@azure-tools/typespec-ts 0.54.1 → 0.55.0-dev.2

package/src/modular/emit-tests.ts

@@ -0,0 +1,194 @@
+import { existsSync, rmSync } from "fs";
+import { join } from "path";
+import { SourceFile } from "ts-morph";
+import { resolveReference } from "../framework/reference.js";
+import { NameType, normalizeName } from "../rlc-common/index.js";
+import { SdkContext } from "../utils/interfaces.js";
+import { ServiceOperation } from "../utils/operation-util.js";
+import { AzureTestDependencies } from "./external-dependencies.js";
+import {
+  buildParameterValueMap,
+  ClientEmitOptions,
+  createSourceFile,
+  generateMethodCall,
+  generateResponseAssertions,
+  getDescriptiveName,
+  iterateClientsAndMethods,
+  prepareCommonParameters,
+} from "./helpers/example-value-helpers.js";
+import { getClassicalClientName } from "./helpers/naming-helpers.js";
+import { CreateRecorderHelpers } from "./static-helpers-metadata.js";
+
+/**
+ * Clean up the test/generated folder before generating new tests
+ */
+async function cleanupTestFolder(dpgContext: SdkContext) {
+  const clients = dpgContext.sdkPackage.clients;
+  const baseTestFolder = join(dpgContext.generationPathDetail?.rootDir ?? "", "test", "generated");
+
+  // If there are multiple clients, clean up subfolders
+  if (clients.length > 1) {
+    for (const client of clients) {
+      const subFolder = normalizeName(getClassicalClientName(client), NameType.File);
+      const clientTestFolder = join(baseTestFolder, subFolder);
+      if (existsSync(clientTestFolder)) {
+        rmSync(clientTestFolder, { recursive: true, force: true });
+      }
+    }
+  } else {
+    // Single client, clean up the entire test/generated folder
+    if (existsSync(baseTestFolder)) {
+      rmSync(baseTestFolder, { recursive: true, force: true });
+    }
+  }
+}
+
+/**
+ * Helpers to emit tests similar to samples
+ */
+export async function emitTests(dpgContext: SdkContext): Promise<SourceFile[]> {
+  // Clean up the test/generated folder before generating new tests
+  await cleanupTestFolder(dpgContext);
+
+  return iterateClientsAndMethods(dpgContext, emitMethodTests);
+}
+
+function emitMethodTests(
+  dpgContext: SdkContext,
+  method: ServiceOperation,
+  options: ClientEmitOptions,
+): SourceFile | undefined {
+  const examples = method.operation.examples ?? [];
+  if (examples.length === 0) {
+    return;
+  }
+
+  const methodPrefix = `${options.classicalMethodPrefix ?? ""} ${method.oriName ?? method.name}`;
+  const fileName = normalizeName(`${methodPrefix} Test`, NameType.File);
+  const sourceFile = createSourceFile(dpgContext, method, options, "test", fileName);
+  const clientName = getClassicalClientName(options.client);
+
+  // Use resolveReference for test dependencies to let the binder handle imports automatically
+  const recorderType = resolveReference(AzureTestDependencies.Recorder);
+  const assertType = resolveReference(AzureTestDependencies.assert);
+  const beforeEachType = resolveReference(AzureTestDependencies.beforeEach);
+  const afterEachType = resolveReference(AzureTestDependencies.afterEach);
+  const itType = resolveReference(AzureTestDependencies.it);
+  const describeType = resolveReference(AzureTestDependencies.describe);
+  const createRecorderHelper = resolveReference(CreateRecorderHelpers.createRecorder);
+
+  // Compute the relative path from the generated test file to src/index.js.
+  // Single-client files land at test/generated/<file>.spec.ts (2 levels up),
+  // while multi-client files land at test/generated/<subFolder>/<file>.spec.ts (3 levels up).
+  const srcIndexRelativePath = options.subFolder ? "../../../src/index.js" : "../../src/index.js";
+
+  // Import the client
+  sourceFile.addImportDeclaration({
+    moduleSpecifier: srcIndexRelativePath,
+    namedImports: [clientName],
+  });
+
+  const testFunctions = [];
+  let clientParamNames: string[] = [];
+  let clientParameterDefs: string[] = [];
+
+  // Create test describe block
+  const methodDescription = method.doc ?? `test ${method.oriName ?? method.name}`;
+  let normalizedDescription =
+    methodDescription.charAt(0).toLowerCase() + methodDescription.slice(1);
+
+  // Remove any trailing dots from describe block
+  normalizedDescription = normalizedDescription.replace(/\.$/, "");
+
+  // Generate test functions for each example
+  for (const example of examples) {
+    const testFunctionBody: string[] = [];
+    // Create a more descriptive test name based on the operation (same as samples)
+    const testName = getDescriptiveName(method, example.name, "test");
+    const parameterMap = buildParameterValueMap(example);
+    const parameters = prepareCommonParameters(dpgContext, method, parameterMap, options.client);
+
+    // Prepare client-level parameters
+    const requiredClientParams = parameters.filter((p) => p.onClient && !p.isOptional);
+    clientParameterDefs = requiredClientParams.map((p) => `const ${p.name} = ${p.value};`);
+    clientParamNames = requiredClientParams.map((p) => p.name);
+    // add client options to parameters
+    // const clientOptions = recorder.configureClientOptions({});
+    clientParamNames.push("clientOptions");
+    clientParameterDefs.push(`const clientOptions = recorder.configureClientOptions({});`);
+
+    const { methodCall } = generateMethodCall(method, parameters, options);
+
+    // Add method call based on type
+    const isPaging = method.kind === "paging";
+    const isLRO = method.kind === "lro" || method.kind === "lropaging";
+
+    if (method.response.type === undefined) {
+      // skip response handling for void methods
+      testFunctionBody.push(`await ${methodCall};`);
+      testFunctionBody.push(`/* Test passes if no exception is thrown */`);
+    } else if (isPaging) {
+      testFunctionBody.push(`const resArray = new Array();`);
+      testFunctionBody.push(`for await (const item of ${methodCall}) { resArray.push(item); }`);
+      testFunctionBody.push(`${assertType}.ok(resArray);`);
+      // Add response assertions for paging results
+      const pagingAssertions = generateResponseAssertions(
+        example,
+        "resArray",
+        true, // isPaging = true
+      );
+      testFunctionBody.push(...pagingAssertions);
+    } else if (isLRO) {
+      testFunctionBody.push(`const result = await ${methodCall};`);
+      testFunctionBody.push(`${assertType}.ok(result);`);
+      // Add response assertions for LRO results
+      const responseAssertions = generateResponseAssertions(example, "result");
+      testFunctionBody.push(...responseAssertions);
+    } else {
+      testFunctionBody.push(`const result = await ${methodCall};`);
+      testFunctionBody.push(`${assertType}.ok(result);`);
+      // Add response assertions for non-paging results
+      const responseAssertions = generateResponseAssertions(example, "result");
+      testFunctionBody.push(...responseAssertions);
+    }
+
+    // Create a test function
+    const testFunction = {
+      name: testName,
+      body: testFunctionBody,
+    };
+
+    testFunctions.push(testFunction);
+  }
+
+  // Create describe block with beforeEach and afterEach
+  const describeBlock = `
+${describeType}("${normalizedDescription}", () => {
+  let recorder: ${recorderType};
+  let client: ${clientName};
+
+  ${beforeEachType}(async function(ctx) {
+    recorder = await ${createRecorderHelper}(ctx);
+    ${clientParameterDefs.join("\n")}
+    client = new ${clientName}(${clientParamNames.join(", ")});
+  });
+
+  ${afterEachType}(async function() {
+    await recorder.stop();
+  });
+
+${testFunctions
+  .map(
+    (fn) => `
+  ${itType}("should ${fn.name}", async function() {
+    ${fn.body.join("\n    ")}
+  });
+`,
+  )
+  .join("")}
+});`;
+
+  sourceFile.addStatements(describeBlock);
+  options.generatedFiles.push(sourceFile);
+  return sourceFile;
+}

package/src/modular/helpers/classical-operation-helpers.ts

@@ -0,0 +1,375 @@
+import { SdkClientType, SdkServiceOperation } from "@azure-tools/typespec-client-generator-core";
+import {
+  FunctionDeclarationStructure,
+  InterfaceDeclarationStructure,
+  OptionalKind,
+  PropertySignatureStructure,
+  SourceFile,
+  StructureKind,
+} from "ts-morph";
+import { addDeclaration } from "../../framework/declaration.js";
+import { resolveReference } from "../../framework/reference.js";
+import { refkey } from "../../framework/refkey.js";
+import { NameType, normalizeName } from "../../rlc-common/index.js";
+import { getModularClientOptions } from "../../utils/client-utils.js";
+import { SdkContext } from "../../utils/interfaces.js";
+import { ServiceOperation } from "../../utils/operation-util.js";
+import { AzurePollingDependencies } from "../external-dependencies.js";
+import { PagingHelpers, SimplePollerHelpers } from "../static-helpers-metadata.js";
+import { getClassicalLayerPrefix } from "./naming-helpers.js";
+import { getOperationFunction } from "./operation-helpers.js";
+
+interface OperationDeclarationInfo {
+  // the operation function
+  declaration: OptionalKind<FunctionDeclarationStructure>;
+  // the original operation name
+  oriName: string | undefined;
+  // the refkey of the operation declaration
+  declarationRefKey: string | undefined;
+  // the default is false
+  isLro?: boolean;
+  // only set when isLro is true
+  lroFinalReturnType?: string;
+  // set to true for LRO+Paging operations
+  isLroPaging?: boolean;
+  // only set when isLroPaging is true
+  lropagingFinalReturnType?: string;
+}
+export function getPagingLROMethodName(operationName: string) {
+  let initialOperationName = normalizeName(operationName, NameType.Operation);
+  if (initialOperationName.indexOf("list") === 0) {
+    initialOperationName = initialOperationName.replace("list", "");
+  } else if (initialOperationName.indexOf("get") === 0) {
+    initialOperationName = initialOperationName.replace("get", "");
+  } else {
+    initialOperationName = normalizeName(initialOperationName, NameType.Class);
+  }
+  return `beginList_${initialOperationName}_andWait`;
+}
+export function getClassicalOperation(
+  dpgContext: SdkContext,
+  clientMap: [string[], SdkClientType<SdkServiceOperation>],
+  classicFile: SourceFile,
+  operationGroup: [string[], ServiceOperation[]],
+  layer: number = operationGroup[0].length - 1,
+) {
+  const prefixes = operationGroup[0];
+  const operations = operationGroup[1];
+  const { rlcClientName } = getModularClientOptions(clientMap);
+  const hasClientContextImport = classicFile.getImportDeclarations().filter((i) => {
+    return (
+      i.getModuleSpecifierValue() ===
+      `${"../".repeat(layer + 2)}api/${normalizeName(rlcClientName, NameType.File)}.js`
+    );
+  });
+  if (!hasClientContextImport || hasClientContextImport.length === 0) {
+    classicFile.addImportDeclaration({
+      namedImports: [rlcClientName],
+      moduleSpecifier: `${"../".repeat(layer + 2)}api/${normalizeName(
+        rlcClientName,
+        NameType.File,
+      )}.js`,
+    });
+  }
+
+  const operationDeclarationMap = new Map<
+    OptionalKind<FunctionDeclarationStructure>,
+    OperationDeclarationInfo | undefined
+  >();
+  const operationDeclarations: OptionalKind<FunctionDeclarationStructure>[] = operations.map(
+    (operation) => {
+      const declaration = getOperationFunction(dpgContext, [prefixes, operation], rlcClientName);
+      operationDeclarationMap.set(declaration, {
+        declaration,
+        oriName: operation.oriName,
+        declarationRefKey: resolveReference(refkey(operation, "api")),
+        isLro: declaration.isLro,
+        lroFinalReturnType: declaration.lroFinalReturnType,
+        isLroPaging: declaration.isLroPaging,
+        lropagingFinalReturnType: declaration.lropagingFinalReturnType,
+      });
+      return declaration;
+    },
+  );
+
+  const interfaceNamePrefix = getClassicalLayerPrefix(prefixes, NameType.Interface, "", layer);
+  const interfaceName = `${interfaceNamePrefix}Operations`;
+  const nextLayerInterfaceName = `${getClassicalLayerPrefix(
+    prefixes,
+    NameType.Interface,
+    "",
+    layer + 1,
+  )}Operations`;
+  const existInterface = classicFile
+    .getInterfaces()
+    .filter((i) => i.getName() === interfaceName)[0];
+  const properties: OptionalKind<PropertySignatureStructure>[] = [];
+  if (layer !== prefixes.length - 1) {
+    const name = normalizeName(
+      (layer === prefixes.length - 1 ? prefixes[layer] : prefixes[layer + 1]) ?? "",
+      NameType.Property,
+    );
+    if (
+      !properties.some((x) => x.name === name) &&
+      !(existInterface && existInterface.getProperty(name))
+    ) {
+      properties.push({
+        kind: StructureKind.PropertySignature,
+        name,
+        type: resolveReference(refkey(nextLayerInterfaceName, layer + 1, "classicOperations")),
+      });
+    }
+  } else {
+    operationDeclarations.forEach((d) => {
+      const operationInfo = operationDeclarationMap.get(d);
+      const paramStr = d.parameters
+        ?.filter((p) => p.name !== "context")
+        .map(
+          (p) =>
+            p.name +
+            (p.type?.toString().endsWith("operationOptions__") || p.hasQuestionToken ? "?" : "") +
+            ": " +
+            p.type,
+        )
+        .join(",");
+      // add the operation method signature
+      properties.push({
+        kind: StructureKind.PropertySignature,
+        name: getClassicalMethodName(d),
+        type: `(${paramStr}) => ${d.returnType}`,
+        docs: d.docs,
+      });
+      // add LRO helper methods if applicable
+      if (
+        dpgContext.rlcOptions?.compatibilityLro &&
+        (operationInfo?.isLro || operationInfo?.isLroPaging)
+      ) {
+        const operationStateReference = resolveReference(AzurePollingDependencies.OperationState);
+        const simplePollerLikeReference = resolveReference(SimplePollerHelpers.SimplePollerLike);
+        const beginName = `begin_${getClassicalMethodName(d)}`;
+        const beginAndWaitName = `${beginName}_andWait`;
+
+        if (operationInfo?.isLroPaging) {
+          // LRO+Paging operation
+          const returnType = operationInfo?.lropagingFinalReturnType ?? "void";
+          const pagedAsyncIterableIteratorReference = resolveReference(
+            PagingHelpers.PagedAsyncIterableIterator,
+          );
+          const beginListAndWaitName = getPagingLROMethodName(getClassicalMethodName(d));
+          properties.push({
+            kind: StructureKind.PropertySignature,
+            name: `${normalizeName(beginListAndWaitName, NameType.Method)}`,
+            type: `(${paramStr}) => ${pagedAsyncIterableIteratorReference}<${returnType}>`,
+            docs: [`@deprecated use ${getClassicalMethodName(d)} instead`],
+          });
+        } else {
+          // Regular LRO operation
+          const returnType = operationInfo?.lroFinalReturnType ?? "void";
+          properties.push({
+            kind: StructureKind.PropertySignature,
+            name: `${normalizeName(beginName, NameType.Method)}`,
+            type: `(${paramStr}) => Promise<${simplePollerLikeReference}<${operationStateReference}<${returnType}>, ${returnType}>>`,
+            docs: [`@deprecated use ${getClassicalMethodName(d)} instead`],
+          });
+          properties.push({
+            kind: StructureKind.PropertySignature,
+            name: `${normalizeName(beginAndWaitName, NameType.Method)}`,
+            type: `(${paramStr}) => Promise<${returnType}>`,
+            docs: [`@deprecated use ${getClassicalMethodName(d)} instead`],
+          });
+        }
+      }
+    });
+  }
+  if (existInterface) {
+    existInterface.addProperties([...properties]);
+  } else {
+    const interfaceDeclaration: InterfaceDeclarationStructure = {
+      kind: StructureKind.Interface,
+      name: interfaceName,
+      isExported: true,
+      properties,
+      docs: [`Interface representing a ${interfaceNamePrefix} operations.`],
+    };
+    addDeclaration(
+      classicFile,
+      interfaceDeclaration,
+      refkey(interfaceName, layer, "classicOperations"),
+    );
+  }
+
+  const functionName = `_get${getClassicalLayerPrefix(prefixes, NameType.Interface, "", layer)}`;
+  if (layer === prefixes.length - 1) {
+    const functionDeclaration: FunctionDeclarationStructure = {
+      kind: StructureKind.Function,
+      name: functionName,
+      isExported: false,
+      parameters: [
+        {
+          name: "context",
+          type: rlcClientName,
+        },
+      ],
+      statements: `return {
+        ${operationDeclarations
+          .map((d) => {
+            const operationInfo = operationDeclarationMap.get(d);
+            const classicalParamStr = d.parameters
+              ?.filter((p) => p.name !== "context")
+              .map(
+                (p) =>
+                  p.name +
+                  (p.type?.toString().endsWith("operationOptions__") || p.hasQuestionToken
+                    ? "?"
+                    : "") +
+                  ": " +
+                  p.type,
+              )
+              .join(",");
+            const apiParamStr = [
+              "context",
+              ...[d.parameters?.map((p) => p.name).filter((p) => p !== "context")],
+            ].join(",");
+            const ret = [
+              `${getClassicalMethodName(d)}: (${classicalParamStr}) => ${operationInfo?.declarationRefKey}(${
+                apiParamStr
+              })`,
+            ];
+            // add LRO helper methods if applicable
+            if (
+              dpgContext.rlcOptions?.compatibilityLro &&
+              (operationInfo?.isLro || operationInfo?.isLroPaging)
+            ) {
+              const getSimplePollerReference = resolveReference(
+                SimplePollerHelpers.getSimplePoller,
+              );
+              const beginName = `begin_${getClassicalMethodName(d)}`;
+              const beginAndWaitName = `${beginName}_andWait`;
+              const beginListAndWaitName = getPagingLROMethodName(getClassicalMethodName(d));
+
+              if (operationInfo?.isLroPaging) {
+                ret.push(
+                  `${normalizeName(
+                    beginListAndWaitName,
+                    NameType.Method,
+                  )}: (${classicalParamStr}) => {
+                    return ${operationInfo?.declarationRefKey}(${apiParamStr});
+                  }`,
+                );
+              } else {
+                // Regular LRO operation
+                ret.push(
+                  `${normalizeName(beginName, NameType.Method)}: async (${classicalParamStr}) => {
+                    const poller = ${operationInfo?.declarationRefKey}(${apiParamStr});
+                    await poller.submitted();
+                    return ${getSimplePollerReference}(poller);
+                  }`,
+                );
+                ret.push(
+                  `${normalizeName(
+                    beginAndWaitName,
+                    NameType.Method,
+                  )}: async (${classicalParamStr}) => {
+                    return await ${operationInfo?.declarationRefKey}(${apiParamStr});
+                  }`,
+                );
+              }
+            }
+            return ret.join(",");
+          })
+          .join(",")}
+      }`,
+    };
+    addDeclaration(
+      classicFile,
+      functionDeclaration,
+      refkey(functionName, layer, "getClassicOperation"),
+    );
+  }
+
+  const operationFunctionName = `_get${getClassicalLayerPrefix(
+    prefixes,
+    NameType.Interface,
+    "",
+    layer,
+  )}Operations`;
+  const nextLayerOperationFunctionName = `_get${getClassicalLayerPrefix(
+    prefixes,
+    NameType.Interface,
+    "",
+    layer + 1,
+  )}Operations`;
+  const existFunction = classicFile
+    .getFunctions()
+    .filter((f) => f.getName() === operationFunctionName)[0];
+  if (existFunction) {
+    const returnStatement = existFunction.getBodyText();
+    if (returnStatement) {
+      let statement: string | undefined = undefined;
+      if (layer !== prefixes.length - 1) {
+        const name = normalizeName(prefixes[layer + 1] ?? "FIXME", NameType.Property);
+
+        // HACK: check if the statement includes a group of this name already to prevent an operation group appearing multiple times
+        // TODO: would be good to refactor so that we have an intermediate data structure before generating the return statement
+        if (!returnStatement.includes(`${name}:`)) {
+          statement = `,
+          ${normalizeName(
+            prefixes[layer + 1] ?? "FIXME",
+            NameType.Property,
+          )}: ${resolveReference(refkey(nextLayerOperationFunctionName, layer + 1, "getClassicOperations"))}(context)}`;
+        }
+      } else {
+        statement = `,
+      ...${resolveReference(refkey(nextLayerOperationFunctionName, layer + 1, "getClassicOperations"))}(context)}`;
+      }
+
+      if (statement) {
+        const newReturnStatement = returnStatement.replace(/}$/, statement);
+        existFunction.setBodyText(newReturnStatement);
+      }
+    }
+  } else {
+    const functions: FunctionDeclarationStructure = {
+      kind: StructureKind.Function,
+      name: operationFunctionName,
+      isExported: true,
+      parameters: [
+        {
+          name: "context",
+          type: rlcClientName,
+        },
+      ],
+      returnType: resolveReference(refkey(interfaceName, layer, "classicOperations")),
+      statements:
+        layer !== prefixes.length - 1
+          ? `return {
+            ${normalizeName(
+              prefixes[layer + 1] ?? "FIXME",
+              NameType.Property,
+            )}: ${resolveReference(refkey(nextLayerOperationFunctionName, layer + 1, "getClassicOperations"))}(context)   
+      }`
+          : `return {
+        ...${resolveReference(refkey(functionName, layer, "getClassicOperation"))}(context)
+      }`,
+    };
+    addDeclaration(
+      classicFile,
+      functions,
+      refkey(operationFunctionName, layer, "getClassicOperations"),
+    );
+  }
+
+  function getClassicalMethodName(
+    declaration: OptionalKind<FunctionDeclarationStructure> & {
+      propertyName?: string;
+    },
+  ) {
+    return normalizeName(
+      operationDeclarationMap.get(declaration)?.oriName ??
+        declaration.propertyName ??
+        declaration.name ??
+        "FIXME",
+      NameType.Method,
+    );
+  }
+}