| 1 |
# MQTT Integration Tests |
| 2 |
|
| 3 |
This directory contains integration tests for the MQTT service in Shoutrrr. |
| 4 |
The tests validate MQTT functionality by mocking the connection manager, ensuring feature parity with MQTT v5 protocol. |
| 5 |
|
| 6 |
## Test Coverage |
| 7 |
|
| 8 |
### Configuration Options |
| 9 |
|
| 10 |
- URL parsing for `mqtt://` and `mqtts://` schemes |
| 11 |
- Default ports (1883 for mqtt, 8883 for mqtts) |
| 12 |
- Query parameters (qos, retained, clientid, cleansession, disabletls, disabletlsverification) |
| 13 |
- Username/password authentication from URL |
| 14 |
- Invalid URL handling (missing topic) |
| 15 |
- Invalid QoS values |
| 16 |
|
| 17 |
### Message Publishing |
| 18 |
|
| 19 |
- Basic message publish |
| 20 |
- Publish with different QoS levels (0, 1, 2) |
| 21 |
- Publish with retained flag |
| 22 |
- Publish with params override |
| 23 |
- Multiple messages |
| 24 |
- Topic variations (simple, nested, deep paths) |
| 25 |
|
| 26 |
### Error Handling |
| 27 |
|
| 28 |
- Connection errors |
| 29 |
- Publish errors with reason codes |
| 30 |
- Timeout errors |
| 31 |
- Connection not initialized error |
| 32 |
- Invalid QoS errors |
| 33 |
- Disconnect errors |
| 34 |
|
| 35 |
### Timeout Scenarios |
| 36 |
|
| 37 |
- Publish timeout (10s) |
| 38 |
- Disconnect timeout (5s) |
| 39 |
- Context cancellation handling |
| 40 |
- Fast operation completion before timeout |
| 41 |
|
| 42 |
### Edge Cases |
| 43 |
|
| 44 |
- Empty message |
| 45 |
- Very long message (1MB+) |
| 46 |
- Special characters in topic |
| 47 |
- Unicode in message (emoji, Chinese, Japanese, Arabic, Russian) |
| 48 |
- Newlines and tabs in message |
| 49 |
- JSON and XML payloads |
| 50 |
- HTML entities |
| 51 |
- Whitespace-only messages |
| 52 |
- Binary-like data |
| 53 |
- Concurrent message publishing |
| 54 |
- Deep topic paths |
| 55 |
|
| 56 |
## Running the Tests |
| 57 |
|
| 58 |
### Mocked Integration Tests (Default) |
| 59 |
|
| 60 |
Run all integration tests with mocked MQTT connection: |
| 61 |
|
| 62 |
```bash |
| 63 |
go test ./testing/integration/mqtt/ -v |
| 64 |
``` |
| 65 |
|
| 66 |
Or run specific test files: |
| 67 |
|
| 68 |
```bash |
| 69 |
# Run specific test categories |
| 70 |
go test ./testing/integration/mqtt/ -run TestConfig -v |
| 71 |
go test ./testing/integration/mqtt/ -run TestPublish -v |
| 72 |
go test ./testing/integration/mqtt/ -run TestErrors -v |
| 73 |
go test ./testing/integration/mqtt/ -run TestTimeout -v |
| 74 |
go test ./testing/integration/mqtt/ -run TestEdgeCases -v |
| 75 |
``` |
| 76 |
|
| 77 |
## Test Structure |
| 78 |
|
| 79 |
The test suite is organized as a flat directory structure with individual test files for each feature category: |
| 80 |
|
| 81 |
```bash |
| 82 |
testing/integration/mqtt/ |
| 83 |
├── utils_test.go # Helper functions and mock implementations |
| 84 |
├── config_test.go # Configuration and URL parsing tests |
| 85 |
├── publish_test.go # Message publishing tests |
| 86 |
├── errors_test.go # Error handling tests |
| 87 |
├── timeout_test.go # Timeout scenario tests |
| 88 |
├── edge_cases_test.go # Edge case and boundary condition tests |
| 89 |
└── README.md # This documentation |
| 90 |
``` |
| 91 |
|
| 92 |
## Mock Architecture |
| 93 |
|
| 94 |
### MockConnectionManager |
| 95 |
|
| 96 |
The `MockConnectionManager` implements the `mqtt.ConnectionManager` interface using testify mock: |
| 97 |
|
| 98 |
```go |
| 99 |
type MockConnectionManager struct { |
| 100 |
mock.Mock |
| 101 |
} |
| 102 |
``` |
| 103 |
|
| 104 |
Methods mocked: |
| 105 |
|
| 106 |
- `AwaitConnection(ctx context.Context) error` |
| 107 |
- `Publish(ctx context.Context, publish *paho.Publish) (*paho.PublishResponse, error)` |
| 108 |
- `Disconnect(ctx context.Context) error` |
| 109 |
|
| 110 |
### Helper Functions |
| 111 |
|
| 112 |
- `createTestService(t *testing.T, url string, mockManager ...ConnectionManager) *mqtt.Service` |
| 113 |
- `createMockPublishResponse(reasonCode byte) *paho.PublishResponse` |
| 114 |
- `createMockPublishResponseWithReason(reasonCode byte, reasonString string) *paho.PublishResponse` |
| 115 |
- `createTestParams(pairs ...string) *types.Params` |
| 116 |
- `assertPublishCalled(t *testing.T, mockManager *MockConnectionManager, expectedTopic string)` |
| 117 |
- `assertPublishPayload(t *testing.T, mockManager *MockConnectionManager, expectedPayload string)` |
| 118 |
- `assertPublishQoS(t *testing.T, mockManager *MockConnectionManager, expectedQoS byte)` |
| 119 |
- `assertPublishRetained(t *testing.T, mockManager *MockConnectionManager, expectedRetained bool)` |
| 120 |
- `getPublishCall(mockManager *MockConnectionManager) *paho.Publish` |
| 121 |
|
| 122 |
## MQTT v5 Reason Codes |
| 123 |
|
| 124 |
The tests cover various MQTT v5 reason codes: |
| 125 |
|
| 126 |
| Code | Name | Type | |
| 127 |
|------|-------------------------------|---------| |
| 128 |
| 0x00 | Success | Success | |
| 129 |
| 0x01 | Granted QoS 1 | Success | |
| 130 |
| 0x02 | Granted QoS 2 | Success | |
| 131 |
| 0x10 | No matching subscribers | Warning | |
| 132 |
| 0x80 | Unspecified error | Failure | |
| 133 |
| 0x81 | Malformed Packet | Failure | |
| 134 |
| 0x82 | Protocol Error | Failure | |
| 135 |
| 0x83 | Implementation specific error | Failure | |
| 136 |
| 0x84 | Unsupported Protocol Version | Failure | |
| 137 |
| 0x85 | Client Identifier not valid | Failure | |
| 138 |
| 0x86 | Bad User Name or Password | Failure | |
| 139 |
| 0x87 | Not authorized | Failure | |
| 140 |
|
| 141 |
Codes >= 0x80 are treated as failures and return an error. |
| 142 |
Codes < 0x80 are treated as success/warnings and do not return an error. |
| 143 |
|
| 144 |
## Test Patterns |
| 145 |
|
| 146 |
All tests follow the synctest pattern for time-based testing: |
| 147 |
|
| 148 |
```go |
| 149 |
func TestFeature(t *testing.T) { |
| 150 |
synctest.Test(t, func(t *testing.T) { |
| 151 |
// Test code |
| 152 |
}) |
| 153 |
} |
| 154 |
``` |
| 155 |
|
| 156 |
Mock expectations are always verified: |
| 157 |
|
| 158 |
```go |
| 159 |
mockManager.AssertExpectations(t) |
| 160 |
``` |
| 161 |
|
| 162 |
## Constants |
| 163 |
|
| 164 |
The MQTT service uses the following timeout constants: |
| 165 |
|
| 166 |
- `publishTimeout` = 10 seconds |
| 167 |
- `disconnectTimeout` = 5 seconds |
| 168 |
- `keepAliveInterval` = 20 seconds |
| 169 |
- `sessionExpiryInterval` = 60 seconds |
| 170 |
|
| 171 |
## Related Files |
| 172 |
|
| 173 |
- MQTT Service Implementation: `pkg/services/push/mqtt/mqtt_service.go` |
| 174 |
- MQTT Configuration: `pkg/services/push/mqtt/mqtt_config.go` |
| 175 |
- MQTT Errors: `pkg/services/push/mqtt/mqtt_errors.go` |
| 176 |
- Connection Manager Interface: `pkg/services/push/mqtt/mqtt_connection_manager.go` |