Azure Cosmos DB Emulator limits: which behaviors still require a real account for integration tests?

Answer to the Core Question

For most unit‑level and simple integration tests the Azure Cosmos DB Emulator works fine. However, the following NoSQL API behaviors are either not fully supported or diverge from the cloud service, meaning a real Cosmos DB account is required for trustworthy results:

• Change Feed – Basic push‑mode change feed is emulated, but pull‑mode, lease‑container logic, and multi‑master scenarios are incomplete.
• Time‑to‑Live (TTL) – Expired items are retained until a compaction or manual delete; exact second‑precision deletion is not guaranteed.
• Composite, spatial, and mixed‑type indexing policies – These indexes are ignored or produce different query plans in the emulator.
• Consistency levels beyond Strong and Eventual – The emulator treats all requests as Strong; Bounded Staleness, Session, and Consistent Prefix are not differentiated.
• Throughput‑related tests – Request‑unit (RU) limits are not enforced; performance tests may pass locally but fail in the cloud.

Confirmed Facts

From the latest emulator release notes (v5.x) and community reports:

• The emulator caps 25 containers per database account and limits local storage to roughly 10 GB. These limits are hard‑coded and cannot be changed via command‑line flags.
• Container‑count and storage limits are not configurable; exceeding them will cause test failures that do not reflect cloud behaviour.
• Linux container images lag behind Windows in feature parity. The current Linux image (v5.2‑linux) still lacks full support for change‑feed pull mode and composite indexes, whereas the Windows image (v5.3) has recently added those features.
• CI pipelines that rely solely on the Linux emulator may receive false positives for change‑feed and indexing tests. A small subset of tests against a real dev‑tier account is recommended to catch missing behaviour.

Practical Steps for Your Test Suite

1. Determine the emulator version. Run docker exec <container> azdata cosmosdb emulator show or query /_explorer/emulator.json inside the container. Compare the Version field to the latest release on the Azure Cosmos DB Emulator download page.
2. Run a targeted test matrix. Execute the following subset of tests against the emulator:
   • Change‑feed pull mode and lease‑container creation.
   • TTL expiration with a 1‑second TTL.
   • Queries that rely on composite or spatial indexes.
   • Read operations with Session consistency.
3. Record any failures or unexpected results.
4. Run the same subset against a real Azure Cosmos DB NoSQL account (Free or dev tier) and compare outcomes.
5. Mark any discrepancies as "needs real account".

What to Ask Next

To refine the recommendation for your CI pipeline, please provide the exact emulator version you plan to use in the Linux container. If you are using a custom Docker image, confirm that it is built from the official mcr.microsoft.com/cosmosdb/linux base and that the AZURE_COSMOSDB_EMULATOR_HOST environment variable points to the correct endpoint.

Conclusion

Use the emulator for quick local runs and most unit tests, but schedule a regular run of the critical subset against a real dev‑tier account to guard against the documented divergences. The Linux container can be used for CI, but be aware of its feature gaps and plan for occasional Windows‑based tests if you need full parity.