QIT Architecture

August 7, 2026 · View on GitHub

Overview

QIT 2.0 is a complete rewrite of the Qpid Interoperability Test suite with modern Python packaging, comprehensive AMQP type coverage, and extensible test orchestration.

Core Components

1. Test Orchestrator (`qit.core.orchestrator`)

Coordinates test execution across multiple client shims:

Generates test matrix (sender × receiver × type)
Manages shim invocation and result collection
Compares sent/received messages
Generates test reports

2. Shim Interface (`qit.core.shim`)

Defines the protocol for communication with native AMQP clients:

CLI-based: Each shim is an executable accepting standard arguments
JSON I/O: Messages are exchanged via JSON on stdin/stdout
Modes: Supports broker-based and direct peer-to-peer communication

Shim Contract:

# Send
shim send --broker URL --queue NAME --type TYPE --count N --data JSON

# Receive  
shim receive --broker URL --queue NAME --count N --timeout SEC

# Direct mode
shim send-direct --host HOST --port PORT --queue NAME --type TYPE --data JSON
shim receive-direct --port PORT --queue NAME --count N --timeout SEC

Output Format:

{
  "messages": [
    {"index": 0, "type": "uint", "value": 42},
    {"index": 1, "type": "uint", "value": 255}
  ],
  "stats": {"sent": 2, "duration_ms": 123}
}

3. Type System (`qit.types`)

Comprehensive AMQP 1.0 type definitions:

Primitive types: All 18 AMQP primitive types
Corner cases: Encoding boundaries, special values (infinity, NaN, etc.)
Extensible: Easy to add complex types, described types

4. Message Comparison (`qit.core.comparison`)

Type-aware message comparison:

Handles floating point precision (hex representation)
Binary data comparison (hex strings)
UUID normalization
String encoding handling

5. Broker Management (`qit.core.broker`)

Docker Compose-based broker lifecycle:

Start/stop/health check
Support for Artemis, Dispatch Router
Configurable timeouts and URLs

6. CLI (`qit.cli`)

Click-based command-line interface:

qit setup: Environment setup and shim building
qit test amqp-types: Run primitive type tests
qit broker: Broker management helpers

Data Flow

┌─────────────────┐
│  Test Suite     │
│  (pytest/CLI)   │
└────────┬────────┘
         │
         v
┌─────────────────┐
│  Orchestrator   │  ← Coordinates test execution
└────────┬────────┘
         │
    ┌────┴────┐
    v         v
┌────────┐ ┌────────┐
│ Sender │ │Receiver│  ← Native shims (Python, C++, Java, etc.)
│ Shim   │ │ Shim   │
└───┬────┘ └────┬───┘
    │           │
    └─────┬─────┘
          v
    ┌──────────┐
    │  Broker  │  ← Artemis via Docker Compose
    └──────────┘

Test Execution Flow

Discovery: Orchestrator finds available shims
Matrix Generation: Creates (sender, receiver, type) test cases
Broker Check: Ensures broker is running (if needed)
Per Test Case:
- Generate unique queue name
- Invoke sender shim with test values
- Invoke receiver shim to collect messages
- Compare sent vs received
- Record result
Reporting: Aggregate results and generate report

Shim Implementation

Each shim must:

Accept standard CLI arguments
Parse AMQP type names and encode values correctly
Output JSON results to stdout
Return non-zero exit code on errors
Support broker and direct modes

Example Python Shim Flow:

# Send
1. Parse --data JSON into Message objects
2. Encode each value to AMQP type (Proton API)
3. Connect to broker, create sender
4. Send messages, wait for confirmations
5. Output JSON results

# Receive
1. Connect to broker, create receiver
2. Wait for N messages (or timeout)
3. Decode each AMQP value to JSON-serializable format
4. Output JSON results