Skip to content

Commit e2f5625

Browse files
acogoluegnesacogoluegnes
committed
Simplify documentation to run tests
Assume an external RabbitMQ instance, instead of the one launched by the test suite, which is built from source. This makes the contribution much easier.
1 parent 43af65d commit e2f5625

File tree

2 files changed

+39
-132
lines changed

2 files changed

+39
-132
lines changed

‎Makefile

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ MVN_FLAGS += -Ddeps.dir="$(abspath $(DEPS_DIR))"
1616
all: deps
1717
$(MVN) $(MVN_FLAGS) compile
1818

19-
deps: $(DEPS_DIR)/rabbit $(DEPS_DIR)/rabbitmq_ct_helpers
19+
deps: $(DEPS_DIR)/rabbitmq_codegen
2020
@:
2121

2222
dist: clean
@@ -29,6 +29,9 @@ $(DEPS_DIR)/rabbit:
2929
$(DEPS_DIR)/rabbitmq_ct_helpers:
3030
git clone https://github.com/rabbitmq/rabbitmq-ct-helpers.git "$@"
3131

32+
$(DEPS_DIR)/rabbitmq_codegen:
33+
git clone https://github.com/rabbitmq/rabbitmq-codegen.git "$@"
34+
3235
tests: deps
3336
$(MVN) $(MVN_FLAGS) verify
3437

‎RUNNING_TESTS.md

Lines changed: 35 additions & 131 deletions
Original file line numberDiff line numberDiff line change
@@ -18,24 +18,39 @@ TLS port, `5671`. Multi-node tests expect a second cluster node listening on `lo
1818

1919
Connection recovery tests need `rabbitmqctl` to control the running nodes.
2020

21-
`./mvnw verify` will start those nodes with the appropriate configuration.
21+
Note running all those tests requires a fairly complicated setup and is overkill
22+
for most contributions. This is why this document will cover how to run the most
23+
important subset of the test suite. Continuous integration jobs run the whole test
24+
suite anyway.
2225

2326
## Running Tests
2427

25-
To easily fulfill all those requirements, use `make deps` to
26-
fetch the dependencies in the `deps` directory.
28+
Use `make deps` to fetch the dependencies in the `deps` directory:
2729

28-
Then run Maven with the `deps.dir` property set like this:
30+
```
31+
make deps
32+
```
33+
34+
To run a subset of the test suite (do not forget to start a local RabbitMQ node):
2935

3036
```
31-
./mvnw -Ddeps.dir=$(pwd)/deps verify
37+
./mvnw verify -P '!setup-test-cluster' \
38+
-Dtest-broker.A.nodename=rabbit@$(hostname) \
39+
-Drabbitmqctl.bin=/path/to/rabbitmqctl \
40+
-Dit.test=ClientTests,FunctionalTests,ServerTests
3241
```
3342

43+
The test suite subset does not include TLS tests, which is fine for most
44+
contributions and makes the setup easier.
45+
3446
The previous command launches tests against the blocking IO connector.
3547
To run the tests against the NIO connector, add `-P use-nio` to the command line:
3648

3749
```
38-
./mvnw -Ddeps.dir=$(pwd)/deps verify -P use-nio
50+
./mvnw verify -P '!setup-test-cluster',use-nio \
51+
-Dtest-broker.A.nodename=rabbit@$(hostname) \
52+
-Drabbitmqctl.bin=/path/to/rabbitmqctl \
53+
-Dit.test=ClientTests,FunctionalTests,ServerTests
3954
```
4055

4156
For details on running specific tests, see below.
@@ -48,140 +63,29 @@ top-level directory of the source tree:
4863

4964
* To run the client unit tests:
5065

51-
```
52-
./mvnw -Ddeps.dir=$(pwd)/deps verify -Dit.test=ClientTests
53-
```
54-
55-
* To run the functional tests:
56-
57-
```
58-
./mvnw -Ddeps.dir=$(pwd)/deps verify -Dit.test=FunctionalTests
59-
```
60-
61-
* To run a single test:
62-
6366
```
64-
./mvnw -Ddeps.dir=$(pwd)/deps verify -Dit.test=DeadLetterExchange
67+
./mvnw verify -P '!setup-test-cluster',use-nio \
68+
-Dtest-broker.A.nodename=rabbit@$(hostname) \
69+
-Drabbitmqctl.bin=/path/to/rabbitmqctl \
70+
-Dit.test=ClientTests
6571
```
6672

67-
When running from the repository cloned as part of the [RabbitMQ public umbrella](https://github.com/rabbitmq/rabbitmq-public-umbrella),
68-
the `deps.dir` property path may have to change, e.g.
73+
* To run the functional tests:
6974

7075
```
71-
./mvnw -Ddeps.dir=$(pwd)/.. verify -Dit.test=ConnectionRecovery
76+
./mvnw verify -P '!setup-test-cluster',use-nio \
77+
-Dtest-broker.A.nodename=rabbit@$(hostname) \
78+
-Drabbitmqctl.bin=/path/to/rabbitmqctl \
79+
-Dit.test=FunctionalTests
7280
```
7381

74-
For example, to run the client tests:
82+
* To run a single test:
7583

7684
```
77-
rabbitmq-java-client$ ./mvnw -Ddeps.dir=$(pwd)/deps verify -Dit.test=ClientTests
78-
[INFO] Scanning for projects...
79-
[INFO]
80-
[INFO] ------------------------------------------------------------------------
81-
[INFO] Building RabbitMQ Java Client 5.3.0-SNAPSHOT
82-
[INFO] ------------------------------------------------------------------------
83-
[INFO]
84-
[INFO] --- groovy-maven-plugin:2.0:execute (generate-amqp-sources) @ amqp-client ---
85-
[INFO]
86-
[INFO] --- build-helper-maven-plugin:1.12:add-source (add-generated-sources-dir) @ amqp-client ---
87-
[INFO] Source directory: .../rabbitmq-java-client/target/generated-sources/src/main/java added.
88-
[INFO]
89-
[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ amqp-client ---
90-
[INFO] Using 'UTF-8' encoding to copy filtered resources.
91-
[INFO] Copying 2 resources
92-
[INFO]
93-
[INFO] --- maven-compiler-plugin:3.6.1:compile (default-compile) @ amqp-client ---
94-
[INFO] Nothing to compile - all classes are up to date
95-
[INFO]
96-
[INFO] --- maven-bundle-plugin:3.2.0:manifest (bundle-manifest) @ amqp-client ---
97-
[INFO]
98-
[INFO] --- groovy-maven-plugin:2.0:execute (remove-old-test-keystores) @ amqp-client ---
99-
[INFO]
100-
[INFO] --- groovy-maven-plugin:2.0:execute (query-test-tls-certs-dir) @ amqp-client ---
101-
[INFO]
102-
[INFO] --- keytool-maven-plugin:1.5:importCertificate (generate-test-ca-keystore) @ amqp-client ---
103-
[WARNING] Certificate was added to keystore
104-
[INFO]
105-
[INFO] --- keytool-maven-plugin:1.5:importCertificate (generate-test-empty-keystore) @ amqp-client ---
106-
[WARNING] Certificate was added to keystore
107-
[INFO]
108-
[INFO] --- keytool-maven-plugin:1.5:deleteAlias (generate-test-empty-keystore) @ amqp-client ---
109-
[INFO]
110-
[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ amqp-client ---
111-
[INFO] Using 'UTF-8' encoding to copy filtered resources.
112-
[INFO] Copying 5 resources
113-
[INFO]
114-
[INFO] --- maven-compiler-plugin:3.6.1:testCompile (default-testCompile) @ amqp-client ---
115-
[INFO] Nothing to compile - all classes are up to date
116-
[INFO]
117-
[INFO] --- maven-surefire-plugin:2.19.1:test (default-test) @ amqp-client ---
118-
[INFO] Tests are skipped.
119-
[INFO]
120-
[INFO] --- maven-jar-plugin:3.0.2:jar (default-jar) @ amqp-client ---
121-
[INFO] Building jar: .../rabbitmq-java-client/target/amqp-client-5.3.0-SNAPSHOT.jar
122-
[INFO]
123-
[INFO] >>> maven-source-plugin:3.0.1:jar (default) > generate-sources @ amqp-client >>>
124-
[INFO]
125-
[INFO] --- groovy-maven-plugin:2.0:execute (generate-amqp-sources) @ amqp-client ---
126-
[INFO]
127-
[INFO] --- build-helper-maven-plugin:1.12:add-source (add-generated-sources-dir) @ amqp-client ---
128-
[INFO] Source directory: .../rabbitmq-java-client/target/generated-sources/src/main/java added.
129-
[INFO]
130-
[INFO] <<< maven-source-plugin:3.0.1:jar (default) < generate-sources @ amqp-client <<<
131-
[INFO]
132-
[INFO]
133-
[INFO] --- maven-source-plugin:3.0.1:jar (default) @ amqp-client ---
134-
[INFO] Building jar: .../rabbitmq-java-client/target/amqp-client-5.3.0-SNAPSHOT-sources.jar
135-
[INFO]
136-
[INFO] --- groovy-maven-plugin:2.0:execute (start-test-broker-A) @ amqp-client ---
137-
[INFO]
138-
[INFO] --- groovy-maven-plugin:2.0:execute (start-test-broker-B) @ amqp-client ---
139-
[INFO]
140-
[INFO] --- groovy-maven-plugin:2.0:execute (create-test-cluster) @ amqp-client ---
141-
[INFO]
142-
[INFO] --- maven-failsafe-plugin:2.19.1:integration-test (integration-test) @ amqp-client ---
143-
144-
-------------------------------------------------------
145-
T E S T S
146-
-------------------------------------------------------
147-
Running com.rabbitmq.client.test.ClientTests
148-
Tests run: 121, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 58.869 sec - in com.rabbitmq.client.test.ClientTests
149-
150-
Results :
151-
152-
Tests run: 121, Failures: 0, Errors: 0, Skipped: 0
153-
154-
[INFO]
155-
[INFO] --- groovy-maven-plugin:2.0:execute (stop-test-broker-B) @ amqp-client ---
156-
[INFO]
157-
[INFO] --- groovy-maven-plugin:2.0:execute (stop-test-broker-A) @ amqp-client ---
158-
[INFO]
159-
[INFO] --- maven-failsafe-plugin:2.19.1:verify (verify) @ amqp-client ---
160-
[INFO] ------------------------------------------------------------------------
161-
[INFO] BUILD SUCCESS
162-
[INFO] ------------------------------------------------------------------------
163-
[INFO] Total time: 01:31 min
164-
[INFO] Finished at: 2018-04-25T11:33:54+02:00
165-
[INFO] Final Memory: 26M/336M
166-
[INFO] ------------------------------------------------------------------------
85+
./mvnw verify -P '!setup-test-cluster',use-nio \
86+
-Dtest-broker.A.nodename=rabbit@$(hostname) \
87+
-Drabbitmqctl.bin=/path/to/rabbitmqctl \
88+
-Dit.test=DeadLetterExchange
16789
```
16890

16991
Test reports can be found in `target/failsafe-reports`.
170-
171-
172-
## Running tests against an externally provided broker or cluster
173-
174-
By default, if the RabbitMQ broker sources are available, the testsuite
175-
starts automatically a cluster of two RabbitMQ nodes and runs the tests
176-
against it.
177-
178-
You can also provide your own broker or cluster. To disable the
179-
automatic test cluster setup, disable the `setup-test-cluster` Maven
180-
profile:
181-
182-
```
183-
mvn verify -P '!setup-test-cluster'
184-
```
185-
186-
Note that by doing so some tests will fail as they require `rabbitmqctl` to
187-
control the running nodes.

0 commit comments

Comments
 (0)