You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kp...@apache.org on 2021/10/18 15:02:36 UTC
[qpid-interop-test] branch main updated: Modified CMakeLists.txt to
install QIT docs, updates to docs
This is an automated email from the ASF dual-hosted git repository.
kpvdr pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/qpid-interop-test.git
The following commit(s) were added to refs/heads/main by this push:
new 7c313cd Modified CMakeLists.txt to install QIT docs, updates to docs
7c313cd is described below
commit 7c313cd4b39a38e94528f964821f483684c101d3
Author: Kim van der Riet <ki...@apache.org>
AuthorDate: Mon Oct 18 11:02:27 2021 -0400
Modified CMakeLists.txt to install QIT docs, updates to docs
---
CMakeLists.txt | 3 ++
QUICKSTART.md | 2 +-
docs/CMakeLists.txt | 11 ++++-
docs/USERGUIDE.md | 123 +++++++++++++++++++++++++++++++++-------------------
4 files changed, 92 insertions(+), 47 deletions(-)
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 55297b1..a7dcd26 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -121,3 +121,6 @@ install (DIRECTORY src/python/qpid_interop_test
install (FILES build/bin/qpid-interop-test
DESTINATION ${CMAKE_INSTALL_PREFIX}/bin/
PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ WORLD_READ WORLD_EXECUTE)
+install (FILES LICENSE NOTICE QUICKSTART.md README.md
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/qpid-interop-test
+ PERMISSIONS OWNER_WRITE OWNER_READ GROUP_READ WORLD_READ)
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 47a380a..dd38c5f 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -19,7 +19,7 @@ under the License.
-->
-# USER GUIDE
+# QUICK START
## 1. Overview
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 822ff26..938323a 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -21,4 +21,13 @@ project (qpid-interop-test-doc)
cmake_minimum_required(VERSION 3.16.3 FATAL_ERROR)
-execute_process(COMMAND asciidoc -d book ${CMAKE_CURRENT_SOURCE_DIR}/users-guide.txt)
+# Now using GitHub-flavored markdown file USERGUIDE.md
+# execute_process(COMMAND asciidoc -d book ${CMAKE_CURRENT_SOURCE_DIR}/users-guide.txt)
+
+install (FILES qpid-interop-test-devel-overview.txt
+ RELEASE.txt
+ Shim_HOWTO.txt
+ Test_HOWTO.txt
+ USERGUIDE.md
+ DESTINATION ${CMAKE_INSTALL_PREFIX}/share/qpid-interop-test/docs
+ PERMISSIONS OWNER_WRITE OWNER_READ GROUP_READ WORLD_READ)
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 9df07cd..0587e2e 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -55,7 +55,18 @@ or using containers:
* podman run
* Run test in container
-## 3. Build Prerequisites
+## 3. Obtaining
+
+Qpid Interop Test is an Apache Qpid project.
+
+Web page: https://qpid.apache.org/components/interop-test/index.html
+
+Download soruce: https://qpid.apache.org/download.html
+
+Git: https://github.com/apache/qpid-interop-test.git
+
+
+## 4. Build Prerequisites
Qpid Interop Test should build and run on any reasonably recent distribution
of Linux for which the prerequisite packages listed below are available.
@@ -115,7 +126,7 @@ known. This is achieved by using the `--sender <addr[:port]>` and
`--receiver <addr[:port]>` options with each test.
-### 3.1 Fedora 34
+### 4.1 Fedora 34
Make sure the following packages are installed:
```bash
@@ -137,7 +148,7 @@ To install Qpid Dispatch Router as a broker:
sudo dnf install -y qpid-dispatch-router
```
-### 3.2 CentOS 8
+### 4.2 CentOS 8
Install EPEL repository, then make sure the following packages are installed:
```bash
@@ -178,7 +189,7 @@ To install Qpid Dispatch Router as a broker:
sudo dnf install -y qpid-dispatch-router
```
-### 3.3 Ubuntu Focal
+### 4.3 Ubuntu Focal
Make sure the following packages are installed:
```bash
@@ -211,7 +222,7 @@ To install Qpid Dispatch Router as a broker:
sudo apt-get install -y qdrouterd
```
-## 4. Install Source and Build
+## 5. Install Source and Build
This section describes building from source. To use containers, see [5. Containers] below.
To use the optional javascript shims, install Rhea source. This should be done before cmake
@@ -240,14 +251,14 @@ cmake in the above sequence as follows:
cmake --CMAKE_INSTALL_PREFIX=<abs-path-to-location> ..
```
-## 5. Run the Tests
+## 6. Run the Tests
The Qpid Interop Test entry point is `/usr/local/bin/qpid-interop-test`
by default, or if an alternate location was specified,
`<CMAKE_INSTALL_PREFIX>/usr/local/bin/qpid-interop-test`. If an alternate location
was used, make sure that this directory is in the path.
-### 5.1 Start a Broker
+### 6.1 Start a Broker
Make sure an AMQP broker is running. Typically, the broker is run locally, but
it may also be remote, provided it is accessible on the network.
@@ -257,7 +268,7 @@ If you are using the dispatch router as a local broker, start it as follows:
sudo /sbin/qdrouterd --daemon
```
-### 5.2 Run the tests (local broker)
+### 6.2 Run the tests (local broker)
Run the tests by executing `qpid-interop-test test-name [test-options...]`.
@@ -289,7 +300,7 @@ For help on all tests: run:
qpid-interop-test all --help
```
-### 5.3 Output
+### 6.3 Output
Tests will show each test case, followed by `ok` if the test passes or `FAIL` if it fails.
When all tests have completed, all failed tests will be listed with a failure message and
@@ -304,11 +315,23 @@ test_list_decimal32_ProtonCpp->ProtonCpp (__main__.ListTestCase) ... skipped 'BR
Each skipped tests references a JIRA issue number and which will usually refer to the
[Apache Qpid JIRA](https://issues.apache.org/jira).
-### 5.4 Available Tests and their Options
-The following tests are available:
+### 6.4 Available Tests and their Options
+The following tests and shims are available:
+
+Test | Qpid Proton Python 3 | Qpid C++ | AmqpNetLite (.NET) | Rhea (Javascript) | Qpid JMS |
+-----|----------------------|----------|--------------------|-------------------|----------|
+`amqp-types-test` | Y | Y | Y | Y | |
+`amqp-complex-types-test` | Y | Y | | | |
+`amqp-large-content-test` | Y | Y | Y | | |
+`jms-messages-test` | Y | Y | | | Y |
+`jms-hdrs-props-test` | Y | Y | | | Y |
+
+1. Missing shims will be added in future releases.
+2. The Qpid JMS client is incompattible with the AMQP types tests. However, the other clients can format messages that will be accepted by the JMS client.
-#### 5.4.1 Common Options
+#### 6.4.1 Common Options
The following test options are common to all tests:
+
Option | Default | Description |
-------|---------|-------------|
--sender | 'localhost:5672' | IP address of node to which test suite will send messages. |
@@ -326,6 +349,7 @@ Option | Default | Description |
[^5]: Mutually exclusive
Currently, the following shims are supported:
+
Name | Description |
-----|-------------|
`AmqpNetLite` | .NET AmqpNetLite client |
@@ -336,20 +360,22 @@ Name | Description |
These options may be used when specifying `all` as the test name, as all the individual tests will accept them.
-#### 5.4.2 amqp-types-test
+#### 6.4.2 amqp-types-test
This test sends the simple AMQP types (ie types that are not container-like and do not include other AMQP types)
as an AMQP value payload (section 3.2.7 of the
[AMQP 1.0 specification](http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html). )
In addition to the common options described above, the following options are availbe to this test:
-Option | Default | Description |
--------|---------|-------------|
---include-type[^6] | | Name of AMQP type to include. See table of AMQP simple types below. May be used multiple times. |
---exclude-type[^6] | | Name of AMQP type to exclude. See table of AMQP simple types below. May be used multiple times. |
+
+Option | Description |
+-------|-------------|
+--include-type[^6] | Name of AMQP type to include. See table of AMQP simple types below. May be used multiple times. |
+--exclude-type[^6] | Name of AMQP type to exclude. See table of AMQP simple types below. May be used multiple times. |
[^6]: Mutually exclusive
Supported AMQP simple types are:
+
Type | AMQP Type Description |
-----|-----------------------|
`null` | Indicates an empty value. |
@@ -374,16 +400,17 @@ Type | AMQP Type Description |
`string` | A sequence of Unicode characters as defined by the Unicode V6.0.0 standard. |
`symbol` | Symbolic values from an application-defined constrained domain. |
-#### 5.4.3 amqp-complex-types-test
+#### 6.4.3 amqp-complex-types-test
This test sends the complex AMQP types (ie types that contain other AMQP types)
as an AMQP value payload (section 3.2.7 of the
[AMQP 1.0 specification](http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html). )
In addition to the common options described above, the following options are availbe to this test:
-Option | Default | Description |
--------|---------|-------------|
---include-type[^7] | | Name of AMQP type to include. See table of AMQP complex types below. May be used multiple times. |
---exclude-type[^7] | | Name of AMQP type to exclude. See table of AMQP complex types below. May be used multiple times. |
+
+Option | Description |
+-------|-------------|
+--include-type[^7] | Name of AMQP type to include. See table of AMQP complex types below. May be used multiple times. |
+--exclude-type[^7] | Name of AMQP type to exclude. See table of AMQP complex types below. May be used multiple times. |
--include-subtype[^8] | Name of AMQP subtype to include. See table of AMQP simple types above. May be used multiple times. |
--exclude-subtype[^8] | Name of AMQP subtype to exclude. See table of AMQP simple types above. May be used multiple times. |
@@ -391,13 +418,14 @@ Option | Default | Description |
[^8]: Mutually exclusive
Supported AMQP complex types are:
+
Type | AMQP Type Description |
-----|-----------------------|
`array` | A sequence of values of a single AMQP type. |
`list` | A sequence of polymorphic AMQP values. |
`map` | A polymorphic mapping from distinct keys to AMQP values. |
-#### 5.4.4 amqp-large-content-test
+#### 6.4.4 amqp-large-content-test
This test is designed to stress clients and brokers with large messages
as an AMQP value payload (section 3.2.7 of the
[AMQP 1.0 specification](http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-overview-v1.0-os.html).
@@ -409,10 +437,11 @@ seconds per test. If this needs to be changed, use the `--timeout`
option.
In addition to the common options described above, the following options are availbe to this test:
-Option | Default | Description |
--------|---------|-------------|
---include-type[^9] | | Name of AMQP type to include. See list of AMQP extensible types below. May be used multiple times. |
---exclude-type[^9] | | Name of AMQP type to exclude. See list of AMQP extensible types below. May be used multiple times. |
+
+Option | Description |
+-------|-------------|
+--include-type[^9] | Name of AMQP type to include. See list of AMQP extensible types below. May be used multiple times. |
+--exclude-type[^9] | Name of AMQP type to exclude. See list of AMQP extensible types below. May be used multiple times. |
[^9]: Mutually exclusive
@@ -421,21 +450,23 @@ and `map` (see above for descriptions). Currently, type `array` is not
supported, but will be added in a future release.
The message payload sizes are fixed at 1MB and 10MB. Currently there is no
-way to select payload size from the command-line. This will be added in a
-future release.
+way to select or set payload size from the command-line. This will be added
+in a future release.
-#### 5.4.5 jms-messages-test
+#### 6.4.5 jms-messages-test
This test sends each of the JMS-defined message types.
In addition to the common options described above, the following options are availbe to this test:
-Option | Default | Description |
--------|---------|-------------|
---include-type[^10] | | Name of JMS message type to include. See list of JMS message types below. May be used multiple times. |
---exclude-type[^10] | | Name of JMS message type to exclude. See list of JMS message types below. May be used multiple times. |
+
+Option | Description |
+-------|-------------|
+--include-type[^10] | Name of JMS message type to include. See list of JMS message types below. May be used multiple times. |
+--exclude-type[^10] | Name of JMS message type to exclude. See list of JMS message types below. May be used multiple times. |
[^10]: Mutually exclusive
The supported JMS message types are:
+
Type | JMS Message Type Description |
-----|------------------------------|
`JMS_MESSAGE_TYPE` | Base message type, usually without a message payload, but may contain headers and properties. |
@@ -448,22 +479,24 @@ The JMS Object message type is not currently supported for interoperability
testing as it is depenedent on Java to serialize objects, and which non-Java
clients cannot easily support.
-#### 5.4.6 jms-hdrs-props-test
+#### 6.4.6 jms-hdrs-props-test
This test sends combinations of the JMS-defined user-settable message headers and
user-defined message properties to a JMS message.
In addition to the common options described above, the following options are availbe to this test:
-Option | Default | Description |
--------|---------|-------------|
-`--include-hdr`[^11] | | Name of JMS header to include. See table of supported JMS headers below. |
-`--exclude-hdr`[^11] | | Name of JMS header to exclude or `ALL` to exclude all header tests. See table of supported JMS headers below. |
-`--include-prop`[^12] | | Name of JMS property type to include. See list of JMS property types below. |
-`--exclude-prop`[^12] | | Name of JMS property type to exclude or `ALL` to exclude all property types. |
+
+Option | Description |
+-------|-------------|
+`--include-hdr`[^11] | Name of JMS header to include. See table of supported JMS headers below. |
+`--exclude-hdr`[^11] | Name of JMS header to exclude or `ALL` to exclude all header tests. See table of supported JMS headers below. |
+`--include-prop`[^12] | Name of JMS property type to include. See list of JMS property types below. |
+`--exclude-prop`[^12] | Name of JMS property type to exclude or `ALL` to exclude all property types. |
[^11]: Mutually exclusive
[^12]: Mutually exclusive
Supported JMS headers are:
+
Type | JMS Header Description |
-----|------------------------------|
`JMS_CORRELATIONID_HEADER` | A string used for correlating or grouping messages. Defined and used by applications. |
@@ -476,7 +509,7 @@ be set through the client API.
Supported JMS property types are Java types `boolean`, `byte`, `double`, `float`,
`int`, `long`, `short` and `string`.
-### 5.5 Using a remote broker
+### 6.5 Using a remote broker
The test shims will by default connect to `localhost:5672`. However, arbitrary
IP addresses and ports may be specified by using the `--sender <addr[:port]>` and
@@ -494,14 +527,14 @@ listining on port 35672:
qpid-interop-test jms-messages-test --sender 192.168.25.65:35672 --receiver 192.168.25.65:35672
```
-## 6. Containers
+## 7. Containers
The Qpid Interop Test root directory contains a `containers` directory which
contains Dockerfiles for Fedora 34, CentOS 8 and Ubuntu Focal. Building the
Dockerfile will install all prerequisites, install the source and build/install
Qpid Interop Test. The Qpid Dispatch Router is also installed, but is not running.
-### 6.1 Build the image
+### 7.1 Build the image
```bash
podman build -f <dockerfile> -t <image-name>
@@ -514,7 +547,7 @@ podman build -f containers/Dockerfile.f34 -t fedora34.qit
podman images
```
-### 6.2 Run QIT from a Container
+### 7.2 Run QIT from a Container
Once the image is built, it may be run as follows:
```bash
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org