From 5ea3e1bca79c8e9284c5cd9f5b54271207e94952 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Thu, 20 Oct 2022 14:31:21 +0800 Subject: [PATCH 01/13] update-contributing-document --- CONTRIBUTING.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a5974fc94..6ace49536f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,11 +35,18 @@ Want to get started hacking on the code? Great! Keep reading. This contributing ### General Autorest generation design -_TBA_ +Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we currently only support generation from rest api specs, the support of generate high level client from cadl is planning. +This project is managed by rush, there're four components inside the `./packages` folder. +1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. +1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. +1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. +1. `packages/cadl-rlc-test` is for cadl rlc emitter smoke test. ### Typescript/Javascript SDK generator Design -The generated Typescript/Javascript SDK has the following structure: +The generated Typescript/Javascript SDK has the following structure: + +**Please Note that the following content are based on you are already inside the packages/autorest.typescript folder** 1. Client (Handled by [clientFileGenerator.ts](./src/generators/clientFileGenerator.ts)) 2. Client Context (Handled by [clientContextFileGenerator.ts](./src/generators/clientContextFileGenerator.ts)) @@ -72,9 +79,8 @@ git clone https://github.com/Azure/autorest.typescript.git ``` npm install -g @autorest/autorest -cd autorest.typescript -npm install -npm run build +rush update +rush rebuild ``` 3. There are 3 test-suites in the generator: @@ -232,6 +238,6 @@ If your test case is working fine as expected, now you are ready to create the P Our generated SDKs take dependency on various packages which you can see in the generated package.json files. These will need to be upgraded from time to time to stay on the latest major version so that we get bug fixes automatically due to semver. - Update the version of the dependency you are looking for in the methods `restLevelPackage` and/or `regularAutorestPackage` in the [`packageFileGenerator.ts`](https://github.com/Azure/autorest.typescript/blob/main/src/generators/static/packageFileGenerator.ts) file. -- Run `npm run build && npm run generate-swaggers && npm run smoke-tests` to update the generated files in the repo and run smoke tests before creating the PR. +- Run `rush rebuild && npm run generate-swaggers && npm run smoke-tests` to update the generated files in the repo and run smoke tests before creating the PR. For example, see the [PR 1271](https://github.com/Azure/autorest.typescript/pull/1271) that updates the version of `prettier` that the generated SDKs depend on. From b1ae2bdac3ca7c38607e36ff70af689fd17accbc Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 21 Oct 2022 12:18:08 +0800 Subject: [PATCH 02/13] add contributing md --- CONTRIBUTING.md | 195 +---------- packages/autorest.typescript/CONTRiBUTING.md | 348 +++++++++++++++++++ packages/cadl-typescript/CONTRIBUTING.md | 127 +++++++ packages/rlc-common/CONTRIBUTING.md | 21 ++ 4 files changed, 504 insertions(+), 187 deletions(-) create mode 100644 packages/autorest.typescript/CONTRiBUTING.md create mode 100644 packages/cadl-typescript/CONTRIBUTING.md create mode 100644 packages/rlc-common/CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ace49536f..2ec74206ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,195 +33,16 @@ If your contribution is significantly big it is better to first check with the p Want to get started hacking on the code? Great! Keep reading. This contributing guide helps you to start working with and contributing to the Azure Typescript/Javascript SDK Generator. -### General Autorest generation design +### General Introduction -Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we currently only support generation from rest api specs, the support of generate high level client from cadl is planning. +Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we only support generation from rest api specs, the support of generate high level client from cadl is planning. + This project is managed by rush, there're four components inside the `./packages` folder. -1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. -1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. -1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. -1. `packages/cadl-rlc-test` is for cadl rlc emitter smoke test. - -### Typescript/Javascript SDK generator Design - -The generated Typescript/Javascript SDK has the following structure: - -**Please Note that the following content are based on you are already inside the packages/autorest.typescript folder** - -1. Client (Handled by [clientFileGenerator.ts](./src/generators/clientFileGenerator.ts)) -2. Client Context (Handled by [clientContextFileGenerator.ts](./src/generators/clientContextFileGenerator.ts)) -3. Operation Interfaces (Handled by [operationInterfaceGenerator.ts](./src/generators/operationInterfaceGenerator.ts)) -4. Operations (Handled by [operationGenerator.ts](./src/generators/operationGenerator.ts)) -5. Models (Handled by [modelsGenerator.ts](./src/generators/modelsGenerator.ts)) -6. Parameters (Handled by [parametersGenerator.ts](./src/generators/parametersGenerator.ts)) -7. Index File (Handled by [indexGenerator.ts](./src/generators/indexGenerator.ts)) -8. Metadata (Handled [here](./src/generators/static)) - -The entry point for this design is at [main.ts](./src/main.ts) which invokes the [typescriptGenerator.ts](./src/typescriptGenerator.ts) and starts the entire generation process. You could find all the options that could be sent to the generator at [autorestOptions.ts](./src/utils/autorestOptions.ts) - -On a high level, the entire SDK generation process would be: - -Swagger Input -> Autorest Core & Modeler -> CodeModel -> TS/JS SDK Generator -> Generated SDK - -Within the TS/JS SDK Generator, it has the following stages: - -CodeModel + User Options -> Transform CodeModel -> Generate Client -> Generate Client Context -> Generate Operations/Interfaces -> Generate Models -> Generate Parameters -> Generate Index -> Format & Output Generated SDK - -### Steps to clone, build & test - -1. Use the following command to clone the Typescript/Javascript SDK generator repository: - -``` -git clone https://github.com/Azure/autorest.typescript.git -``` - -2. Use the following commands to build the SDK generator: - -``` -npm install -g @autorest/autorest -rush update -rush rebuild -``` - -3. There are 3 test-suites in the generator: - 1. Unit tests (which could be found at `test/unit/*`) - 2. Integration tests (which could be found at `test/integration/*`) - 3. Smoke tests - 4. Version Tolerence Tests -4. You can run the Unit tests & Integration tests using the following command: - -``` -npm run test -``` - -Running the command above will do the following things: - -- Start TestServer -- Build Autorest.Typescript -- Generate all scenarios in parallel (i.e. BodyString, BodyComplex, Url, CustomUrl, Header, XmlService -- Run all the tests under test/integration -- Stop TestServer - -**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server:v2`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) - -5. You can run the Smoke tests using the following command: - -``` -npm run clone:specs -npm run smoke-test -``` - -**_Note_**: If the command `npm run clone:specs` errors out with the following error: - -``` -fatal: destination path './.tmp/specs' already exists and is not an empty directory. -``` - -delete the `.tmp` folder and then try again. - -### Version Tolerence Tests - -Version tolerance tests provide coverage against unexpected **breaking changes** when generating a newer version of a swagger. RLCs are not expected to produce breaking changes unless the swagger itself has an API breaking change. - -Version Tolerance tests would generate 2 clients one from an initial Swagger and a second from the `updated` swagger that contains changes that are not expected to generate breaking changes. The same set of tests is run against both generated clients to make sure no breaking changes resulted. - -Version Tolerance tests have the following npm scripts: - -- `npm run validate-version-tolerance`: generates SDKs and tests for breaking changes between swagger versions -- `generate-version-tolerance`: Generates version tolerance before and after sdks -- `generate-version-tolerance:tests`: generates `updated` spec.ts based on hand written tests against the initial SDK -- `test-version-tolerance`: executes all .spec.ts tests under `test/version-tolerance/` - -In CI we'll run `npm run validate-version-tolerance` which calls all the other npm scripts. The other individual npm scripts are useful for development. - -For more details on the implementation see [#1268](https://github.com/Azure/autorest.typescript/pull/1268) - -### How to add an integration test case -Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output. - -1. Create your test input. Below are some examples - 1. A simple [Swagger/OpenAPI file](./test/integration/swaggers/license-header.json)) - 2. A standalone [configuration markup file](./test/integration/swaggers/bodyComplex.md) (pointing to Swagger file somewhere else) - 3. A combination of configuration markup file and Swagger/OpenAPI file. - -Let us say your test input will be called `testUserCase.json`. - -2. Now add the test input to the integration test suite to the file [`test-swagger-gen.ts`](./test/commands/test-swagger-gen.ts). In the file, add the following to the array `testSwaggers`: - -``` -testUserCase: { - swaggerOrConfig: "test/integration/swaggers/testUserCase.json", - clientName: "TestUserCaseClient", - packageName: "test-user-case", - licenseHeader: true, - useCoreV2: true, - allowInsecureConnection: true, - addCredentials: false -}, -``` - -3. Now, You can generate the SDK only for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) - -``` -npm run generate-swaggers -- -b -i testUserCase -``` - -4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCase.spec.ts` file [here](./test/integration). You can find several examples in the same place. - -### How to debug an integration test case - -#### `generate-swaggers` step - -If you would like to debug the `generate-swaggers` step for our test input, use the following command: - -``` -npm run generate-swaggers -- -b -i testUserCase --debug -``` - -Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. - -#### Spec file - -If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. - -#### How to debug an unit test case - -- In VS Code, We have created a Debugging profile for UnitTests to start debugging: - - 1. Go to the debugger tab - 2. Select the "Unit Test" Profile - 3. Click the "Play" button - -- Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code - -#### Integration Tests - -- In order to debug integration tests you need to start the test server, by running: - - npm run start-test-server:v1 - -- Once the Test Server is running - - 1. In VSCode go to the debugger tab - 2. Select the "IntegrationTests" profile from the drop down - 3. Click the "Play" button - -- **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: - - - Re-generate all the test swaggers - - npm run generate-swaggers -- --build - - - Re-generate a specific swagger - - npm run generate-swaggers -- -i bodyComplex -b - -### Before investing more time investigating - -- Make sure to reset autorest, this will ensure that the versions used by Auotrest Core are the correct ones. This will solve many problems - - autorest --reset +1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. see the [Contributing.md](./packages/autorest.typescript/CONTRUBUTING.md) for this package. +1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. see the [Contributing.md](./packages/rlc-common/CONTRIBUTING.md) for this package. +1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. see the [Contributing.md](./packages/cadl-typescript/CONTRIBUTING.md) for this package. +1. `packages/cadl-rlc-test` is for cadl rlc emitter smoke test. ### Things to keep in mind when contributing @@ -237,7 +58,7 @@ If your test case is working fine as expected, now you are ready to create the P Our generated SDKs take dependency on various packages which you can see in the generated package.json files. These will need to be upgraded from time to time to stay on the latest major version so that we get bug fixes automatically due to semver. -- Update the version of the dependency you are looking for in the methods `restLevelPackage` and/or `regularAutorestPackage` in the [`packageFileGenerator.ts`](https://github.com/Azure/autorest.typescript/blob/main/src/generators/static/packageFileGenerator.ts) file. +- Update the version of the dependency you are looking for in the methods `restLevelPackage` and/or `regularAutorestPackage` in the [`packageFileGenerator.ts`](https://github.com/Azure/autorest.typescript/blob/main/packages/autorest.typescript/src/generators/static/packageFileGenerator.ts) file. - Run `rush rebuild && npm run generate-swaggers && npm run smoke-tests` to update the generated files in the repo and run smoke tests before creating the PR. For example, see the [PR 1271](https://github.com/Azure/autorest.typescript/pull/1271) that updates the version of `prettier` that the generated SDKs depend on. diff --git a/packages/autorest.typescript/CONTRiBUTING.md b/packages/autorest.typescript/CONTRiBUTING.md new file mode 100644 index 0000000000..074990c46b --- /dev/null +++ b/packages/autorest.typescript/CONTRiBUTING.md @@ -0,0 +1,348 @@ +# Introduction + +This package contains the High Level Client generation and the Rest Level Client generation from swagger. We will introduce both on how to contribute to high level client generation and rest level client generation. + +## Typescript/Javascript High Level Client SDK generator Design + +The generated Typescript/Javascript SDK has the following structure: + +1. Client (Handled by [clientFileGenerator.ts](./src/generators/clientFileGenerator.ts)) +1. Operation Interfaces (Handled by [operationInterfaceGenerator.ts](./src/generators/operationInterfaceGenerator.ts)) +1. Operations (Handled by [operationGenerator.ts](./src/generators/operationGenerator.ts)) +1. Models (Handled by [modelsGenerator.ts](./src/generators/modelsGenerator.ts)) +1. Parameters (Handled by [parametersGenerator.ts](./src/generators/parametersGenerator.ts)) +1. Mappers (Handled by [mappersGenerator.ts](./src/generators/mappersGenerator.ts)) +1. Index File (Handled by [indexGenerator.ts](./src/generators/indexGenerator.ts)) +1. Metadata (Handled [here](./src/generators/static)) + +The entry point for this design is at [main.ts](./src/main.ts) which invokes the [typescriptGenerator.ts](./src/typescriptGenerator.ts) and starts the entire generation process. You could find all the options that could be sent to the generator at [autorestOptions.ts](./src/utils/autorestOptions.ts) + +On a high level, the entire SDK generation process would be: + +Swagger Input -> Autorest Core & Modeler -> CodeModel -> TS/JS SDK Generator -> Generated SDK + +Within the TS/JS SDK Generator, it has the following stages: + +CodeModel + User Options -> Transform CodeModel -> Generate Client -> Generate Client Context -> Generate Operations/Interfaces -> Generate Models -> Generate Parameters -> Generate Index -> Format & Output Generated SDK + +### Steps to clone, build & test + +1. Use the following command to clone the Typescript/Javascript SDK generator repository: + +``` +git clone https://github.com/Azure/autorest.typescript.git +``` + +2. Use the following commands to build the SDK generator: + +``` +npm install -g @autorest/autorest +rush update +rush rebuild +``` + +3. There are 3 test-suites in the generator: + 1. Unit tests (which could be found at `test/unit/*`) + 2. Integration tests (which could be found at `test/integration/*`) + 3. Smoke tests + 4. Version Tolerence Tests +4. You can run the Unit tests & Integration tests using the following command: + +``` +npm run test +``` + +Running the command above will do the following things: + +- Start TestServer +- Build Autorest.Typescript +- Generate all scenarios in parallel (i.e. BodyString, BodyComplex, Url, CustomUrl, Header, XmlService +- Run all the tests under test/integration +- Stop TestServer + +**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server:v2`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) + +5. You can run the Smoke tests using the following command: + +``` +npm run clone:specs +npm run smoke-test +``` + +**_Note_**: If the command `npm run clone:specs` errors out with the following error: + +``` +fatal: destination path './.tmp/specs' already exists and is not an empty directory. +``` + +delete the `.tmp` folder and then try again. + +### Version Tolerence Tests + +Version tolerance tests provide coverage against unexpected **breaking changes** when generating a newer version of a swagger. RLCs are not expected to produce breaking changes unless the swagger itself has an API breaking change. + +Version Tolerance tests would generate 2 clients one from an initial Swagger and a second from the `updated` swagger that contains changes that are not expected to generate breaking changes. The same set of tests is run against both generated clients to make sure no breaking changes resulted. + +Version Tolerance tests have the following npm scripts: + +- `npm run validate-version-tolerance`: generates SDKs and tests for breaking changes between swagger versions +- `generate-version-tolerance`: Generates version tolerance before and after sdks +- `generate-version-tolerance:tests`: generates `updated` spec.ts based on hand written tests against the initial SDK +- `test-version-tolerance`: executes all .spec.ts tests under `test/version-tolerance/` + +In CI we'll run `npm run validate-version-tolerance` which calls all the other npm scripts. The other individual npm scripts are useful for development. + +For more details on the implementation see [#1268](https://github.com/Azure/autorest.typescript/pull/1268) + +### How to add an integration test case + +Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output. + +1. Create your test input. Below are some examples + 1. A simple [Swagger/OpenAPI file](./test/integration/swaggers/license-header.json)) + 2. A standalone [configuration markup file](./test/integration/swaggers/bodyComplex.md) (pointing to Swagger file somewhere else) + 3. A combination of configuration markup file and Swagger/OpenAPI file. + +Let us say your test input will be called `testUserCase.json`. + +2. Now add the test input to the integration test suite to the file [`test-swagger-gen.ts`](./test/commands/test-swagger-gen.ts). In the file, add the following to the array `testSwaggers`: + +``` +testUserCase: { + swaggerOrConfig: "test/integration/swaggers/testUserCase.json", + clientName: "TestUserCaseClient", + packageName: "test-user-case", + licenseHeader: true, + useCoreV2: true, + allowInsecureConnection: true, + addCredentials: false +}, +``` + +3. Now, You can generate the SDK only for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) + +``` +npm run generate-swaggers -- -b -i testUserCase +``` + +4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCase.spec.ts` file [here](./test/integration). You can find several examples in the same place. + +### How to debug an integration test case + +#### `generate-swaggers` step + +If you would like to debug the `generate-swaggers` step for our test input, use the following command: + +``` +npm run generate-swaggers -- -b -i testUserCase --debug +``` + +Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. + +#### Spec file + +If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. + +#### How to debug an unit test case + +- In VS Code, We have created a Debugging profile for UnitTests to start debugging: + + 1. Go to the debugger tab + 2. Select the "Unit Test" Profile + 3. Click the "Play" button + +- Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code + +#### Integration Tests + +- In order to debug integration tests you need to start the test server, by running: + + npm run start-test-server:v1 + +- Once the Test Server is running + + 1. In VSCode go to the debugger tab + 2. Select the "IntegrationTests" profile from the drop down + 3. Click the "Play" button + +- **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: + + - Re-generate all the test swaggers + + npm run generate-swaggers -- --build + + - Re-generate a specific swagger + + npm run generate-swaggers -- -i bodyComplex -b + +## Typescript/Javascript Rest Level Client generator Design + +Rest Level Client generation will be trigger when you specify `--rest-level-client=true` in the command line. + +The entry point for this design is at [main.ts](./src/main.ts) which invokes the [generateRestLevel.ts](./src/restLevelClient/generateRestLevel.ts) and starts the entire generation process. You could find all the options that could be sent to the generator at [autorestOptions.ts](./src/utils/autorestOptions.ts) + +On a high level, the entire Rest Level Client generation process would be: + +Swagger Input -> Autorest Core & Modeler -> CodeModel -> Transform RLCModel -> Call RLC Common library to Generate Code + +Within the Transform RLCModel, it has the following stages: + +CodeModel + User Options -> Transform RLCModel Paths -> Transform RLCModel Options -> Transform RLCModel Schemas -> Transform RLCModel Response and Parameter Types -> call RLCCommon libraries to generate the code. + + +### Steps to clone, build & test + +1. Use the following command to clone the Typescript/Javascript SDK generator repository: + +``` +git clone https://github.com/Azure/autorest.typescript.git +``` + +2. Use the following commands to build the SDK generator: + +``` +npm install -g @autorest/autorest +rush update +rush rebuild +``` + +3. There are also 3 test-suites in the RLC generator: + 1. Unit tests (which could be found at `test/unit/restLevelClient/*`) + 2. Integration tests (which could be found at `test/rlcIntegration/*`) + 3. Smoke tests + 4. Version Tolerence Tests +4. You can run the Unit tests & Integration tests using the following command: + +``` +npm run test +``` + +Running the command above will do the following things: + +- Start TestServer +- Build Autorest.Typescript +- Generate all scenarios in parallel (i.e. BodyString, BodyComplex, Url, CustomUrl, Header, XmlService +- Run all the tests under test/integration +- Stop TestServer + +**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server:v2`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) + +5. You can run the Smoke tests using the following command: + +``` +npm run clone:specs +npm run smoke-test +``` + +**_Note_**: If the command `npm run clone:specs` errors out with the following error: + +``` +fatal: destination path './.tmp/specs' already exists and is not an empty directory. +``` + +delete the `.tmp` folder and then try again. + +### Version Tolerence Tests + +Version tolerance tests provide coverage against unexpected **breaking changes** when generating a newer version of a swagger. RLCs are not expected to produce breaking changes unless the swagger itself has an API breaking change. + +Version Tolerance tests would generate 2 clients one from an initial Swagger and a second from the `updated` swagger that contains changes that are not expected to generate breaking changes. The same set of tests is run against both generated clients to make sure no breaking changes resulted. + +Version Tolerance tests have the following npm scripts: + +- `npm run validate-version-tolerance`: generates SDKs and tests for breaking changes between swagger versions +- `generate-version-tolerance`: Generates version tolerance before and after sdks +- `generate-version-tolerance:tests`: generates `updated` spec.ts based on hand written tests against the initial SDK +- `test-version-tolerance`: executes all .spec.ts tests under `test/version-tolerance/` + +In CI we'll run `npm run validate-version-tolerance` which calls all the other npm scripts. The other individual npm scripts are useful for development. + +For more details on the implementation see [#1268](https://github.com/Azure/autorest.typescript/pull/1268) + +### How to add an integration test case + +Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output. + +1. Create your test input. Below are some examples + 1. A simple [Swagger/OpenAPI file](./test/rlcIntegration/swaggers/multipleUrlParameter.json)) + 2. A standalone [configuration markup file](./test/rlcIntegration/swaggers/bodyComplex.md) (pointing to Swagger file somewhere else) + 3. A combination of configuration markup file and Swagger/OpenAPI file. + +Let us say your test input will be called `testUserCase.json`. + +2. Now add the test input to the integration test suite to the file [`test-swagger-gen.ts`](./test/commands/test-swagger-gen.ts). In the file, add the following to the array `rlcTestSwaggers`: + +``` +testUserCase: { + swaggerOrConfig: "test/rlcIntegration/swaggers/testUserCase.json", + clientName: "TestUserCaseClient", + packageName: "test-user-case", + licenseHeader: true, + useCoreV2: true, + allowInsecureConnection: true, + addCredentials: false, + restLevelClient: true +}, +``` + +3. Now, You can generate the SDK only for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) + +``` +npm run rlc-generate-swaggers -- -b -i testUserCase +``` + +4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/rlcIntegration). You can find several examples in the same place. + +### How to debug an integration test case + +#### `rlc-generate-swaggers` step + +If you would like to debug the `rlc-generate-swaggers` step for our test input, use the following command: + +``` +npm run rlc-generate-swaggers -- -b -i testUserCase --debug +``` + +Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. + +#### Spec file + +If you would like to debug the `testUserCaseRest.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCaseRest.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. + +#### How to debug an unit test case + +- In VS Code, We have created a Debugging profile for UnitTests to start debugging: + + 1. Go to the debugger tab + 2. Select the "Unit Test" Profile + 3. Click the "Play" button + +- Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code + +#### Integration Tests + +- In order to debug integration tests you need to start the test server, by running: + + npm run start-test-server:v1 + +- Once the Test Server is running + + 1. In VSCode go to the debugger tab + 2. Select the "IntegrationTests" profile from the drop down + 3. Click the "Play" button + +- **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: + + - Re-generate all the test swaggers + + npm run rlc-generate-swaggers -- --build + + - Re-generate a specific swagger + + npm run rlc-generate-swaggers -- -i bodyComplexRest -b + +### Before investing more time investigating + +- Make sure to reset autorest, this will ensure that the versions used by Auotrest Core are the correct ones. This will solve many problems + + autorest --reset diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md new file mode 100644 index 0000000000..66b6d8e70f --- /dev/null +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -0,0 +1,127 @@ +# Introduction + +This library is the cadl typescript emitter for Rest Level Client. It take cadl as input, transform it into RLCModel, then call rlc-common library to generate the RLC code. + +On a high level, the entire Rest Level Client generation process would be: + +Cadl Input -> Cadl Compiler -> Cadl Program -> Transform RLCModel -> Call RLC Common library to Generate Code + +Within the Transform RLCModel, it has the following stages: + +Cadl Program + User Options -> Transform RLCModel Paths -> Transform RLCModel Options -> Transform RLCModel Schemas -> Transform RLCModel Response and Parameter Types -> call RLCCommon libraries to generate the code. + +### Steps to clone, build & test + +1. Use the following command to clone the Typescript/Javascript SDK generator repository: + +``` +git clone https://github.com/Azure/autorest.typescript.git +``` + +2. Use the following commands to build the SDK generator: + +``` +npm install -g @cadl-lang/compiler +rush update +rush rebuild +``` + +3. There are also 3 test-suites in the RLC generator: + 1. Unit tests (which could be found at `test/unit/*`) + 2. Integration tests (which could be found at `test/integration/*`) + 3. Smoke tests (which could be found at `../../packages/cadl-rlc-test`) +4. You can run the Unit tests & Integration tests using the following command: + +``` +npm run test +``` + +Running the command above will do the following things: + +- Start TestServer +- Build Cadl Typescript +- Generate all scenarios in parallel (i.e. Dictionary, Extensible Enums, Models, Resiliency) +- Run all the tests under test/integration +- Stop TestServer + +**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server:v2`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) + +5. You can run the Smoke tests using the following command: + +``` +cd ../../packages/cadl-rlc-test +npm run smoke-test +``` + +### How to add an integration test case + +Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output. + +1. Pick up a cadl as your test input in cadl-ranch. Below are some examples + +Let us say your test input will be called `testUserCase.json`. + +2. Now add an entry to the CadlRanchConfig to the file [`cadl-ranch-list.ts`](./test/commands/cadl-ranch-list.ts). In the file, add the following to the array. + +``` + { + outputPath: "authentication/apiKey", + inputPath: "authentication/api-key" + }, +``` + +3. Now, You can generate the RLC for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development, you can comment out other test cases. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) + +``` +npm run generate-cadl-only +``` + +4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/integration). You can find several examples in the same place. + +### How to debug an integration test case + +#### `generate-cadl-only` step + +If you would like to debug the `generate-cadl-only` step for our test input, use the following command: + +``` +npm run generate-cadl-only -- -b -i testUserCase --debug +``` + +Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. + +#### Spec file + +If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. + +#### How to debug an unit test case + +- In VS Code, We have created a Debugging profile for UnitTests to start debugging: + + 1. Go to the debugger tab + 2. Select the "Unit Test" Profile + 3. Click the "Play" button + +- Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code + +#### Integration Tests + +- In order to debug integration tests you need to start the test server, by running: + + npm run start-test-server:v1 + +- Once the Test Server is running + + 1. In VSCode go to the debugger tab + 2. Select the "IntegrationTests" profile from the drop down + 3. Click the "Play" button + +- **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: + + - Re-generate all the test swaggers + + npm run generate-cadl-only -- --build + + - Re-generate a specific swagger + + npm run generate-cadl-only -- -i bodyComplexRest -b diff --git a/packages/rlc-common/CONTRIBUTING.md b/packages/rlc-common/CONTRIBUTING.md new file mode 100644 index 0000000000..19f28103f5 --- /dev/null +++ b/packages/rlc-common/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Introduction + +In this library, we abstract the common logic for RLC generation from both swaggers and cadl. + +we have a [interfaces.ts](./src/interfaces.ts) to define the RLCModel And RLCOptions that is export for both Autorest RLC generator and Cadl emitters. + +The generated Typescript/Javascript Rest Level Client has the following structure: + +1. Client (Handled by [buildClient.ts](./src/buildClient.ts)) +1. Client Definition (Handled by [buildClientDefinitions.ts](./src/buildClientDefinitions.ts)) +1. Index File (Handled by [buildIndexFile.ts](./src/buildIndexFile.ts)) +1. isUnexpectedHelper (Handled by [buildIsUnexpectedHelper.ts](./src/buildIsUnexpectedHelper.ts)) pollingHelper (Handled by [buildPollingHelper.ts](./src/buildPollingHelper.ts)) paginateHelper (Handled by [buildPaginateHelper.ts](./src/buildPaginateHelper.ts)) +1. Models (Handled by [buildObjectTypes.ts](./src/buildObjectTypes.ts) and [buildSchemaType.ts](./src/buildSchemaType.ts)) +1. Parameters (Handled by [buildParameterTypes.ts](./src/buildParameterTypes.ts)) +1. Responses (Handled by [buildResponseTypes.ts](./src/buildResponseTypes.ts)) +1. Parameters (Handled by [parametersGenerator.ts](./src/generators/parametersGenerator.ts)) +1. Metadata (Handled [here](./src/metadata/*)) + +If there's a new feature request, Contributors can add properties in RLCModel and RLCOptions and then add the build logic like other files to generate the type. + +We don't have any tests in this library, as this library is replied by both autorest.typescript and cadl-typescript, we think add test in these two libraries if we want to test something. \ No newline at end of file From 3c871328d02703fa9cd1fc650a0e4f3f37748c8a Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 21 Oct 2022 15:07:56 +0800 Subject: [PATCH 03/13] update to resolve some comments --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ec74206ac..e46c2148a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,9 +39,9 @@ Inside this project, we support both high level client generation and rest level This project is managed by rush, there're four components inside the `./packages` folder. -1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. see the [Contributing.md](./packages/autorest.typescript/CONTRUBUTING.md) for this package. -1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. see the [Contributing.md](./packages/rlc-common/CONTRIBUTING.md) for this package. -1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. see the [Contributing.md](./packages/cadl-typescript/CONTRIBUTING.md) for this package. +1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. see the [CONTRIBUTING.md](./packages/autorest.typescript/CONTRIBUTING.md) for this package. +1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. see the [CONTRIBUTING.md](./packages/rlc-common/CONTRIBUTING.md) for this package. +1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. see the [CONTRIBUTING.md](./packages/cadl-typescript/CONTRIBUTING.md) for this package. 1. `packages/cadl-rlc-test` is for cadl rlc emitter smoke test. ### Things to keep in mind when contributing From f064066c7e02aab978ad4ccb5df7345b09d0fb1c Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 21 Oct 2022 15:24:43 +0800 Subject: [PATCH 04/13] rename file --- packages/autorest.typescript/{CONTRiBUTING.md => CONTRIBUTING.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/autorest.typescript/{CONTRiBUTING.md => CONTRIBUTING.md} (100%) diff --git a/packages/autorest.typescript/CONTRiBUTING.md b/packages/autorest.typescript/CONTRIBUTING.md similarity index 100% rename from packages/autorest.typescript/CONTRiBUTING.md rename to packages/autorest.typescript/CONTRIBUTING.md From 003734d56011fc6331246c23df36a9fbbd92e410 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 21 Oct 2022 15:32:07 +0800 Subject: [PATCH 05/13] update resolve comments --- .vscode/launch.json | 18 ++++++++++++++++++ packages/autorest.typescript/CONTRIBUTING.md | 4 ++-- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 5302f7ef32..09c5c20391 100755 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -27,6 +27,24 @@ "${workspaceFolder}/packages/*/dist-dev/**/*.js" ] }, + { + "type": "node", + "request": "launch", + "name": "[autorest.typescript]-IntegrationTests", + "cwd": "${workspaceFolder}/packages/autorest.typescript", + "program": "./node_modules/mocha/bin/_mocha", + "args": [ + "-r", + "ts-node/register", + "--timeout", + "999999", + "--colors", + "./test/integration/**/*.spec.ts" + ], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "protocol": "inspector" + }, { "name": "Generate code for CadlRlcTest", "request": "launch", diff --git a/packages/autorest.typescript/CONTRIBUTING.md b/packages/autorest.typescript/CONTRIBUTING.md index 074990c46b..bd09afce76 100644 --- a/packages/autorest.typescript/CONTRIBUTING.md +++ b/packages/autorest.typescript/CONTRIBUTING.md @@ -141,7 +141,7 @@ Now, the code will wait for the debugger to be attached. Open the repository in #### Spec file -If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. +If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `[autorest.typescript]-IntegrationTests`. #### How to debug an unit test case @@ -162,7 +162,7 @@ If you would like to debug the `testUserCase.spec.ts` file (after the SDK is gen - Once the Test Server is running 1. In VSCode go to the debugger tab - 2. Select the "IntegrationTests" profile from the drop down + 2. Select the "[autorest.typescript]-IntegrationTests" profile from the drop down 3. Click the "Play" button - **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: From 509635b6d33fb6195c6a1aaf69b53ca05119ee32 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 21 Oct 2022 15:37:01 +0800 Subject: [PATCH 06/13] update to resolve comments --- .vscode/launch.json | 36 ++++++++++++++++++++ packages/autorest.typescript/CONTRIBUTING.md | 4 +-- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 09c5c20391..8e495910f9 100755 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -27,6 +27,24 @@ "${workspaceFolder}/packages/*/dist-dev/**/*.js" ] }, + { + "type": "node", + "request": "launch", + "name": "[autorest.typescript]-UnitTests", + "cwd": "${workspaceFolder}/packages/autorest.typescript", + "program": "./node_modules/mocha/bin/_mocha", + "args": [ + "-r", + "ts-node/register", + "--timeout", + "999999", + "--colors", + "./test/unit/**/*.spec.ts" + ], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "protocol": "inspector" + }, { "type": "node", "request": "launch", @@ -45,6 +63,24 @@ "internalConsoleOptions": "neverOpen", "protocol": "inspector" }, + { + "type": "node", + "request": "launch", + "name": "[autorest.typescript]-IntegrationTests - Current File", + "cwd": "${workspaceFolder}/packages/autorest.typescript", + "program": "./node_modules/mocha/bin/_mocha", + "args": [ + "-r", + "ts-node/register", + "--timeout", + "999999", + "--colors", + "${workspaceFolder}/${relativeFile}" + ], + "console": "integratedTerminal", + "internalConsoleOptions": "neverOpen", + "protocol": "inspector" + }, { "name": "Generate code for CadlRlcTest", "request": "launch", diff --git a/packages/autorest.typescript/CONTRIBUTING.md b/packages/autorest.typescript/CONTRIBUTING.md index bd09afce76..0db5d750f1 100644 --- a/packages/autorest.typescript/CONTRIBUTING.md +++ b/packages/autorest.typescript/CONTRIBUTING.md @@ -141,14 +141,14 @@ Now, the code will wait for the debugger to be attached. Open the repository in #### Spec file -If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `[autorest.typescript]-IntegrationTests`. +If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `[autorest.typescript]-IntegrationTests - Current File`. #### How to debug an unit test case - In VS Code, We have created a Debugging profile for UnitTests to start debugging: 1. Go to the debugger tab - 2. Select the "Unit Test" Profile + 2. Select the "[autorest.typescript]-UnitTests" Profile 3. Click the "Play" button - Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code From 8a97ab926163e140f726a341cdeab29c934a8a2d Mon Sep 17 00:00:00 2001 From: Qiaoqiao Zhang <55688292+qiaozha@users.noreply.github.com> Date: Mon, 24 Oct 2022 09:05:14 +0800 Subject: [PATCH 07/13] Update packages/rlc-common/CONTRIBUTING.md Co-authored-by: Renhe Li --- packages/rlc-common/CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rlc-common/CONTRIBUTING.md b/packages/rlc-common/CONTRIBUTING.md index 19f28103f5..9f081f62f0 100644 --- a/packages/rlc-common/CONTRIBUTING.md +++ b/packages/rlc-common/CONTRIBUTING.md @@ -18,4 +18,4 @@ The generated Typescript/Javascript Rest Level Client has the following structur If there's a new feature request, Contributors can add properties in RLCModel and RLCOptions and then add the build logic like other files to generate the type. -We don't have any tests in this library, as this library is replied by both autorest.typescript and cadl-typescript, we think add test in these two libraries if we want to test something. \ No newline at end of file +We don't have tests in this library as it is invoked by autorest.typescript and cadl-typescript, adding tests in those two libraries directly if you want to test a feature. \ No newline at end of file From 3c2cadcd7f6b128e9039225c508e774febd27f3a Mon Sep 17 00:00:00 2001 From: qiaozha Date: Thu, 27 Oct 2022 17:02:24 +0800 Subject: [PATCH 08/13] update docs organization --- CONTRIBUTING.md | 22 +++++++------ README.md | 30 ++++++++++++++++++ .../docs}/client/initializing.md | 4 +-- .../docs}/client/models.md | 0 .../docs}/client/operations.md | 0 .../docs}/client/readme.md | 2 +- .../docs}/client/tracing.md | 2 +- .../docs}/client/troubleshooting.md | 2 +- .../autorest.typescript/docs}/faq.md | 2 +- .../autorest.typescript/docs}/images/logo.png | Bin .../docs}/migrate/readme.md | 0 .../autorest.typescript/docs}/overview.md | 13 ++------ .../autorest.typescript/docs}/readme.md | 10 +++--- .../docs}/samples/readme.md | 0 .../samples/specification/basic/readme.md | 0 .../specification/management/readme.md | 2 +- .../docs}/troubleshooting.md | 6 ++-- 17 files changed, 60 insertions(+), 35 deletions(-) create mode 100644 README.md rename {docs => packages/autorest.typescript/docs}/client/initializing.md (94%) rename {docs => packages/autorest.typescript/docs}/client/models.md (100%) rename {docs => packages/autorest.typescript/docs}/client/operations.md (100%) rename {docs => packages/autorest.typescript/docs}/client/readme.md (87%) rename {docs => packages/autorest.typescript/docs}/client/tracing.md (97%) rename {docs => packages/autorest.typescript/docs}/client/troubleshooting.md (97%) rename {docs => packages/autorest.typescript/docs}/faq.md (90%) rename {docs => packages/autorest.typescript/docs}/images/logo.png (100%) rename {docs => packages/autorest.typescript/docs}/migrate/readme.md (100%) rename {docs => packages/autorest.typescript/docs}/overview.md (97%) rename {docs => packages/autorest.typescript/docs}/readme.md (70%) rename {docs => packages/autorest.typescript/docs}/samples/readme.md (100%) rename {docs => packages/autorest.typescript/docs}/samples/specification/basic/readme.md (100%) rename {docs => packages/autorest.typescript/docs}/samples/specification/management/readme.md (82%) rename {docs => packages/autorest.typescript/docs}/troubleshooting.md (85%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e46c2148a0..c48e0fc215 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,16 +33,18 @@ If your contribution is significantly big it is better to first check with the p Want to get started hacking on the code? Great! Keep reading. This contributing guide helps you to start working with and contributing to the Azure Typescript/Javascript SDK Generator. -### General Introduction - -Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we only support generation from rest api specs, the support of generate high level client from cadl is planning. - -This project is managed by rush, there're four components inside the `./packages` folder. - -1. `packages/autorest.typescript` contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. see the [CONTRIBUTING.md](./packages/autorest.typescript/CONTRIBUTING.md) for this package. -1. `packages/rlc-common` contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `package/autorest.typescript` rlc generation part and `packages/cadl-typescript`. see the [CONTRIBUTING.md](./packages/rlc-common/CONTRIBUTING.md) for this package. -1. `packages/cadl-typescript` is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. see the [CONTRIBUTING.md](./packages/cadl-typescript/CONTRIBUTING.md) for this package. -1. `packages/cadl-rlc-test` is for cadl rlc emitter smoke test. +## Prerequisites + +In order contribute to this project, You will need to install some prerequisite dependencies to get start. + +- Git +- Any of the [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule) +- Rush 5.x + - Install / update Rush globally via `npm install -g @microsoft/rush`. + - Rush will automatically manage the specific version needed by this repo as long as you have any v5 version installed. + - If you're unable to install a global tool, you can instead call the wrapper script `node /common/scripts/install-run-rush.js` any time the guide instructs you to run `rush`. The wrapper script will install a managed copy of Rush in a temporary directory for you. +- [Autorest](https://www.npmjs.com/package/autorest), if you're planning contribute to the generator code from swagger either for high level client or for rest level client. +- [Cadl Compiler](https://www.npmjs.com/package/@cadl-lang/compiler), if you're planning contribute to the generator code from cadl. ### Things to keep in mind when contributing diff --git a/README.md b/README.md new file mode 100644 index 0000000000..37235f9c30 --- /dev/null +++ b/README.md @@ -0,0 +1,30 @@ +# Azure TypeScript SDK and RLC Code Generator Libraries + +This repository is the code generator libraries for Azure TypeScript SDK and Azure TypeScript Rest Level Client libraries. + +## Packages + +| Name | Changelog | Latest | Next | +| --------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| [@autorest/typescript][autorest_typescript_src] | [Changelog][autorest_typescript_chg] | [![](https://img.shields.io/npm/v/@autorest/typescript)](https://www.npmjs.com/package/@autorest/typescript) | ![](https://img.shields.io/npm/v/@autorest/typescript/next) | +| [@azure-tools/cadl-typescript][cadl-typescript_src] | [Changelog][cadl-typescript_chg] | [![](https://img.shields.io/npm/v/@azure-tools/cadl-typescript)](https://www.npmjs.com/package/@azure-tools/cadl-typescript) | ![](https://img.shields.io/npm/@azure-tools/cadl-azure-core/next) | +| [@azure-tools/rlc-common][rlc-common_src] | [Changelog][rlc-common_chg] | [![](https://img.shields.io/npm/v/@azure-tools/rlc-common)](https://www.npmjs.com/package/@azure-tools/rlc-common) | ![](https://img.shields.io/npm/@azure-tools/rlc-common/next) | + + +[autorest_typescript_src]: packages/autorest.typescript/ +[autorest_typescript_chg]: packages/autorest.typescript/CHANGELOG.md +[cadl-typescript_src]: packages/cadl-typescript +[cadl-typescript_chg]: packages/cadl-typescript/CHANGELOG.md +[rlc-common_src]: packages/rlc-common +[rlc-common_chg]: packages/rlc-common/CHANGELOG.md + + +`@next` version of the package are the latest versions available on the `main` branch. + +### General Introduction + +Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we only support generation from rest api specs, the support of generate high level client from cadl is planning. + +- [**@autorest/typescript:**](https://github.com/Azure/autorest.typescript/tree/main/packages/autorest.typescript) contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. +- [**@azure-tools/cadl-typescript:**](https://github.com/Azure/autorest.typescript/tree/main/packages/cadl-typescript) is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. +- [**@azure-tools/rlc-common:**](https://github.com/Azure/autorest.typescript/tree/main/packages/rlc-common) contains the common generation logic from RLC model into rest client libraries code part. Which is depended by both `@autorest/typescript` rlc generation part and `@azure-tools/cadl-typescript`. diff --git a/docs/client/initializing.md b/packages/autorest.typescript/docs/client/initializing.md similarity index 94% rename from docs/client/initializing.md rename to packages/autorest.typescript/docs/client/initializing.md index b51481627c..771ecab678 100644 --- a/docs/client/initializing.md +++ b/packages/autorest.typescript/docs/client/initializing.md @@ -40,8 +40,8 @@ const client: PetsClient = new PetsClient(new DefaultAzureCredential()); [azure_identity_library]: https://www.npmjs.com/package/@azure/identity -[flag_index]: https://github.com/Azure/autorest/tree/master/docs/generate/flags.md +[flag_index]: https://github.com/Azure/autorest/tree/main/docs/generate/flags.md [aad_authentication]: https://docs.microsoft.com/en-us/azure/cognitive-services/authentication?tabs=powershell#authenticate-with-azure-active-directory -[identity_credentials]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity#credential-classes +[identity_credentials]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity#credential-classes [default_azure_credential]: https://docs.microsoft.com/en-us/javascript/api/@azure/identity/defaultazurecredential?view=azure-node-latest [azure_key_credential]: https://docs.microsoft.com/en-us/python/api/azure-core/azure.core.credentials.azurekeycredential?view=azure-python diff --git a/docs/client/models.md b/packages/autorest.typescript/docs/client/models.md similarity index 100% rename from docs/client/models.md rename to packages/autorest.typescript/docs/client/models.md diff --git a/docs/client/operations.md b/packages/autorest.typescript/docs/client/operations.md similarity index 100% rename from docs/client/operations.md rename to packages/autorest.typescript/docs/client/operations.md diff --git a/docs/client/readme.md b/packages/autorest.typescript/docs/client/readme.md similarity index 87% rename from docs/client/readme.md rename to packages/autorest.typescript/docs/client/readme.md index 662af18b34..390b1b876a 100644 --- a/docs/client/readme.md +++ b/packages/autorest.typescript/docs/client/readme.md @@ -9,7 +9,7 @@ After [generating][generate] your client, this section tells you how to actually * [Tracing][tracing] -[generate]: https://github.com/Azure/autorest/tree/master/docs/generate/readme.md +[generate]: https://github.com/Azure/autorest/tree/main/docs/generate/readme.md [initializing]: ./initializing.md [operations]: ./operations.md [models]: ./models.md diff --git a/docs/client/tracing.md b/packages/autorest.typescript/docs/client/tracing.md similarity index 97% rename from docs/client/tracing.md rename to packages/autorest.typescript/docs/client/tracing.md index e4e0af4ad4..1b2662c828 100644 --- a/docs/client/tracing.md +++ b/packages/autorest.typescript/docs/client/tracing.md @@ -77,7 +77,7 @@ exporter.shutdown(); [open_census]: https://opencensus.io/ [open_telemetry]: https://opentelemetry.io/ -[flag_index]: https://github.com/Azure/autorest/tree/master/docs/generate/flags.md +[flag_index]: https://github.com/Azure/autorest/tree/main/docs/generate/flags.md [tracing_library]: https://www.npmjs.com/package/@azure/core-tracing [azure_monitor]: https://pypi.org/project/opentelemetry-azure-monitor/ [zipkin]: https://zipkin.io/ diff --git a/docs/client/troubleshooting.md b/packages/autorest.typescript/docs/client/troubleshooting.md similarity index 97% rename from docs/client/troubleshooting.md rename to packages/autorest.typescript/docs/client/troubleshooting.md index 46176f6606..0c5204d498 100644 --- a/docs/client/troubleshooting.md +++ b/packages/autorest.typescript/docs/client/troubleshooting.md @@ -29,4 +29,4 @@ export AZURE_LOG_LEVEL=info For more detailed instructions on how to enable logs, you can look at the [@azure/logger package docs][logger-docs] -[logger_docs]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/core/logger \ No newline at end of file +[logger_docs]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/logger \ No newline at end of file diff --git a/docs/faq.md b/packages/autorest.typescript/docs/faq.md similarity index 90% rename from docs/faq.md rename to packages/autorest.typescript/docs/faq.md index 0d71ccd1b7..65e425ab63 100644 --- a/docs/faq.md +++ b/packages/autorest.typescript/docs/faq.md @@ -13,4 +13,4 @@ -[autorest_npm]: https://www.npmjs.com/package/@autorest/python \ No newline at end of file +[autorest_npm]: https://www.npmjs.com/package/@autorest/typescript \ No newline at end of file diff --git a/docs/images/logo.png b/packages/autorest.typescript/docs/images/logo.png similarity index 100% rename from docs/images/logo.png rename to packages/autorest.typescript/docs/images/logo.png diff --git a/docs/migrate/readme.md b/packages/autorest.typescript/docs/migrate/readme.md similarity index 100% rename from docs/migrate/readme.md rename to packages/autorest.typescript/docs/migrate/readme.md diff --git a/docs/overview.md b/packages/autorest.typescript/docs/overview.md similarity index 97% rename from docs/overview.md rename to packages/autorest.typescript/docs/overview.md index 0b7d8be359..1273fd32b0 100644 --- a/docs/overview.md +++ b/packages/autorest.typescript/docs/overview.md @@ -30,7 +30,7 @@ - Autorest is an OpenAPI (Swagger) specification code generator. - The new version of autorest (v3) supports [OpenApi v3](https://github.com/OAI/OpenAPI-Specification). -- Autorest v3 uses[ @azure/modelerfour](https://github.com/Azure/autorest.modelerfour) to parse the OpenAPI (Swagger) document and generates a language agnostic code model. +- Autorest v3 uses[ @autorest/modelerfour](https://github.com/Azure/autorest/tree/main/packages/extensions/modelerfour) to parse the OpenAPI (Swagger) document and generates a language agnostic code model. - Autorest supports plugins, these plugins are responsible for Language specific code generation. - Autorest communicates with the plugins through stdin/stdout using JsonRPC. - Autorest core is written in Typescript, however the plugins can be written in any language. @@ -77,7 +77,6 @@ ├── rollup.config.js ├── src │ ├── bodyComplexClient.ts - │ ├── bodyComplexClientContext.ts │ ├── index.ts │ ├── models │ │ ├── index.ts @@ -137,17 +136,11 @@ Project structure - tsconfig - api-extractor.json -2. clientContextFileGenerator.ts - - - This generator is responsible for generating the clientContext file for a library - - In the generated class all the Client level parameters are set as properties on this class - - The generated class extends `coreHttp.Service` client - -3. clientFileGenerator.cs +2. clientFileGenerator.cs - This generator is responsible for generating the ClientClass file for a library - The generated class is the main entry point of the library, whcih is instantiated by consumers to access the operations - - The generated class extends the generated ClientContext class + - The generated class extends the generated Client class - The generated class has each operation group as property, form which consumers can access each operation - There are also operations that don't belong to any operation group and belong to the clientFileGenerator diff --git a/docs/readme.md b/packages/autorest.typescript/docs/readme.md similarity index 70% rename from docs/readme.md rename to packages/autorest.typescript/docs/readme.md index 7cc5461466..c520d164d4 100644 --- a/docs/readme.md +++ b/packages/autorest.typescript/docs/readme.md @@ -28,15 +28,15 @@ These documents are Typescript-specific, see [our main docs][main_docs] for more -[main_docs]: https://github.com/Azure/autorest/tree/main/docs -[main_generate]: https://github.com/Azure/autorest/tree/main/docs/generate/readme.md +[main_docs]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs +[main_generate]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs/generate/readme.md [typescript_generate]: ./overview.md [typescript_client]: ./client/readme.md -[main_client]: https://github.com/Azure/autorest/tree/main/docs/client/readme.md -[main_migrate]: https://github.com/Azure/autorest/tree/main/docs/migrate/readme.md +[main_client]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs/client/readme.md +[main_migrate]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs/migrate/readme.md [typescript_migrate]: ./migrate/readme.md [typescript_dev]: https://github.com/Azure/autorest.typescript/blob/main/CONTRIBUTING.md -[main_dev]: https://github.com/Azure/autorest/tree/main/docs/developer/readme.md +[main_dev]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs/developer/readme.md [sample]: ./samples/readme.md [faq]: ./faq.md [troubleshooting]: ./troubleshooting.md diff --git a/docs/samples/readme.md b/packages/autorest.typescript/docs/samples/readme.md similarity index 100% rename from docs/samples/readme.md rename to packages/autorest.typescript/docs/samples/readme.md diff --git a/docs/samples/specification/basic/readme.md b/packages/autorest.typescript/docs/samples/specification/basic/readme.md similarity index 100% rename from docs/samples/specification/basic/readme.md rename to packages/autorest.typescript/docs/samples/specification/basic/readme.md diff --git a/docs/samples/specification/management/readme.md b/packages/autorest.typescript/docs/samples/specification/management/readme.md similarity index 82% rename from docs/samples/specification/management/readme.md rename to packages/autorest.typescript/docs/samples/specification/management/readme.md index 19919829ad..2b28961f87 100644 --- a/docs/samples/specification/management/readme.md +++ b/packages/autorest.typescript/docs/samples/specification/management/readme.md @@ -13,4 +13,4 @@ azure-arm: true [mgmt]: https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/control-plane-and-data-plane#control-plane -[flag_index]: https://github.com/Azure/autorest/tree/master/docs/generate/flags.md \ No newline at end of file +[flag_index]: https://github.com/Azure/autorest/tree/main/packages/autorest.typescript/docs/generate/flags.md \ No newline at end of file diff --git a/docs/troubleshooting.md b/packages/autorest.typescript/docs/troubleshooting.md similarity index 85% rename from docs/troubleshooting.md rename to packages/autorest.typescript/docs/troubleshooting.md index 11c48859ad..8a3689eee2 100644 --- a/docs/troubleshooting.md +++ b/packages/autorest.typescript/docs/troubleshooting.md @@ -31,8 +31,8 @@ Our [main docs][main_debugging] show you how to pass in flags (`--verbose` / `-- If you'd like to actually debug through our code, you need to first clone the `v6` branch of our [repo][repo], then include flag `--typescript.debugger` on our command line. You should now be able to step through the Typescript generator's code base. -[main_docs]: https://github.com/Azure/autorest/blob/main/docs/troubleshooting.md +[main_docs]: https://github.com/Azure/autorest/blob/main/packages/autorest.typescript/docs/troubleshooting.md [autorest_issues]: https://github.com/Azure/autorest/issues [autorest_typescript_issues]: https://github.com/Azure/autorest.typescript/issues -[main_debugging]: https://github.com/Azure/autorest/blob/main/docs/troubleshooting.md#debugging -[repo]: https://github.com/Azure/autorest.typescript/tree/v6 +[main_debugging]: https://github.com/Azure/autorest/blob/main/packages/autorest.typescript/docs/troubleshooting.md#debugging +[repo]: https://github.com/Azure/autorest.typescript/ From bcc4dff49ef3caee59cb9edff1cf5991c552ccc6 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Fri, 28 Oct 2022 10:35:45 +0800 Subject: [PATCH 09/13] update contributing guide --- README.md | 2 +- packages/autorest.typescript/CONTRIBUTING.md | 8 ++++-- packages/cadl-typescript/CONTRIBUTING.md | 30 ++++++++------------ packages/cadl-typescript/README.md | 11 +++++++ packages/rlc-common/CONTRIBUTING.md | 18 ++++++++---- packages/rlc-common/README.md | 3 ++ 6 files changed, 46 insertions(+), 26 deletions(-) create mode 100644 packages/cadl-typescript/README.md create mode 100644 packages/rlc-common/README.md diff --git a/README.md b/README.md index 37235f9c30..617e4fd7e5 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ This repository is the code generator libraries for Azure TypeScript SDK and Azu ### General Introduction -Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we only support generation from rest api specs, the support of generate high level client from cadl is planning. +Inside this project, we support both high level client generation and rest level client generation. In the rest level client generation, we support generate code from both rest api specs and cadl. In the high level client generation, we only support generation from rest api specs. - [**@autorest/typescript:**](https://github.com/Azure/autorest.typescript/tree/main/packages/autorest.typescript) contains the original high level client generation and the rest level client generation, mostly including the transformation from autorest code model into RLC model part. - [**@azure-tools/cadl-typescript:**](https://github.com/Azure/autorest.typescript/tree/main/packages/cadl-typescript) is the typescript cadl emitter, which contains the transformation from cadl model into RLC model. diff --git a/packages/autorest.typescript/CONTRIBUTING.md b/packages/autorest.typescript/CONTRIBUTING.md index 0db5d750f1..464f854b5d 100644 --- a/packages/autorest.typescript/CONTRIBUTING.md +++ b/packages/autorest.typescript/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Introduction +# Contributing This package contains the High Level Client generation and the Rest Level Client generation from swagger. We will introduce both on how to contribute to high level client generation and rest level client generation. @@ -23,7 +23,11 @@ Swagger Input -> Autorest Core & Modeler -> CodeModel -> TS/JS SDK Generator -> Within the TS/JS SDK Generator, it has the following stages: -CodeModel + User Options -> Transform CodeModel -> Generate Client -> Generate Client Context -> Generate Operations/Interfaces -> Generate Models -> Generate Parameters -> Generate Index -> Format & Output Generated SDK +CodeModel + User Options -> Transform CodeModel -> Generate Client -> Generate Client Context -> Generate Operations/Interfaces -> Generate Models -> Generate Parameters -> Generate Index -> Format & Output Generated SDK + +### Prerequisite + +Please follow the **[Prerequisite](../../CONTRIBUTING.md#prerequisites)** part to install the dependencies. ### Steps to clone, build & test diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md index 66b6d8e70f..99a6ab56bf 100644 --- a/packages/cadl-typescript/CONTRIBUTING.md +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -1,16 +1,10 @@ -# Introduction +# How to Contribute -This library is the cadl typescript emitter for Rest Level Client. It take cadl as input, transform it into RLCModel, then call rlc-common library to generate the RLC code. +## Prerequisite -On a high level, the entire Rest Level Client generation process would be: +Please follow the **[Prerequisite](../../CONTRIBUTING.md#prerequisites)** part to install the dependencies. -Cadl Input -> Cadl Compiler -> Cadl Program -> Transform RLCModel -> Call RLC Common library to Generate Code - -Within the Transform RLCModel, it has the following stages: - -Cadl Program + User Options -> Transform RLCModel Paths -> Transform RLCModel Options -> Transform RLCModel Schemas -> Transform RLCModel Response and Parameter Types -> call RLCCommon libraries to generate the code. - -### Steps to clone, build & test +## Steps to clone, build & test 1. Use the following command to clone the Typescript/Javascript SDK generator repository: @@ -21,7 +15,6 @@ git clone https://github.com/Azure/autorest.typescript.git 2. Use the following commands to build the SDK generator: ``` -npm install -g @cadl-lang/compiler rush update rush rebuild ``` @@ -30,7 +23,8 @@ rush rebuild 1. Unit tests (which could be found at `test/unit/*`) 2. Integration tests (which could be found at `test/integration/*`) 3. Smoke tests (which could be found at `../../packages/cadl-rlc-test`) -4. You can run the Unit tests & Integration tests using the following command: + +1. You can run the Unit tests & Integration tests using the following command: ``` npm run test @@ -53,7 +47,7 @@ cd ../../packages/cadl-rlc-test npm run smoke-test ``` -### How to add an integration test case +## How to add an integration test case Whenever you work on adding a feature/fixing a bug, this would probably be your first step. You create a test case and then run it through the generator, see the result, modify the generator, run it again and so on, until you get the desired output. @@ -78,9 +72,9 @@ npm run generate-cadl-only 4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/integration). You can find several examples in the same place. -### How to debug an integration test case +## How to debug -#### `generate-cadl-only` step +### `generate-cadl-only` step If you would like to debug the `generate-cadl-only` step for our test input, use the following command: @@ -90,11 +84,11 @@ npm run generate-cadl-only -- -b -i testUserCase --debug Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. -#### Spec file +### Spec file If you would like to debug the `testUserCase.spec.ts` file (after the SDK is generated), Open the repository in VS Code -> Open the `testUserCase.spec.ts` file -> Select `Run and Debug` section -> Click `IntegrationTests - Current File`. -#### How to debug an unit test case +### How to debug an unit test case - In VS Code, We have created a Debugging profile for UnitTests to start debugging: @@ -104,7 +98,7 @@ If you would like to debug the `testUserCase.spec.ts` file (after the SDK is gen - Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code -#### Integration Tests +### Integration Tests - In order to debug integration tests you need to start the test server, by running: diff --git a/packages/cadl-typescript/README.md b/packages/cadl-typescript/README.md new file mode 100644 index 0000000000..90e6354a47 --- /dev/null +++ b/packages/cadl-typescript/README.md @@ -0,0 +1,11 @@ +# Introduction + +This library is the cadl typescript emitter for Rest Level Client. It take [cadl](https://github.com/microsoft/cadl) as input, transform it into RLCModel, then call rlc-common library to generate the RLC code. + +On a high level, the entire Rest Level Client generation process would be: + +Cadl Input -> Cadl Compiler -> Cadl Program -> Transform RLCModel -> Call RLC Common library to Generate Code + +Within the Transform RLCModel, it has the following stages: + +Cadl Program + User Options -> Transform RLCModel Paths -> Transform RLCModel Options -> Transform RLCModel Schemas -> Transform RLCModel Response and Parameter Types -> call RLCCommon libraries to generate the code. diff --git a/packages/rlc-common/CONTRIBUTING.md b/packages/rlc-common/CONTRIBUTING.md index 9f081f62f0..e49bf8e171 100644 --- a/packages/rlc-common/CONTRIBUTING.md +++ b/packages/rlc-common/CONTRIBUTING.md @@ -1,6 +1,4 @@ -# Introduction - -In this library, we abstract the common logic for RLC generation from both swaggers and cadl. +# Contributing we have a [interfaces.ts](./src/interfaces.ts) to define the RLCModel And RLCOptions that is export for both Autorest RLC generator and Cadl emitters. @@ -15,7 +13,17 @@ The generated Typescript/Javascript Rest Level Client has the following structur 1. Responses (Handled by [buildResponseTypes.ts](./src/buildResponseTypes.ts)) 1. Parameters (Handled by [parametersGenerator.ts](./src/generators/parametersGenerator.ts)) 1. Metadata (Handled [here](./src/metadata/*)) +## Prerequisite + +Please follow the **[Prerequisite](../../CONTRIBUTING.md#prerequisites)** part to install the dependencies. + +## Add a new feature + +If there's a new feature request, Contributors can + +1. add properties in RLCModel and RLCOptions in [interfaces.ts](./src/interfaces.ts) +1. add the build logic about how the newly add properties is going to change the generation behavior. -If there's a new feature request, Contributors can add properties in RLCModel and RLCOptions and then add the build logic like other files to generate the type. +## Testing -We don't have tests in this library as it is invoked by autorest.typescript and cadl-typescript, adding tests in those two libraries directly if you want to test a feature. \ No newline at end of file +We don't have tests in this library as it is invoked by autorest.typescript and cadl-typescript, adding tests in those two libraries directly if you want to test a feature. diff --git a/packages/rlc-common/README.md b/packages/rlc-common/README.md new file mode 100644 index 0000000000..4089f33033 --- /dev/null +++ b/packages/rlc-common/README.md @@ -0,0 +1,3 @@ +# Introduction + +In this library, we abstract the common generation logic for RLC generation from both swaggers and cadl. In this way, the autorest.typescript part will only need to transform the code model into RLCModel, and the cadl emitter will only need to transform the cadl program into RLCModel, then the rlc-common library will take the rest generation part to build the file content of from the RLCModel. From 3895033fd190a73b829cd067bec6acd679f8247e Mon Sep 17 00:00:00 2001 From: qiaozha Date: Tue, 1 Nov 2022 11:18:34 +0800 Subject: [PATCH 10/13] update to resolve comments --- .vscode/launch.json | 22 +++++++++++++++++++++- packages/cadl-typescript/CONTRIBUTING.md | 12 +++--------- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/.vscode/launch.json b/.vscode/launch.json index 8e495910f9..ebc717bbf9 100755 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -102,7 +102,27 @@ "outFiles": ["${workspaceFolder}/packages/*/dist/**/*.js"] }, { - "name": "Cadl Unit or Integration Test", + "name": "[CADL] - Unit Test", + "request": "launch", + "cwd": "${workspaceFolder}/packages/cadl-typescript", + "runtimeArgs": [ + "mocha", + "-r", + "ts-node/register", + "--experimental-specifier-resolution=node", + "--experimental-modules=true", + "--timeout", + "999999", + "--colors", + "./test/unit/**/*.spec.ts" + ], + "runtimeExecutable": "npx", + "skipFiles": ["/**"], + "type": "pwa-node", + "outFiles": ["${workspaceFolder}/packages/*/dist/**/*.js"] + }, + { + "name": "[CADL] - Integration Test", "request": "launch", "cwd": "${workspaceFolder}/packages/cadl-typescript", "runtimeArgs": [ diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md index 99a6ab56bf..50ee6f0578 100644 --- a/packages/cadl-typescript/CONTRIBUTING.md +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -76,13 +76,7 @@ npm run generate-cadl-only ### `generate-cadl-only` step -If you would like to debug the `generate-cadl-only` step for our test input, use the following command: - -``` -npm run generate-cadl-only -- -b -i testUserCase --debug -``` - -Now, the code will wait for the debugger to be attached. Open the repository in VS Code -> Select `Run and Debug` section -> Click `Attach`. +If you would like to debug the `generate-cadl-only` step for our test input, Open the repository in VS Code -> Select `Generate code for CadlEmitter` section -> Click `Attach`. ### Spec file @@ -93,7 +87,7 @@ If you would like to debug the `testUserCase.spec.ts` file (after the SDK is gen - In VS Code, We have created a Debugging profile for UnitTests to start debugging: 1. Go to the debugger tab - 2. Select the "Unit Test" Profile + 2. Select the "[CADL] - Unit Test" Profile 3. Click the "Play" button - Your breakpoints will start hitting, you can set breakpoints in either Test or Generator code @@ -107,7 +101,7 @@ If you would like to debug the `testUserCase.spec.ts` file (after the SDK is gen - Once the Test Server is running 1. In VSCode go to the debugger tab - 2. Select the "IntegrationTests" profile from the drop down + 2. Select the "[CADL] - Integration Test" profile from the drop down 3. Click the "Play" button - **\*\***IMPORTANT**\*\***: Running Integration Tests for debugging, does not re-generate the test clients so make sure that after each change you do: From 698e9e098319d3758adbc7151cde3fe270d2ac83 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Tue, 1 Nov 2022 11:25:25 +0800 Subject: [PATCH 11/13] update resolve comments --- packages/cadl-typescript/CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md index 50ee6f0578..9ee4dd5135 100644 --- a/packages/cadl-typescript/CONTRIBUTING.md +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -38,7 +38,7 @@ Running the command above will do the following things: - Run all the tests under test/integration - Stop TestServer -**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server:v2`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) +**_Note_**: If your development environment is Windows, then run the command `npm run start-test-server`(in a seperate window) before running `npm run test` and run the command `npm run stop-test-server` after. (In non windows machines, we could run the test-server in the background automatically. But, in Windows machines, it has to be done manually.) 5. You can run the Smoke tests using the following command: @@ -53,7 +53,7 @@ Whenever you work on adding a feature/fixing a bug, this would probably be your 1. Pick up a cadl as your test input in cadl-ranch. Below are some examples -Let us say your test input will be called `testUserCase.json`. +Let us say your test input is `authentication/api-key/main.cadl` in @azure-tools/cadl-ranch-specs. 2. Now add an entry to the CadlRanchConfig to the file [`cadl-ranch-list.ts`](./test/commands/cadl-ranch-list.ts). In the file, add the following to the array. From a17302c97fea0c29d0851b17fd42565f9be75c86 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Tue, 1 Nov 2022 11:31:54 +0800 Subject: [PATCH 12/13] update contributing guide --- packages/cadl-typescript/CONTRIBUTING.md | 30 +++++++++++++++++++----- 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md index 9ee4dd5135..af2974696b 100644 --- a/packages/cadl-typescript/CONTRIBUTING.md +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -42,7 +42,7 @@ Running the command above will do the following things: 5. You can run the Smoke tests using the following command: -``` +```shell cd ../../packages/cadl-rlc-test npm run smoke-test ``` @@ -55,22 +55,40 @@ Whenever you work on adding a feature/fixing a bug, this would probably be your Let us say your test input is `authentication/api-key/main.cadl` in @azure-tools/cadl-ranch-specs. -2. Now add an entry to the CadlRanchConfig to the file [`cadl-ranch-list.ts`](./test/commands/cadl-ranch-list.ts). In the file, add the following to the array. +1. Now add an entry to the CadlRanchConfig to the file [`cadl-ranch-list.ts`](./test/commands/cadl-ranch-list.ts). In the file, add the following to the array. -``` +```typescript { outputPath: "authentication/apiKey", inputPath: "authentication/api-key" }, ``` -3. Now, You can generate the RLC for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development, you can comment out other test cases. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) - +1. Create a cadl-project.yaml in `./test/integration/generated/authentication/apiKey` folder and put the following content in it. + +```yaml +emitters: + "../../../../../../../../../../../packages/cadl-typescript/dist/src/index.js": + generateMetadata: true + generateTest: true + includeShortcuts: true + azureSdkForJs: false + addCredentials: false + isCadlTest: true + title: AuthApiKeyClient + packageDetails: + name: "@msinternal/auth-apikey" + description: "Auth api key Test Service" + version: "1.0.0" ``` + +1. Now, You can generate the RLC for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development, you can comment out other test cases. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) + +```shell npm run generate-cadl-only ``` -4. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/integration). You can find several examples in the same place. +1. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/integration). You can find several examples in the same place. ## How to debug From e67c67d4d9b258726831db74968ec348dd8bcf12 Mon Sep 17 00:00:00 2001 From: qiaozha Date: Tue, 1 Nov 2022 11:33:57 +0800 Subject: [PATCH 13/13] fix format --- packages/cadl-typescript/CONTRIBUTING.md | 50 ++++++++++++------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/packages/cadl-typescript/CONTRIBUTING.md b/packages/cadl-typescript/CONTRIBUTING.md index af2974696b..f7670bb86a 100644 --- a/packages/cadl-typescript/CONTRIBUTING.md +++ b/packages/cadl-typescript/CONTRIBUTING.md @@ -53,40 +53,40 @@ Whenever you work on adding a feature/fixing a bug, this would probably be your 1. Pick up a cadl as your test input in cadl-ranch. Below are some examples -Let us say your test input is `authentication/api-key/main.cadl` in @azure-tools/cadl-ranch-specs. + Let us say your test input is `authentication/api-key/main.cadl` in @azure-tools/cadl-ranch-specs. 1. Now add an entry to the CadlRanchConfig to the file [`cadl-ranch-list.ts`](./test/commands/cadl-ranch-list.ts). In the file, add the following to the array. -```typescript - { - outputPath: "authentication/apiKey", - inputPath: "authentication/api-key" - }, -``` + ```typescript + { + outputPath: "authentication/apiKey", + inputPath: "authentication/api-key" + }, + ``` 1. Create a cadl-project.yaml in `./test/integration/generated/authentication/apiKey` folder and put the following content in it. -```yaml -emitters: - "../../../../../../../../../../../packages/cadl-typescript/dist/src/index.js": - generateMetadata: true - generateTest: true - includeShortcuts: true - azureSdkForJs: false - addCredentials: false - isCadlTest: true - title: AuthApiKeyClient - packageDetails: - name: "@msinternal/auth-apikey" - description: "Auth api key Test Service" - version: "1.0.0" -``` + ```yaml + emitters: + "../../../../../../../../../../../packages/cadl-typescript/dist/src/index.js": + generateMetadata: true + generateTest: true + includeShortcuts: true + azureSdkForJs: false + addCredentials: false + isCadlTest: true + title: AuthApiKeyClient + packageDetails: + name: "@msinternal/auth-apikey" + description: "Auth api key Test Service" + version: "1.0.0" + ``` 1. Now, You can generate the RLC for your test case with the following command: (Initially, during your development, you do not want to run all the cases during every step of your development, you can comment out other test cases. But, once your code changes are complete for your case, then you need to run the entire suite to ensure that your changes did not cause any unwanted changes.) -```shell -npm run generate-cadl-only -``` + ```shell + npm run generate-cadl-only + ``` 1. Once you are satisfied with the generated code, you can add a spec file such as `testUserCaseRest.spec.ts` file [here](./test/integration). You can find several examples in the same place.