Dev env and how to run tests

Author: Alexey Raga

.gitignore

@@ -23,6 +23,7 @@ Icon
 ### Haskell ###
 dist
 dist-newstyle
+dist-docs*
 cabal-dev
 *.o
 *.hi

README.md

@@ -215,44 +215,22 @@ _Note:_ this is a semi-naive solution as this waits forever (or until
 librdkafka times out). You should make sure that your configuration reflects
 the behavior you want out of this functionality.
 
-# Installation
+## Running integration tests locally
 
-## Installing librdkafka
+[shell.nix](./shell.nix) can be used to provide a working environment that is enough to build and test `hw-kafka-client`.
 
-Although `librdkafka` is available on many platforms, most of
-the distribution packages are too old to support `kafka-client`.
-As such, we suggest you install from the source:
+To be able to run tests locally, `$KAFKA_TEST_BROKER` environment variable is expected to be set (use [shell.nix](./shell.nix) or export manually).
 
-```bash
-    git clone https://github.com/edenhill/librdkafka
-    cd librdkafka
-    ./configure
-    make && make install
-```
+`$KAFKA_TEST_BROKER` should contain an IP address of an accessible Kafka broker that will be used to run integration tests against.
 
-Sometimes it is helpful to specify openssl includes explicitly:
+With [Docker Compose](./docker-compose.yml) this variable is used to configure Kafka broker to listen on this address:
 
 ```
-    LDFLAGS=-L/usr/local/opt/openssl/lib CPPFLAGS=-I/usr/local/opt/openssl/include ./configure
+$ docker-compose up
 ```
 
-If you are using Stack with Nix, don't forget to declare `rdkafka` as extra package:
+After that, tests can be run as usual:
 
-```yaml
-# stack.yaml
-nix:
-  enable: true
-  packages:
-    - rdkafka
 ```
-
-## Installing Kafka
-
-The full Kafka guide is at http://kafka.apache.org/documentation.html#quickstart
-
-Alternatively `docker-compose` can be used to run Kafka locally inside a Docker container.
-To run Kafka inside Docker:
-
-```bash
-$ docker-compose up
+$ cabal test --test-show-details=direct
 ```

docker-compose.yml

@@ -16,6 +16,6 @@ kafka:
     - zookeeper:zookeeper
   environment:
     KAFKA_ZOOKEEPER_CONNECT: "zookeeper:2181"
-    KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://$DOCKER_IP:9092"
+    KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://$KAFKA_TEST_BROKER:9092"
     KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
     KAFKA_CREATE_TOPICS:

shell.nix

@@ -0,0 +1,17 @@
+with import <nixpkgs> {};
+
+pkgs.mkShell {
+  buildInputs = with pkgs; [
+    zlib
+    rdkafka
+  ];
+
+  shellHook = ''
+    PATH=~/.cabal/bin:$PATH
+    LD_LIBRARY_PATH=${pkgs.zlib}/lib:$LD_LIBRARY_PATH
+    export LIBRARY_PATH=${pkgs.rdkafka}/lib
+    export C_INCLUDE_PATH=${pkgs.rdkafka}/include
+
+    export KAFKA_TEST_BROKER=$(ifconfig | sed -En 's/127.0.0.1//;s/.*inet (addr:)?(([0-9]*\.){3}[0-9]*).*/\2/p' | head -n 1)
+  '';
+}