druid/integration-tests-ex/docs/quickstart.md

Quickstart

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.

Example Test

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.)

Working with Individual Tests

To work with tests for development and debugging, you can break the above all-in-one step into a number of sub-steps.

• [Build Druid](#Build Druid).
• [Build the Docker image](#Build the Docker Image).
• [Start a cluster](#Start a Cluster).
• [Run a test from the command line](#Run a Test from the Command Line).
• [Run a test from an IDE](#Run a Test from an IDE).
• [Stop the cluster](#Stop the Cluster).
• [Clean up](#Clean Up).

Build Druid

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

Build the Docker Image

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.

Run an IT from the Command Line

./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.

Start a Cluster

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.

Run a Test from an IDE

To run an IT in your IDE:

• Find the IT to run.
• Run it as a JUnit test.

The tests are specifically designed to require no command-line setup: you can just run them directly.

Stop the Cluster

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

Clean Up

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.