Create integration tests

Signed-off-by: Cy Rossignol <[email protected]>

Author: cyrossignol

.gitattributes

@@ -3,6 +3,9 @@
 /.gitignore         export-ignore
 /.scrutinizer.yml   export-ignore
 /.travis.yml        export-ignore
+/docker-compose.yml export-ignore
+/phpcs.xml.dist     export-ignore
 /phpspec.yml.dist   export-ignore
 /phpunit.xml.dist   export-ignore
+/start-cluster.sh   export-ignore
 /tests              export-ignore

.gitignore

@@ -1,7 +1,10 @@
 build/
+cluster/
 docs/
 vendor/
 composer.phar
 composer.lock
+docker-compose.override.yml
+phpcs.xml
 phpspec.yml
 phpunit.xml

.travis.yml

@@ -2,50 +2,52 @@ language: php
 dist: trusty
 
 php:
-    - 5.6
-    - 7.0
-    - 7.1
-    - 7.2
-    - hhvm
+  - 5.6
+  - 7.0
+  - 7.1
+  - 7.2
+  - hhvm
 
 env:
-    - LARAVEL_VERSION=">=5.4.0 <5.4.20"
-    - LARAVEL_VERSION=">=5.4.20 <5.5.0"
-    - LARAVEL_VERSION="5.5.*"
-    - LARAVEL_VERSION="5.6.*"
-    - LUMEN_VERSION="5.4.*"
-    - LUMEN_VERSION="5.5.*"
-    - LUMEN_VERSION="5.6.*"
+  - LARAVEL_VERSION=">=5.4.0 <5.4.20"
+  - LARAVEL_VERSION=">=5.4.20 <5.5.0"
+  - LARAVEL_VERSION="5.5.*"
+  - LARAVEL_VERSION="5.6.*"
+  - LUMEN_VERSION="5.4.*"
+  - LUMEN_VERSION="5.5.*"
+  - LUMEN_VERSION="5.6.*"
 
 matrix:
-    exclude:
-        - php: 5.6
-          env: LARAVEL_VERSION="5.5.*"
-        - php: 5.6
-          env: LUMEN_VERSION="5.5.*"
-        - php: 5.6
-          env: LARAVEL_VERSION="5.6.*"
-        - php: 5.6
-          env: LUMEN_VERSION="5.6.*"
-        - php: 7.0
-          env: LARAVEL_VERSION="5.6.*"
-        - php: 7.0
-          env: LUMEN_VERSION="5.6.*"
-        - php: hhvm
-          env: LARAVEL_VERSION="5.5.*"
-        - php: hhvm
-          env: LUMEN_VERSION="5.5.*"
-        - php: hhvm
-          env: LARAVEL_VERSION="5.6.*"
-        - php: hhvm
-          env: LUMEN_VERSION="5.6.*"
+  exclude:
+    - php: 5.6
+      env: LARAVEL_VERSION="5.5.*"
+    - php: 5.6
+      env: LUMEN_VERSION="5.5.*"
+    - php: 5.6
+      env: LARAVEL_VERSION="5.6.*"
+    - php: 5.6
+      env: LUMEN_VERSION="5.6.*"
+    - php: 7.0
+      env: LARAVEL_VERSION="5.6.*"
+    - php: 7.0
+      env: LUMEN_VERSION="5.6.*"
+    - php: hhvm
+      env: LARAVEL_VERSION="5.5.*"
+    - php: hhvm
+      env: LUMEN_VERSION="5.5.*"
+    - php: hhvm
+      env: LARAVEL_VERSION="5.6.*"
+    - php: hhvm
+      env: LUMEN_VERSION="5.6.*"
 
-before_script:
-    - if [ -n "$LARAVEL_VERSION" ]; then composer remove --dev --no-update "laravel/lumen-framework"; fi
-    - if [ -n "$LARAVEL_VERSION" ]; then composer require --no-update "laravel/framework:$LARAVEL_VERSION"; fi
-    - if [ -n "$LUMEN_VERSION" ]; then composer remove --dev --no-update "laravel/framework"; fi
-    - if [ -n "$LUMEN_VERSION" ]; then composer require --no-update "laravel/lumen-framework:$LUMEN_VERSION"; fi
-    - composer install --prefer-source --no-interaction
+before_install:
+  - if [ -n "$LARAVEL_VERSION" ]; then composer remove --dev --no-update "laravel/lumen-framework"; fi
+  - if [ -n "$LARAVEL_VERSION" ]; then composer require --no-update "laravel/framework:$LARAVEL_VERSION"; fi
+  - if [ -n "$LUMEN_VERSION" ]; then composer remove --dev --no-update "laravel/framework"; fi
+  - if [ -n "$LUMEN_VERSION" ]; then composer require --no-update "laravel/lumen-framework:$LUMEN_VERSION"; fi
 
-script:
-    - vendor/bin/phpunit
+install: composer install --prefer-dist --no-interaction --no-suggest
+
+before_script: SUPERVISE=no ./start-cluster.sh || { cat ./cluster/*.log; false; }
+
+script: vendor/bin/phpunit ${LUMEN_VERSION:+--exclude-group laravel-only}

README.md

@@ -144,6 +144,10 @@ This example configures the package [through the environment][s-env-config]. It
 the configurable environment variables. Optionally, enable the [`RedisSentinel`
 facade][s-facade].
 
+For those that need a quick development Sentinel server cluster, try the
+[*start-cluster.sh*][s-integration-tests] script included with the package's
+testing files.
+
 Configuration
 -------------
 
@@ -661,15 +665,74 @@ Testing
 -------
 
 This package includes a PHPUnit test suite with unit tests for the package's
-classes. This package does not perform functional/integration tests against
-running Redis or Sentinel servers because Predis and Laravel both contain full
-test suites, and because the package code simply wraps these libraries. We may
-add these types of tests in the future if needed.
+classes and an integration test suite for Sentinel-specific functionality and
+known issues. These tests do not verify every Redis command because Predis and
+Laravel both contain full test suites themselves, and because the package code
+simply wraps these libraries.
 
+```shell
+$ phpunit --testsuite unit
+$ phpunit --testsuite integration
 ```
-$ phpunit
+
+The unit tests do not require live Redis servers. Read the next section for
+integration testing environment suggestions.
+
+**Note:** Composer does not download this package's testing files with a normal
+installation. We need to clone the package repository directly or install it
+with the `--prefer-source` option.
+
+### Integration Tests
+
+This package's integration test suite validates Sentinel- and Redis-specific
+functionality against real servers. These tests require at least one Sentinel
+server that monitors a Redis master. Additionally, at least one replica should
+synchronize with the master for optimal test coverage. Developers may supply
+their own servers or start an environment using the package's tools described
+below.
+
+To customize the Sentinel connection settings used by the integration tests,
+copy *phpunit.xml.dist* to *phpunit.xml* and change the constants defined in
+the `<php>...</php>` block.
+
+We can run the [*start-cluster.sh*](start-cluster.sh) script provided in the
+project's root directory to spin up Redis and Sentinel servers for a testing
+environment. Read the script help page for usage information.
+
+```shell
+$ ./start-cluster.sh help
 ```
 
+Docker users may wish to use the script to start testing servers in a container:
+
+```shell
+$ docker run --name redis-sentinel \
+    -v "$(pwd):/project" \
+    -w /project \
+    -u "$(id -u):$(id -g)" \
+    -e BIND_ADDRESS=0.0.0.0 \
+    -e SENTINEL_PORTS='26379-26381' \
+    -e REDIS_GROUP_1='service1 6379-6381' \
+    -e REDIS_GROUP_2='service2 6382-6384' \
+    -e LOGGING=yes \
+    -p 6379-6384:6379-6384 \
+    -p 26379-26381:26379-26381 \
+    --entrypoint start-cluster.sh \
+    redis:alpine
+```
+
+The package provides a [Compose file](docker-compose.yml) with the same options
+for running tests:
+
+```shell
+$ export CONTAINER_USER_ID="$(id -u):$(id -g)"
+$ docker-compose up -d cluster
+$ docker-compose run --rm tests [--testsuite ...]
+```
+
+Developers can also customize the Compose file by copying *docker-compose.yml*
+to *docker-compose.override.yml*.
+
 License
 -------
 
@@ -986,6 +1049,7 @@ Sentinel Documentation][sentinel].
 [s-env-config-examples]: #environment-based-configuration-examples
 [s-facade]: #executing-redis-commands-redissentinel-facade
 [s-hybrid-config]: #hybrid-configuration
+[s-integration-tests]: #integration-tests
 [s-multi-sentinel-example]: #multi-sentinel-connection-configuration
 [s-multi-service-example]: #multi-service-connection-configuration
 [s-multiple-hosts]: #specifying-multiple-hosts

docker-compose.yml

@@ -0,0 +1,28 @@
+version: "3"
+
+services:
+
+  cluster:
+    image: redis:alpine
+    entrypoint: ./start-cluster.sh
+    working_dir: /project
+    user: "${CONTAINER_USER_ID:-root:root}"
+    environment:
+      BIND_ADDRESS: "0.0.0.0"
+      SENTINEL_PORTS: "26379-26381"
+      REDIS_GROUP_1: "service1 6379-6381"
+      REDIS_GROUP_2: "service2 6382-6384"
+      LOGGING: "yes"
+    ports:
+      - "6379-6384:6379-6384"
+      - "26379-26381:26379-26381"
+    volumes:
+      - ./:/project
+
+  tests:
+    image: phpunit/phpunit:latest
+    entrypoint: vendor/bin/phpunit --colors=always
+    network_mode: host
+    user: "${CONTAINER_USER_ID:-root:root}"
+    volumes:
+      - ./:/app

phpunit.xml.dist

@@ -12,8 +12,11 @@
     stopOnFailure="false">
 
     <testsuites>
-        <testsuite name="Example">
-            <directory>tests</directory>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/Integration</directory>
         </testsuite>
     </testsuites>
 
@@ -23,11 +26,23 @@
         </whitelist>
     </filter>
 
+    <php>
+        <!-- Integration test configuration: -->
+        <const name="TEST_REDIS_SENTINEL_HOST"
+            value="127.0.0.1:26379,127.0.0.1:26380,127.0.0.1:26381"/>
+        <const name="TEST_REDIS_SENTINEL_SERVICE" value="service1"/>
+        <const name="TEST_REDIS_DATABASE" value="15"/>
+        <const name="TEST_MAX_CONNECTION_TIMEOUT" value="5.0"/>
+        <const name="TEST_MIN_CONNECTION_TIMEOUT" value="0.1"/>
+    </php>
+
+    <!--
     <logging>
         <log type="tap" target="build/report.tap"/>
         <log type="junit" target="build/report.junit.xml"/>
         <log type="coverage-html" target="build/coverage" charset="UTF-8" yui="true" highlight="true"/>
         <log type="coverage-text" target="build/coverage.txt"/>
         <log type="coverage-clover" target="build/clover.xml"/>
     </logging>
+    -->
 </phpunit>