The CosmosDBNoSQLEndpointContainer was built for the standard Cosmos DB emulator image (latest tag). It does not work with the vnext-preview image (mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview), which is the newer Linux-native emulator

Both images serve the same NoSQL API, but vnext has different runtime behavior that breaks assumptions in the current module.

What breaks

1. vnext defaults to HTTP — the standard image defaults to HTTPS, which is what url and _wait_until_ready hardcode. vnext needs --protocol https passed as a command to opt into HTTPS. There is no way to configure this through the module.

2. No Data Explorer on vnext — _wait_until_ready() polls https://localhost:8081/_explorer/index.html as a readiness signal. vnext returns 400 on that path, so the check loops for 120s and times out.

3. No PEM certificate on vnext — start() calls _download_cert() looking for a file at the legacy Windows-style path inside the container. vnext does not write a cert there, so this raises docker.errors.NotFound.

4. 503s during startup are not retried — After the container is up, vnext returns CosmosHttpResponseError (503, "pgcosmos extension is still starting") for a few seconds before it can serve queries. _wait_for_query_success only catches ServiceRequestError (connection-level errors), so it does not retry on 503.

5. Endpoint discovery returns internal port — The emulator advertises https://127.0.0.1:8081 in its discovery response regardless of how ports are mapped. Using bind_ports=False causes the SDK to connect to the wrong port after discovery. Related: Emulator (preview) and TestContainers: not a happy marriage? Azure/azure-cosmos-db-emulator-docker#160

Current workaround

I wrote a subclass that overrides start(), _wait_until_ready(), and _wait_for_query_success() — it passes --protocol https as a command, skips the cert download and explorer check, and catches 503s during readiness polling. It works but depends on the internal class hierarchy, which makes it fragile.

Suggestion

Some ideas:

• Add a protocol parameter (http/https) to control the URL scheme and pass the right startup command for vnext.
• Make _wait_until_ready() skip the explorer URL check when it returns 400 or is not available. Relying on _wait_for_query_success alone is sufficient.
• Make _download_cert() optional or catch NotFound gracefully — for vnext there is no cert to download.
• Add CosmosHttpResponseError to the retry decorator in _wait_for_query_success.

Alternatively, a dedicated vnext-aware container class would keep things clean.

Versions

• testcontainers 4.14.2
• Python 3.13
• Image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview