<commit_before><!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

Integration Testing 
===================

To run integration tests, you have to specify the druid cluster the
tests should use.  

Druid comes with the mvn profile integration-tests
for setting up druid running in docker containers, and using that
cluster to run the integration tests.

To use a druid cluster that is already running, use the
mvn profile int-tests-config-file, which uses a configuration file 
describing the cluster.

Integration Testing Using Docker 
-------------------

Before starting, if you don't already have docker on your machine, install it as described on 
[Docker installation instructions](https://docs.docker.com/install/). Ensure that you 
have at least 4GiB of memory allocated to the docker engine. (You can verify it 
under Preferences > Resources > Advanced.)

Also set the `DOCKER_IP`
environment variable to localhost on your system, as follows:

```bash
export DOCKER_IP=127.0.0.1
```

Optionally, you can also set `APACHE_ARCHIVE_MIRROR_HOST` to override `https://archive.apache.org` host. This host is used to download archives such as hadoop and kafka during building docker images:

```bash
export APACHE_ARCHIVE_MIRROR_HOST=https://example.com/remote-generic-repo
```

## Running tests againt auto brought up Docker containers

> NOTE: This section describes how to start integration tests against docker containers which will be brought up automatically by following commands.
If you want to buid docker images and run tests separately, see the next section.

To run all tests from a test group using docker and mvn run the following command: 
(list of test groups can be found at `integration-tests/src/test/java/org/apache/druid/tests/TestNGGroup.java`)
```bash
mvn verify -P integration-tests -Dgroups=<test_group>
```

To run only a single test using mvn run the following command:
```bash
mvn verify -P integration-tests -Dgroups=<test_group> -Dit.test=<test_name>
```
The test group should always be set, as certain test setup and cleanup tasks are based on the test group. You can find
the test group for a given test as an annotation in the respective test class.

Add `-rf :druid-integration-tests` when running integration tests for the second time or later without changing
the code of core modules in between to skip up-to-date checks for the whole module dependency tree.

Integration tests can also be run with either Java 8 or Java 11 by adding `-Djvm.runtime=#` to mvn command, where `#`
can either be 8 or 11.

Druid's configuration (using Docker) can be overrided by providing `-Doverride.config.path=<PATH_TO_FILE>`. 
The file must contain one property per line, the key must start with `druid_` and the format should be snake case.
Note that when bringing up docker containers through mvn and -Doverride.config.path is provided, additional
Druid routers for security group integration test (permissive tls, no client auth tls, custom check tls) will not be started.   

## Running tests against mannually brought up Docker containers

1. Build docker images.
   
   From root module run maven command, run the following command:
   ```bash
   mvn clean install -pl integration-tests -P integration-tests -Ddocker.run.skip=true -Dmaven.test.skip=true -Ddocker.build.hadoop=true
   ```             
   
   > **NOTE**: `-Ddocker.build.hadoop=true` is optional if you don't run tests against Hadoop.

2. Choose a docker-compose file to start containers.

   There are a few different Docker compose yamls located in "docker" folder that could be used to start containers for different tests. 

   - To start basic Druid cluster (skip this if running Druid cluster with override configs):
     ```bash
     docker-compose -f integration-tests/docker/docker-compose.yml up
     ```

   - To start Druid cluster with override configs
     ```bash
     OVERRIDE_ENV=<PATH_TO_ENV> docker-compose -f docker-compose.yml up
     ```
   
   - To start tests against Hadoop
     ```bash
     docker-compose -f docker-compose.druid-hadoop.yml up
     ```
   
   - To start tests againt security group
     ```bash
     docker-compose -f docker-compose.yml -f docker-compose.security.yml up
     ```

3. Run tests.
  
   Execute the following command from root module, where `<test_name>` is the class name of a test, such as ITIndexerTest.
   ```bash
   mvn verify -P integration-tests -pl integration-tests -Ddocker.build.skip=true -Ddocker.run.skip=true -Dit.test=<test_name>
   ```

## Docker Compose files

- docker-compose.base.yml

  Base file that defines all containers for integration testing

- docker-compose.yml

  Defines a Druid cluster with default configuration that is used for running integration tests.

  ```bash
  docker-compose -f docker-compose.yml up
  # DRUID_INTEGRATION_TEST_GROUP - an environment variable that specifies the integration test group to run.
  DRUID_INTEGRATION_TEST_GROUP=batch-index docker-compose -f docker-compose.yml up
  ```

  You can change the default configuration using a custom configuration file. The settings in the file will override
  the default settings if they conflict. They will be appended to the default configuration otherwise.

  ```bash
  # OVERRIDE_ENV - an environment variable that specifies the custom configuration file path.<commit_msg>Document running it tests from intellij IDE (#12440)<commit_after><!--
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->

Integration Testing 
===================

To run integration tests, you have to specify the druid cluster the
tests should use.  

Druid comes with the mvn profile integration-tests
for setting up druid running in docker containers, and using that
cluster to run the integration tests.

To use a druid cluster that is already running, use the
mvn profile int-tests-config-file, which uses a configuration file 
describing the cluster.

Integration Testing Using Docker 
-------------------

Before starting, if you don't already have docker on your machine, install it as described on 
[Docker installation instructions](https://docs.docker.com/install/). Ensure that you 
have at least 4GiB of memory allocated to the docker engine. (You can verify it 
under Preferences > Resources > Advanced.)

Also set the `DOCKER_IP`
environment variable to localhost on your system, as follows:

```bash
export DOCKER_IP=127.0.0.1
```

Optionally, you can also set `APACHE_ARCHIVE_MIRROR_HOST` to override `https://archive.apache.org` host. This host is used to download archives such as hadoop and kafka during building docker images:

```bash
export APACHE_ARCHIVE_MIRROR_HOST=https://example.com/remote-generic-repo
```

## Running tests againt auto brought up Docker containers

> NOTE: This section describes how to start integration tests against docker containers which will be brought up automatically by following commands.
If you want to buid docker images and run tests separately, see the next section.

To run all tests from a test group using docker and mvn run the following command: 
(list of test groups can be found at `integration-tests/src/test/java/org/apache/druid/tests/TestNGGroup.java`)
```bash
mvn verify -P integration-tests -Dgroups=<test_group>
```

To run only a single test using mvn run the following command:
```bash
mvn verify -P integration-tests -Dgroups=<test_group> -Dit.test=<test_name>
```
The test group should always be set, as certain test setup and cleanup tasks are based on the test group. You can find
the test group for a given test as an annotation in the respective test class.

Add `-rf :druid-integration-tests` when running integration tests for the second time or later without changing
the code of core modules in between to skip up-to-date checks for the whole module dependency tree.

Integration tests can also be run with either Java 8 or Java 11 by adding `-Djvm.runtime=#` to mvn command, where `#`
can either be 8 or 11.

Druid's configuration (using Docker) can be overrided by providing `-Doverride.config.path=<PATH_TO_FILE>`. 
The file must contain one property per line, the key must start with `druid_` and the format should be snake case.
Note that when bringing up docker containers through mvn and -Doverride.config.path is provided, additional
Druid routers for security group integration test (permissive tls, no client auth tls, custom check tls) will not be started.   

## Running tests against mannually brought up Docker containers

1. Build docker images.
   
   From root module run maven command, run the following command:
   ```bash
   mvn clean install -pl integration-tests -P integration-tests -Ddocker.run.skip=true -Dmaven.test.skip=true -Ddocker.build.hadoop=true
   ```             
   
   > **NOTE**: `-Ddocker.build.hadoop=true` is optional if you don't run tests against Hadoop.

2. Choose a docker-compose file to start containers.

   There are a few different Docker compose yamls located in "docker" folder that could be used to start containers for different tests. 

   - To start basic Druid cluster (skip this if running Druid cluster with override configs):
     ```bash
     docker-compose -f integration-tests/docker/docker-compose.yml up
     ```

   - To start Druid cluster with override configs
     ```bash
     OVERRIDE_ENV=<PATH_TO_ENV> docker-compose -f docker-compose.yml up
     ```
   
   - To start tests against Hadoop
     ```bash
     docker-compose -f docker-compose.druid-hadoop.yml up
     ```
   
   - To start tests againt security group
     ```bash
     docker-compose -f docker-compose.yml -f docker-compose.security.yml up
     ```

3. Run tests.
  
   Execute the following command from root module, where `<test_name>` is the class name of a test, such as ITIndexerTest.
   ```bash
   mvn verify -P integration-tests -pl integration-tests -Ddocker.build.skip=true -Ddocker.run.skip=true -Dit.test=<test_name>
   ```

### Running tests from IntelliJ

Before running tests from IntelliJ, ensure you have a Druid cluster running.
Modify the tests run configurations to be the following Vm options:

```
-Duser.timezone=UTC
-Dfile.encoding=UTF-8
-Ddruid.test.config.dockerIp=localhost
-Ddruid.zk.service.host=localhost
-Ddruid.client.https.trustStorePath=client_tls/truststore.jks
-Ddruid.client.https.trustStorePassword=<PASSWORD>
-Ddruid.client.https.keyStorePath=client_tls/client.jks
-Ddruid.client.https.certAlias=druid
-Ddruid.client.https.keyManagerPassword=<PASSWORD>
-Ddruid.client.https.keyStorePassword=<PASSWORD>
```

Run tests from the test configuration often found in the top right corner of the IntelliJ IDE.
The values shown above are for the default docker compose cluster. For other clusters the values will need to be changed.

## Docker Compose files

- docker-compose.base.yml

  Base file that defines all containers for integration testing

- docker-compose.yml

  Defines a Druid cluster with default configuration that is used for running integration tests.

  ```bash
  docker-compose -f docker-compose.yml up
  # DRUID_INTEGRATION_TEST_GROUP - an environment variable that specifies the integration test group to run.
  DRUID_INTEGRATION_TEST_GROUP=batch-index docker-compose -f docker-compose.yml up
  ```

  You can change the default configuration using a custom configuration file. The settings in the file will override
  the default settings if they conflict. They will be appended to the default configuration otherwise.

  ```bash
  # OVERRIDE_ENV - an environment variable that specifies the custom configuration file path.
{'fraction_non_alphanumeric': 0.07318751911899664, 'fraction_numerical': 0.003517895380850413, 'mean_word_length': 3.9106271122793843, 'pattern_counts': {'":': 0, '<': 22, '<?xml version=': 0, '>': 30, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3072668', 'n_tokens_mistral': 3738, 'n_tokens_neox': 3507, 'n_words': 1635}