If you just need to know how to build, run and use the tests, this is the place. You can refer to the detailed material later as you add new tests or work to improve the tests.
When first learning the framework, you can try thing out using the HighAvailability test. Of the tests converted thus far, it is the one that runs for the shortest time (on the order of a minute or two.)
To work with tests for development and debugging, you can break the above all-in-one step into a number of sub-steps.
The integration tests start with a Druid distribution in distribution/target, which you can build using your preferred Maven command line. Simplest:
cd $DRUID_DEV ./it.sh dist
Or, in detail:
For example: To make the text a bit simpler, define a variable for the standard settings:
export MAVEN_IGNORE=-P skip-static-checks,skip-tests -Dmaven.javadoc.skip=true
mvn clean package -P dist $MAVEN_IGNORE -T1.0C
Hint: put this into a script somewhere, such as a ~/bin directory and add that to your PATH. A good name is bdru (Build DRUid). Here is the full script:
#! /bin/bash mvn clean package -P dist,skip-static-checks,skip-tests \ -Dmaven.javadoc.skip=true -T1.0C $*
Now you can run the any Druid build with the above script. To resume a build:
> bdru -rf :foo
You must rebuild the Docker image whenever you rebuild the Druid distribution, since the image includes the distribution. You also will want to rebuild the image if you change the it-image project which contains the build scripts.
./it.sh image
In detail, and assuming DRUID_DEV points to your Druid build directory, to build the image (only):
cd $DRUID_DEV/integration-tests-ex/image mvn install -P test-image $MAVEN_IGNORE
The above has you cd into the project to avoid the need to disable all the unwanted bits of the Maven build.
See this page for more information.
./it.sh test <category>
Or, in detail:
mvn verify -P docker-tests,IT-<category> -pl :druid-it-cases \ -P skip-static-checks,skip-tests -Dmaven.javadoc.skip=true -DskipUTs=true
Where <category> is one of the test categories.
Or
cd $DRUID_DEV/integration-tests-ex/cases mvn verify -P skip-static-checks,docker-tests,IT-<category> \ -Dmaven.javadoc.skip=true -DskipUTs=true \ -pl :druid-it-cases
If the test fails, find the Druid logs in target/shared/logs within the test group project.
The previous generation of tests were organized into TestNG groups. This revision moves those groups into Maven modules. Each group has a distinct cluster configuration. (In fact, it is the cluster configuration which defines the group: we combine all tests with the same configuration into the same module.) So, to start a cluster, you have to pick a group to run. See this list for the list of groups.
./it.sh up <category>
Or, in detail:
cd $DRUID_DEV/integration-tests-ex/cases ./cluster.sh <category> up
You can use Docker Desktop to monitor the cluster. Give things about 30 seconds or a minute: if something is going to fail, it will happen during starup and you'll see that one or more containers exited unexpectedly.
Remember to first shut down any Druid cluster you may already be running on your machine.
See this page for more information.
To run an IT in your IDE:
The tests are specifically designed to require no command-line setup: you can just run them directly.
Once you are done with your cluster, you can stop it as follows:
./it.sh down <category>
Or, in detail:
cd $DRUID_DEV/integration-tests-ex/<group> ./cluster.sh <category> down
You can remove the Docker image when you no longer need it:
cd $DRUID_DEV mvn clean -P test-image
It is usually fine to skip this step: the next image build will replace the current one anyway.