Add IntelliJ IT docs

README.md

@@ -1,4 +1,4 @@
-## Dapr SDK for Java
+# Dapr SDK for Java
 
 [![Build Status](https://github.com/dapr/java-sdk/workflows/Build/badge.svg?event=push&branch=master)](https://github.com/dapr/java-sdk/actions?workflow=Build)
 [![Discord](https://img.shields.io/discord/778680217417809931)](https://discord.com/channels/778680217417809931/778749797242765342) 
@@ -15,9 +15,9 @@ This is the Dapr SDK for Java, including the following features:
 * State Store
 * Actors
 
-### Getting Started
+## Getting Started
 
-#### Pre-Requisites
+### Pre-Requisites
 * JDK 11 or above - the published jars are compatible with Java 8:
     * [Microsoft JDK 11](https://docs.microsoft.com/en-us/java/openjdk/download#openjdk-11)
     * [AdoptOpenJDK 11 - LTS](https://adoptopenjdk.net/)
@@ -41,7 +41,7 @@ This is the Dapr SDK for Java, including the following features:
     * [New Maven project in IntelliJ](https://www.jetbrains.com/help/idea/maven-support.html#create_new_maven_project)
     * [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
 
-#### Importing Dapr's Java SDK
+### Importing Dapr's Java SDK
 For a Maven project, add the following to your `pom.xml` file:
 ```xml
 <project>
@@ -86,7 +86,7 @@ dependencies {
 }
 ```
 
-#### Running the examples
+### Running the examples
 Clone this repository including the submodules:
 
 ```sh
@@ -112,11 +112,11 @@ Try the following examples to learn more about Dapr's Java SDK:
 * [Exception handling](./examples/src/main/java/io/dapr/examples/exception)
 * [Unit testing](./examples/src/main/java/io/dapr/examples/unittesting)
 
-#### API Documentation
+### API Documentation
 
 Please, refer to our [Javadoc](https://dapr.github.io/java-sdk/) website.
 
-#### Reactor API
+### Reactor API
 
 The Java SDK for Dapr is built using [Project Reactor](https://projectreactor.io/). It provides an asynchronous API for Java. When consuming a result is consumed synchronously, as in the examples referenced above, the `block()` method is used.
 
@@ -132,7 +132,7 @@ Mono<Void> result = daprClient.publishEvent("mytopic", "my message");
 result.block();
 ```
 
-#### How to use a custom serializer
+### How to use a custom serializer
 
 This SDK provides a basic serialization for request/response objects but also for state objects. Applications should provide their own serialization for production scenarios.
 
@@ -162,7 +162,7 @@ This SDK provides a basic serialization for request/response objects but also fo
     ```
 
 
-#### Debug Java application or Dapr's Java SDK
+### Debug Java application or Dapr's Java SDK
 
 **In IntelliJ Community Edition, consider [debugging in IntelliJ](https://docs.dapr.io/developing-applications/ides/intellij/).**
 
@@ -185,13 +185,13 @@ DAPR_GRPC_PORT=5001
 
 Now you can go to your IDE (like Eclipse, for example) and debug your Java application, using port `3500` to call Dapr while also listening to port `3000` to expose Dapr's callback endpoint.
 
-#### Exception handling
+### Exception handling
 
 Most exceptions thrown from the SDK are instances of `DaprException`. `DaprException` extends from `RuntimeException`, making it compatible with Project Reactor. See [example](./examples/src/main/java/io/dapr/examples/exception) for more details.
 
-### Development
+## Development
 
-#### Update proto files
+### Update proto files
 
 Change the properties below in [pom.xml](./pom.xml) to point to the desired reference URL in Git. Avoid pointing to `master` branch since it can change over time and create unpredictable behavior in the build.
 
@@ -207,3 +207,69 @@ Change the properties below in [pom.xml](./pom.xml) to point to the desired refe
   ...
 </project>
 ```
+
+### Running Integration Tests
+
+#### Pre-Requisites for ITs
+Along with the pre-requisites for [SDK](#pre-requisites) the following are needed. 
+
+* Docker installed 
+  * [Docker Compose](https://docs.docker.com/compose/install/) 
+  * [Docker Desktop](https://www.docker.com/products/docker-desktop)
+* Bash shell
+  * In Windows use [WSL2](https://docs.microsoft.com/en-us/windows/wsl/install)
+  * In Linux and Mac, default shells are enough
+
+#### Code
+
+The code for the tests are present inside the project [sdk-tests](./sdk-tests). This module alone can be imported as a separate project in IDEs. 
+This project depends on the rest of the JARs built by the other modules in the repo like [sdk](./sdk), [sdk-springboot](./sdk-springboot) etc.
+
+As a starting point for running Integration Tests, first run `mvn clean install` from the root of the repo to build the JARs for the different modules
+except the `sdk-tests` module.
+
+#### Run all the dependent services spun up during build
+
+During normal CI build, docker compose is used to bring up services like MongoDB, Hashicorp Vault, Apache Zookeeper, Kafka etc. 
+
+Similarly, all of these need to be run for running the ITs either individually or as a whole.
+
+Run the following commands from the root of the repo to start all the docker containers that the tests depend on.
+
+```bash
+docker-compose -f ./sdk-tests/deploy/local-test-kafka.yml up -d
+docker-compose -f ./sdk-tests/deploy/local-test-mongo.yml up -d
+docker-compose -f ./sdk-tests/deploy/local-test-vault.yml up -d
+```
+
+To stop the containers and services, run the following commands.
+
+```bash
+docker-compose -f ./sdk-tests/deploy/local-test-kafka.yml down
+docker-compose -f ./sdk-tests/deploy/local-test-mongo.yml down
+docker-compose -f ./sdk-tests/deploy/local-test-vault.yml down
+```
+
+
+#### Run all ITs from command line
+From the `java-sdk` repo root, change to the `sdk-tests` directory and run the following command.
+
+```bash
+## with current directory as /java-sdk/sdk-tests/
+
+mvn clean install
+```
+
+The above command runs all the integration tests present in the `sdk-tests` project. 
+
+#### Run Individual tests from IntelliJ
+
+In IntelliJ, go to `File > New > Project from Existing Sources...`. Import the `sdk-tests` project. 
+
+Once the project has been imported, the individual tests can be run normally as any Unit Tests, from the IDE itself.
+
+![intellij-integration-test](./examples/src/main/resources/img/intellij-integration-test.png).
+
+> Sometimes when the `sdk-tests` project does not build correctly, try `File > Invalidate Caches...`  and try restarting IntelliJ.
+
+You should be able to set breakpoints and Debug the test directly from IntelliJ itself as seen from the above image. 

sdk-tests/deploy/local-test-kafka.yml

@@ -5,6 +5,8 @@ services:
     ports:
       - "2181:2181"
   kafka:
+    depends_on:
+      - zookeeper
     image: wurstmeister/kafka:latest
     ports:
       - "9092:9092"