What's the Mock Service Host
The Mock Service Host works as a mock server for ARM FrontDoor Service. It supports all management plane APIs that are defined in the azure-rest-api-specs repo (or any subset of it). It could be invoked from different types of clients including AzureCLI/Terraform/SDKs/Postman, etc. and it has the below capabilities:
- Verify whether the incoming request meets the Swagger definition.
- Generate a response based on Swagger and return it to the client.
- Generate Swagger examples based on the request and response.
The Behaviour of Mock Service Host
The Mock Service Host could be run in your local environment. After started, it will listen to the following endpoints by default:
- https://localhost:8441, stateful.
- http://localhost:8442, stateless http.
- https://localhost:8443, stateless https.
- https://localhost:8445, always return 500 to simulate service internal error (except resourcegroup operations).
Since currently the HTTPS certificate is created with domain localhost, so the HTTPS endpoints can only be visited though "localhost".
NOTE: If these listening ports are already been used by other apps in your local environment, change the default ports according to the Configuration.
- Client could only call GET/DELETE after CREATE succeeded, otherwise it will get the response code of 404.
- If cascadeEnabled is true:
- The sub resource could only be created if parent resource already exists. For instance: the following resources should be created one after another: resourceGroup-->virtual network-->subnet.
- Deleting a parent resource will also delete it's all descendants.
- If cascadeEnabled is false:
- Can create sub resource even if parent does not exist.
- Deleting a parent resource will not delete it's children.
- Mock service host will return a valid mocked response for each valid call of GET/List.
- Nodejs 14.15 or above
Run Mock Service Host
Install Mock Service Host
You need to create a workspace to place the config and cache of Mock Service Host and then use
npm install to get the latest version.
# mkdir <MY_WORKSPACE> && cd <MY_WORKSPACE> # npm install @azure-tools/mock-service-host
Configure Mock Service Host's running environment to use your local swagger
The Azrue Rest Api Spec repo is a companion repo of Mock Service Host. By default, the Mock Service Host downloads the public azure swagger repo to the cache folder and loads the target Resource provider based on configuration. You can ask it to load all RPs by add config file '.env' under your workspace.
+-- <MY_WORKSPACE>/ | +-- cache/ // swagger repos will be downloaded here in the first start-up of mock-service-host | +-- .env // you can create this file, and add configs in it.
Set target swagger files as bellow in .env:
specRetrievalGitUrl=https://github.com/Azure/azure-rest-api-specs specRetrievalGitBranch=main specRetrievalGitCommitID=6023d2b16a66b70c7a870a003c2e3f6750eacd70 validationPathsPattern=specification/*/resource-manager/*/**/*.json
Change specRetrievalGitUrl and specRetrievalGitBranch if you are not using the public swagger main branch. Change specRetrievalGitCommitID if you are not using the branch head. And you can specify a filter rule to enable only your own RP's json files to accelerate the loading speed of Mock Service Host. For instance:
Start Mock Service Host
# cd <MY_WORKSPACE> # node node_modules/@azure-tools/mock-service-host/dist/src/main.js
Common trouble shootings for starting the web server:
- Make sure all ports used in Mock Service Host haven't been used by other processes.
- Try to use sudo/"run as administrator" if failed to start listening.
It takes up to two minutes to load all swagger files in the
azure-rest-api-specs repo after the Mock Service Host started. When loading finished, a log with "validator initialized" is shown in the console.
Consume Mock Service Host
You can use different client tool/lib to consume the Mock Service Host after it is started.
You can create a file .env to customize the configurations used at runtime. The file .env should be located at current working directory, for instance:
+-- mock-service-host | +-- .env // configuration files
Customize Mock Service Host listen ports
Bellow options in .env are available to configure the server to listen specific local TCP ports.
httpsPortStateful=5001 httpPortStateless=5002 httpsPortStateless=5003 internalErrorPort=5004
Consume a remote swagger repo
You can use below configures to configure the server to load and run against a remote swagger repo:
specRetrievalMethod=git specRetrievalLocalRelativePath=./cache specRetrievalGitUrl=https://github.com/Azure/azure-rest-api-specs-pr specRetrievalGitBranch=main
Consume a local swagger repo
Instead of download swagger repo from git remotely, you can configure the Mock Service Host to load your local swagger files:
specRetrievalMethod=filesystem specRetrievalLocalRelativePath=../azure-rest-api-specs validationPathsPattern=specification/*/resource-manager/*/**/*.json
Configure example generation folder
With below configuration, the REST calling request and mocked response can be preserved in local swagger repo.
The example files are generated in the mock sub-folder relative to the swagger directory, for example:
- [specRetrievalLocalRelativePath]\specification\apimanagement\resource-manager\Microsoft.ApiManagement\preview\2018-01-01\mock You can update exampleGenerationFolder in file .env to use another folder, for instance:
The stateful endpoint has different behaviour on Create/Delete operations depending on value of cascadeEnabled. The cascadeEnabled is false by default, you can enable it in file .env like below: