cosmos-run-integration-tests

Running azure-cosmos integration tests locally (CI-equivalent)

TL;DR

CI runs tests in two separate Maven invocations, both on the same JDK (the version CI pins via JavaTestVersion in eng/pipelines/templates/variables/globals.yml):

1. Build + install (-DskipTests ... install) — compiles main + test classes, installs jars.
2. Test (verify -P<profile> -DskipCompile=true -DskipTestCompile=true) — failsafe runs the TestNG suite.

Because step 2 skips compilation, it runs the classes/jars step 1 produced — so both steps must use the same JDK (see below).

There is no separate "surefire command" — integration tests run through failsafe via mvn verify -P<profile>.

⚠️ Critical: use the same JDK for build (step 1) and test (step 2)

Step 1 compiles main + test classes and installs the azure-cosmos / azure-cosmos-tests jars into ~/.m2 using whatever JAVA_HOME you build with. A local incremental install packages those classes at the build JDK's class-file version (the java9plus profile's default-compile / default-testCompile use <release>${java.vm.specification.version}</release>, i.e. the build VM's version). Step 2 then skips compilation (-DskipCompile=true -DskipTestCompile=true) and runs those already-built classes.

So if step 1 and step 2 use different JDKs you get class-file version mismatches. Example: build on a newer JDK (class file v65/v69), then run step 2 on JDK 17 (v61) and javac / the runtime rejects the jars with misleading errors like:

cannot access com.azure.cosmos.implementation.TestConfigurations
  bad class file: ...azure-cosmos-*.jar(.../TestConfigurations.class)
  class file has wrong version 65.0, should be 61.0

This is NOT a JPMS / module-path / javaModulesSurefireArgLine problem. The parent already sets useModulePath=false; azure-cosmos lands on -classpath correctly. The only cause is the JDK mismatch between the two steps.

Fix: pick one JDK and use it for both steps — ideally the major version CI uses for tests (JavaTestVersion in eng/pipelines/templates/variables/globals.yml). Point JAVA_HOME at that JDK and prepend it to PATH at the top of every command (adjust the path to your local install):

$env:JAVA_HOME='<path-to-your-jdk>'   # e.g. C:\Program Files\OpenLogic\jdk-21.0.10.7-hotspot
$env:PATH="$env:JAVA_HOME\bin;$env:PATH"