Debian Codegraph @

testing/integration/mqtt/README.md

raw
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`