|
| 1 | +# Conventions Used in This Document |
| 2 | +Unless otherwise noted all commands, file and directory references are relative to the *source root* directory. |
| 3 | + |
| 4 | +## Terminology |
| 5 | + - modes: Collection of integration tests to be run |
| 6 | + - testconf: [JSON](https://tools.ietf.org/html/rfc8259) formatted configuration file. |
| 7 | + Example: [tests/testconf-example.json](./tests/testconf-example.json) for formatting. |
| 8 | + |
1 | 9 | Unit tests |
2 | 10 | ========== |
3 | | - |
4 | 11 | From top-level directory run: |
5 | 12 |
|
6 | | - $ tox |
| 13 | + $ ./tests/run.sh tox |
7 | 14 |
|
8 | 15 | **NOTE**: This requires `tox` ( please install with `pip install tox` ) and several supported versions of Python. |
9 | 16 |
|
10 | | -Integration tests |
11 | | -================= |
12 | | - |
13 | | -**NOTE**: Integration tests require an existing Kafka cluster and a `testconf.json` configuration file. Any value provided |
14 | | -in `testconf.json` prefixed with '$' will be treated as an environment variable and automatically resolved. |
15 | | - |
16 | | -At a minimum you must specify `bootstrap.servers` and `topic` within `testconf.json`. Please reference [tests/testconf-example.json](tests/testconf-example.json) for formatting. |
17 | | - |
18 | | -**WARNING**: These tests will create new topics and consumer groups. |
| 17 | +If tox is not installed: |
19 | 18 |
|
20 | | -To run all of the integration test `modes` uncomment the following line from `tox.ini` and provide the location to your `testconf.json` |
| 19 | + $ ./tests/run.sh unit |
21 | 20 |
|
22 | | - #python examples/integration_test.py --conf <testconf.json> |
23 | | - |
24 | | -You can also run the integration tests outside of `tox` by running this command from the source root directory |
25 | | - |
26 | | - python examples/integration_test.py --conf <testconf.json> |
27 | | - |
28 | | -To run individual integration test `modes` use the following syntax |
29 | | - |
30 | | - python examples/integration_test.py --<test mode> --conf <testconf.json> |
| 21 | +Integration tests |
| 22 | +================= |
31 | 23 |
|
32 | | -For example: |
| 24 | +### Requirements |
| 25 | + 1. docker-compose 3.0 + |
| 26 | + 2. docker-engine 1.13.0+ |
| 27 | + 3. **Optional:** tox (enables testing against multiple interpreter versions) |
33 | 28 |
|
34 | | - python examples/integration_test.py --producer --conf testconf.json |
| 29 | +### Cluster setup |
| 30 | +**Note** Manual cluster set up is not required when using ./tests/run.sh |
35 | 31 |
|
36 | | -To get a list of modes you can run the integration test manually with the `--help` flag |
| 32 | + $ ./tests/docker/bin/cluster_up.sh |
37 | 33 |
|
38 | | - python examples/integration_tests.py --help |
| 34 | +### Cluster teardown |
| 35 | +**Note** Manual cluster teardown is not required when using ./tests/run.sh |
39 | 36 |
|
| 37 | + $ ./tests/docker/bin/cluster_down.sh |
40 | 38 |
|
41 | | -Throttle Callback test |
42 | | -====================== |
43 | | -The throttle_cb integration test requires an additional step and as such is not included in the default test modes. |
44 | | -In order to execute the throttle_cb test you must first set a throttle for the client 'throttled_client' with the command below: |
| 39 | +### Configuration |
| 40 | +Tests are configured with a JSON configuration file referred to as `testconf.json` to be provided as the last argument upon test execution. |
45 | 41 |
|
46 | | - kafka-configs --zookeeper <zookeeper host>:<zookeeper port> \ |
47 | | - --alter --add-config 'request_percentage=01' \ |
48 | | - --entity-name throttled_client --entity-type clients |
| 42 | +Advanced users can reference the provided configuration file, [testconf.json](integration/testconf.json), if modification is required. |
| 43 | +Most developers however should use the defaults. |
49 | 44 |
|
50 | | -Once the throttle has been set you can proceed with the following command: |
| 45 | +### Running tests |
| 46 | +To run the entire test suite: |
51 | 47 |
|
52 | | - python examples/integration_test.py --throttle --conf testconf.json |
| 48 | +From the source root directory ... |
53 | 49 |
|
| 50 | +- With tox installed (will run against all supported interpreters) |
| 51 | + 1. Uncomment the following line from [tox.ini](../tox.ini) |
| 52 | + - ```#python tests/integration/integration_test.py``` |
| 53 | + 2. Execute the following script |
| 54 | + - ```$ ./tests/run.sh tox``` |
54 | 55 |
|
55 | | -To remove the throttle you can execute the following |
| 56 | +- Without tox (will run against current interpreter) |
| 57 | + - ```$ ./tests/run.sh all``` |
56 | 58 |
|
57 | | - kafka-configs --zookeeper <zookeeper host>:<zookeeper port> \ |
58 | | - --alter --delete-config 'request_percentage' \ |
59 | | - --entity-name throttled_client --entity-type clients |
| 59 | +To run just the unit tests |
60 | 60 |
|
| 61 | + $ ./tests/run.sh unit |
61 | 62 |
|
62 | | -HTTPS Schema Registry test |
63 | | -========================== |
| 63 | +To run a specific integration test `mode` or set of `modes` use the following syntax |
64 | 64 |
|
65 | | -HTTPS tests require access to a Schema Registry instance configured to with at least one HTTPS listener. |
| 65 | + $ ./tests/run.sh <test mode 1> <test mode 2>.. |
66 | 66 |
|
67 | | -For instructions on how to configure the Schema Registry please see the Confluent documentation: |
| 67 | +For example: |
68 | 68 |
|
69 | | -[Schema Registry documentation](https://docs.confluent.io/current/schema-registry/docs/security.html#configuring-the-rest-api-for-http-or-https) |
| 69 | + $ ./tests/run.sh --producer --consumer |
70 | 70 |
|
71 | | -If client authentication has been enabled you will need to provide both the client certificate, `schema.registry.ssl.certificate.location`, |
72 | | -and the client's private key, `schema.registry.ssl.key.location` |
| 71 | +To get a list of integration test `modes` simply supply the `help` option |
73 | 72 |
|
74 | | - python examples/integration_test.py --avro-https --conf testconf.json |
| 73 | + $ ./tests/run.sh --help |
0 commit comments