Setting up the Task

First off you need to go to the Azure Pipelines Marketplace and install the emulator in your organization.

Now add the task to your azure-pipelines.yml:

- task: azure-cosmosdb.emulator-public-preview.run-cosmosdbemulatorcontainer.CosmosDbEmulator@2
  displayName: 'Run Azure Cosmos DB Emulator'

Note that the task mentions “public preview”, so this will likely need to change when the emulator becomes generally available.

Making the Connection

Now where you run the test you can pass through the CosmosDbEmulator.Endpoint variable provided by the task, add in the auth key that is hardcoded in the emulator and disable TLS to prevent self-signed certificate errors (example is with Node.JS).

- script: yarn test
  displayName: 'Run tests using Cosmos DB emulator'
  env:
    ENDPOINT: $(CosmosDbEmulator.Endpoint)
    KEY: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    NODE_TLS_REJECT_UNAUTHORIZED: '0'

Adding a Condition for Matrix Builds

The emulator is currently only supported on Windows, so you can either set this up in a separate job for Windows or use a condition for that step if you’re using a matrix build like this:

strategy:
  matrix:
    linux:
      imageName: 'ubuntu-latest'
    mac:
      imageName: 'macos-latest'
    windows:
      imageName: 'vs2017-win2016'

...

- task: azure-cosmosdb.emulator-public-preview.run-cosmosdbemulatorcontainer.CosmosDbEmulator@2
  displayName: 'Run Azure Cosmos DB Emulator'
  # Using this condition will ensure this step only runs on the Windows VM
  condition: eq(variables['imageName'], 'vs2017-win2016')

Outsite Azure Pipelines

It should be possible to use the emulator outside of Azure Pipelines with Docker for Windows but it would be a little more difficult to setup without the pre-packaged task. Consult the official documentation and the GitHub repo for how to go about doing this.

More posts tagged Cosmos DB