Google Git
Sign in
apache / qpid-site / 3ef7d309765c479480533c6989ce2cd966b1d804 / . / content / releases / qpid-interop-test-0.1.0 / users-guide.html
blob: 5e6f8c43c482f12a0938470c50ec00c27bc51b8d [file] [log] [blame]
<!DOCTYPE html>
<!--
-
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>Qpid Interoperability Test Users Guide - Apache Qpid&#8482;</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
<link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
<script type="text/javascript">var _deferredFunctions = [];</script>
<script type="text/javascript" src="/deferred.js" defer="defer"></script>
<!--[if lte IE 8]>
<link rel="stylesheet" href="/ie.css" type="text/css"/>
<script type="text/javascript" src="/html5shiv.js"></script>
<![endif]-->
<!-- Redirects for `go get` and godoc.org -->
<meta name="go-import"
content="qpid.apache.org git https://git-wip-us.apache.org/repos/asf/qpid-proton.git"/>
<meta name="go-source"
content="qpid.apache.org
https://github.com/apache/qpid-proton/blob/go1/README.md
https://github.com/apache/qpid-proton/tree/go1{/dir}
https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
</head>
<body>
<div id="-content">
<div id="-top" class="panel">
<a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>
<a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>
<ul id="-global-navigation">
<li><a id="-logotype" href="/index.html">Apache Qpid<sup>&#8482;</sup></a></li>
<li><a href="/documentation.html">Documentation</a></li>
<li><a href="/download.html">Download</a></li>
<li><a href="/discussion.html">Discussion</a></li>
</ul>
</div>
<div id="-menu" class="panel" style="display: none;">
<div class="flex">
<section>
<h3>Project</h3>
<ul>
<li><a href="/overview.html">Overview</a></li>
<li><a href="/components/index.html">Components</a></li>
<li><a href="/releases/index.html">Releases</a></li>
</ul>
</section>
<section>
<h3>Messaging APIs</h3>
<ul>
<li><a href="/proton/index.html">Qpid Proton</a></li>
<li><a href="/components/jms/index.html">Qpid JMS</a></li>
<li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
</ul>
</section>
<section>
<h3>Servers and tools</h3>
<ul>
<li><a href="/components/broker-j/index.html">Broker-J</a></li>
<li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
<li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
</ul>
</section>
<section>
<h3>Resources</h3>
<ul>
<li><a href="/dashboard.html">Dashboard</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
<li><a href="/resources.html">More resources</a></li>
</ul>
</section>
</div>
</div>
<div id="-search" class="panel" style="display: none;">
<form action="http://www.google.com/search" method="get">
<input type="hidden" name="sitesearch" value="qpid.apache.org"/>
<input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
<button type="submit">Search</button>
<a href="/search.html">More ways to search</a>
</form>
</div>
<div id="-middle" class="panel">
<ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/releases/index.html">Releases</a></li><li><a href="/releases/qpid-interop-test-0.1.0/index.html">Qpid Interop Test 0.1.0</a></li><li>Qpid Interoperability Test Users Guide</li></ul>
<div id="-middle-content">
<div class="quoteblock">
<div class="title">Apache License</div>
<div class="content">
<div class="paragraph"><p>Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at</p></div>
<div class="paragraph"><p><a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a></p></div>
<div class="paragraph"><p>Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.</p></div>
</div>
<div class="attribution">
</div></div>
<h1 id="_qpid_interoperability_test_users_guide">Qpid Interoperability Test Users Guide</h1>
<div class="sect1">
<h2 id="_1_introduction">1. Introduction</h2>
<div class="sectionbody">
<div class="paragraph"><p>qpid-interop-test is an AMQP client interoperability test suite. It tests
various aspects of the AMQP protocol and/or test client features against
each other to ensure that they can interoperate.</p></div>
<div class="paragraph"><p>The test suite consists of tests and shims. Each test has a set of test-cases
which make up the test. Each test case will pass or fail a specific feature
or piece of functionality under test.</p></div>
<div class="paragraph"><p>Each test has a set of shims, which are small and specific clients which
send and receive messages, and is written using one of the client libraries
under test. For example, the amqp_types test has shims for the following
clients:
* AmqpNetLite
* ProtonCpp
* ProtonPython
* RheaJS</p></div>
<div class="paragraph"><p>To obtain both self- and interoperability testing, each test program will
run each shim against every other shim in the role of both sender and
receiver. For the amqp-type-test example above, this will result in the
following combinations of shims being used:</p></div>
<div class="tableblock">
<table rules="all"
width="30%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="10%" />
<col width="45%" />
<col width="45%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table"><strong>Sender shim</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>Receiver shim</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">1</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">2</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">3</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">4</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">5</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">6</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">7</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">8</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">9</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">10</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">11</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">12</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">13</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
<td align="left" valign="top"><p class="table">AmqpNetLite</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">14</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
<td align="left" valign="top"><p class="table">ProtonCpp</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">15</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
<td align="left" valign="top"><p class="table">ProtonPython</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">16</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
<td align="left" valign="top"><p class="table">RheaJS</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>so that for each test case, 16 individual tests are run. The test program
will by default run all the available shims against each other in this way,
but it is possible to control which shims are used using the --include-shim
or --exclude-shim arguments (see below).</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_2_obtaining">2. Obtaining</h2>
<div class="sectionbody">
<div class="paragraph"><p>qpid-interop-test is an Apache Qpid project.</p></div>
<div class="paragraph"><p>Web page: xxx</p></div>
<div class="paragraph"><p>Download soruce: xxx</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_3_building">3. Building</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_a_install_dependencies">a. Install dependencies:</h3>
<div class="ulist"><ul>
<li>
<p>
Build tools: git, gcc, cmake
</p>
</li>
<li>
<p>
Qpid Proton: qpid-proton-c-devel
</p>
</li>
</ul></div>
</div>
<div class="sect2">
<h3 id="_b_decide_on_local_vs_system_install">b. Decide on local vs system install</h3>
<div class="sect3">
<h4 id="_local_install">Local install:</h4>
<div class="paragraph"><p>Installs all of the Proton and QIT bits in a local directory. This is
useful for limited testing where you don&#8217;t want to have these files
in your system directories. Also, if you don&#8217;t have root privileges, then
this is the only way to install. The drawback is that you may need to
adjust some environment settings (<code>PATH</code>, <code>PYTHONPATH</code>, <code>LD_LIBRARY_PATH</code>) so
that the test will run.</p></div>
</div>
<div class="sect3">
<h4 id="_system_install">System install:</h4>
<div class="paragraph"><p>Installs the files into traditional system locations. This type of install
requires root privileges. As the files are located in expected locations, no
environment settings need be made.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_c_build_qpid_proton">c. Build qpid-proton</h3>
<div class="paragraph"><p><strong>System install:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><code> $ cd qpid-proton
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install</code></pre>
</div></div>
<div class="paragraph"><p><strong>Local install:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><code> $ cd qpid-proton
$ mkdir build
$ cd build
$ cmake ..
$ make install</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_d_build_qpid_interop_test">d. Build qpid-interop-test</h3>
<div class="paragraph"><p><strong>System install:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><code> $ cd qpid-interop-test
$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install</code></pre>
</div></div>
<div class="paragraph"><p><strong>Local install:</strong></p></div>
<div class="listingblock">
<div class="content">
<pre><code> $ cd qpid-interop-test
$ mkdir build
$ cd build
$ cmake ..
$ make install</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_4_running">4. Running</h2>
<div class="sectionbody">
<div class="paragraph"><p>The tests assume a broker is available and running. The assumed default is at
<code>localhost:5672</code>. For other broker location(s), use the <code>--sender</code> and <code>--receiver</code>
arguments to specify where the clients should interact, see below.</p></div>
<div class="paragraph"><p>The tests do not start or stop brokers.</p></div>
<div class="paragraph"><p>There are several tests in the test suite:</p></div>
<div class="ulist"><ul>
<li>
<p>
<strong>amqp_types_test.py</strong> - Tests all of the AMQP primitive types. This primarily tests
the encoding and decoding of AMQP types.
</p>
</li>
<li>
<p>
<strong>amqp_large_content_test.py</strong> - Tests large messages of various types. Messages sizes
are 1MB, 10MB, 100MB. Compound types (lists, maps, etc) send elements of various
sizes so that the total payload is the target size.
</p>
</li>
<li>
<p>
<strong>jms_messages_test.py</strong> - Tests JMS message types (as implemented by Qpid-jms over AMQP)
from all the Qpid clients (including non-jms clients)
</p>
</li>
<li>
<p>
<strong>jms_hdrs_props_test.py</strong> - Tests various combinations of JMS headers and properties
are correctly sent and received by the various clients.
</p>
</li>
</ul></div>
<div class="paragraph"><p>Each test is executed directly.</p></div>
<div class="sect2">
<h3 id="_command_line_arguments">Command-line arguments</h3>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 1. Common to all tests</caption>
<col width="20%" />
<col width="80%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><code>--help</code></p></td>
<td align="left" valign="top"><p class="table">Print help. This is useful for seeing the available argument options and
defaults for some arguments.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--sender</code></p></td>
<td align="left" valign="top"><p class="table">Node to which test suite will send messages.
Format: <code>ip-address:port</code>
Default: <code>localhost:5672</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--receiver</code></p></td>
<td align="left" valign="top"><p class="table">Node from which test suite will receive messages.
Format: <code>ip-address:port</code>
Default: <code>localhost:5672</code></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--no-skip</code></p></td>
<td align="left" valign="top"><p class="table">Do not skip tests that are excluded by default for reasons of a known bug.
Warning: some tests may lock up of freeze rather than fail.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--broker-type</code></p></td>
<td align="left" valign="top"><p class="table">Specify the broker manually, which eliminates the test connection made
to the broker to determine its identity through connection properties. If
"None" is specified, then Artemis broker will be assumed, but this will
change in the future when Artemis fixes the connection properties issue.
Format: For our current brokers: one of: "ActiveMQ", "qpid-cpp",
"qpid-dispatch-router". Artemis does not currently pass its name
in connection properties, and is equivalent to "None".</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--include-shim</code></p></td>
<td align="left" valign="top"><p class="table">Name of shim to include. Cannot be used together with <code>--exclude-shim</code>. May
be used multiple times to include more than one shim.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--exclude-shim</code></p></td>
<td align="left" valign="top"><p class="table">Name of shim to exclude. Cannot be used together with <code>--include-shim</code>. May
be used multiple times to exclude more that one shim.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 2. amqp-types-test</caption>
<col width="20%" />
<col width="80%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><code>--include-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of AMQP type to include. Cannot be used together with <code>--exclude-type</code>.
May be used multiple times to include more than one type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--exclude-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of AMQP type to exclude. Cannot be used together with <code>--include-type</code>.
May be used multiple times to exclude more than one type.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 3. amqp-large-content-test</caption>
<col width="100%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table">No other parameters. There is currently no way to select/limit the message size, but there
an issue open to address this limitation.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 4. jms-messages-test</caption>
<col width="20%" />
<col width="80%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><code>--include-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of JMS message type to include. Cannot be used together with
<code>--exclude-type</code>. May be used multiple times to include more than one type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--exclude-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of JMS message type to exclude. Cannot be used together with
<code>--include-type</code>. May be used multiple times to exclude more than one type.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Table 5. jms-hdrs-props-test</caption>
<col width="20%" />
<col width="80%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><code>--include-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of Java property type to include. Cannot be used together with
<code>--exclude-type</code>. May be used multiple times to include more than one type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><code>--exclude-type</code></p></td>
<td align="left" valign="top"><p class="table">Name of Java property type to exclude. Cannot be used together with
<code>--include-type</code>. May be used multiple times to exclude more than one type.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>There is currently no way to control/limit the JMS header types in this test, but there is
an issue open to address this limitation.</p></div>
<div class="sect3">
<h4 id="_examples">Examples:</h4>
<div class="paragraph"><p>To limit amqp_types_test to boolean type only:
<code>$ amqp_types_test --include-type boolean</code></p></div>
<div class="paragraph"><p>To limit amqp_types_test to Qpid-cpp and Proton-python shims only:
<code>$ amqp_types_test --include-shim ProtonCpp --include-shim ProtonPython</code></p></div>
<div class="paragraph"><p>To test against a pair of Dispatch Routers and a broker running on the local machine
as follows (first set up the brokers and routers):</p></div>
<div class="listingblock">
<div class="content">
<pre><code>+----------+ 9001 +----------+ 5672 +--------+
| sender |---------&gt;| dispatch |--------&gt;| |
| shim | | router 1 | | |
+----------+ +----------+ | |
| broker |
+----------+ 9002 +----------+ 5672 | |
| receiver |&lt;---------| dispatch |&lt;--------| |
| shim | | router 2 | | |
+----------+ +----------+ +--------+</code></pre>
</div></div>
<div class="paragraph"><p><code>$ amqp_types_test --sender localhost:9001 --receiver localhost:9002</code></p></div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_5_output">5. Output</h2>
<div class="sectionbody">
<div class="paragraph"><p>All the tests will list each test as it runs and whether it passes or fails.
If a test fails, then the details of the failure will be printed at the end of
the test.</p></div>
<div class="listingblock">
<div class="content">
<pre><code> ======================================================================
FAIL: test.B.MESSAGE.JMS_TYPE_HEADER:string+JMS_REPLYTO_HEADER:topic.QpidJms-&gt;ProtonCpp (__main__.PartB_JmsHeaderCombination_TestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
File "./install/lib/python2.7/site-packages/qpid_interop_test/jms_hdrs_props_test.py", line 422, in inner_test_method
receive_shim)
File "./install/lib/python2.7/site-packages/qpid_interop_test/jms_hdrs_props_test.py", line 313, in run_test
self.fail(str(receive_obj))
AssertionError: JmsReceiver error: Unexpected JMS message header: JMS_PRIORITY: Expected default priority (4), found priority 0</code></pre>
</div></div>
<div class="paragraph"><p>Currently, the tests do not produce log files.</p></div>
</div>
</div>
<hr/>
<ul id="-apache-navigation">
<li><a href="http://www.apache.org/">Apache</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks!</a></li>
<li><a href="/security.html">Security</a></li>
<li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
</ul>
<p id="-legal">
Apache Qpid, Messaging built on AMQP; Copyright &#169; 2015
The Apache Software Foundation; Licensed under
the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
Proton, Apache, the Apache feather logo, and the Apache Qpid
project logo are trademarks of The Apache Software
Foundation; All other marks mentioned may be trademarks or
registered trademarks of their respective owners
</p>
</div>
</div>
</div>
</body>
</html>