Tags:

- [Azure](/content/p/explore.html?t=Azure/index.html)
- [Cosmos DB](/content/p/explore.html?t=Cosmos%20DB/index.html)
- [Azure Pipelines](/content/p/explore.html?t=Azure%20Pipelines/index.html)

When working on an application that interfaces with an Azure Cosmos DB backend you could use an actual Cosmos DB instance to test against but that’s a bit of a hassle as it involves setting up and configuring an actual instance. It turns out there is an emulator that runs in a docker container that you can test against instead.

### Setting up the Task

First off you need to go to [the Azure Pipelines Marketplace](https://marketplace.visualstudio.com/items?itemName=azure-cosmosdb.emulator-public-preview) 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](https://docs.microsoft.com/en-us/azure/devops/pipelines/get-started-multiplatform?view=azure-devops) 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')
```

### Outside 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](https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator#running-on-docker) and the [GitHub repo](https://github.com/Azure/azure-cosmos-db-emulator-docker) for how to go about doing this.