Debian Codegraph @

testing/e2e/mqtt/README.md

raw
1 # MQTT End-to-End Tests
2
3 This directory contains end-to-end (e2e) tests for the MQTT service in Shoutrrr.
4
5 ## Overview
6
7 The end-to-end tests validate the complete MQTT notification functionality by connecting to a real MQTT broker and publishing messages to topics.
8
9 ## Test Coverage
10
11 ### Basic Functionality
12
13 - Plain text messages with various content types
14 - Basic connection and message publishing
15
16 ### QoS (Quality of Service) Levels
17
18 - QoS 0 (at most once) - Fire and forget
19 - QoS 1 (at least once) - Acknowledged delivery
20 - QoS 2 (exactly once) - Four-part handshake
21 - QoS configuration via URL parameters and runtime params
22
23 ### Retained Messages
24
25 - Non-retained messages (default)
26 - Retained message publishing
27 - Replacing retained messages
28
29 ### Authentication
30
31 - Anonymous connections (no auth)
32 - Username/password authentication
33 - Failed authentication handling
34
35 ### TLS Connections
36
37 - mqtts:// scheme for TLS connections
38 - Custom TLS port (8883)
39 - TLS failure scenarios
40
41 ### Topic Formats
42
43 - Single-level topics (e.g., `test/topic`)
44 - Nested topics (e.g., `home/alerts/notifications`)
45 - Single-level wildcards (e.g., `sensors/+/temperature`)
46 - Multi-level wildcards (e.g., `home/#`)
47 - Topics with special characters (URL-encoded)
48
49 ## Test Environment Setup
50
51 ### Prerequisites
52
53 - Go 1.25+
54 - Docker and Docker Compose
55 - Linux OS (for generating TLS certs)
56
57 ### Quick Start
58
59 A pre-configured, local EMQX deployment is provided, which includes bootstrapped authentication.
60
61 Before running the tests, you will need to use the provided `generate.sh` script to generate self-signed TLS certificates:
62
63 ```bash
64 cd testing/e2e/mqtt/certs
65 chmod +x generate.sh
66 ./generate.sh
67 ```
68
69 To start EMQX, run the following commands:
70
71 ```bash
72 cd testing/e2e/mqtt
73 docker-compose up -d
74 ```
75
76 This starts an EMQX broker with:
77
78 - Pre-configured MQTT test user
79 - TLS enabled on port 8883
80 - Anonymous access disabled
81
82 The EMQX Dashboard will be available at <http://localhost:18083>.
83
84 #### Dashboard Credentials
85
86 | Field | Value |
87 | --------- | --------- |
88 | Username | `admin` |
89 | Password | `public` |
90
91 ### Pre-Configuring Authentication
92
93 The docker-compose setup includes a pre-configured test user that is automatically bootstrapped when the container starts.
94 This `shoutrrr` user is what is used as a target for sending MQTT messages, rather than the `admin` user that's used for webui access.
95
96 #### MQTT Test Credentials
97
98 | Field | Value |
99 |----------|------------|
100 | Username | `shoutrrr` |
101 | Password | `testing` |
102
103 These credentials are used for MQTT connections (ports 1883 and 8883).
104
105 #### Bootstrap Configuration
106
107 The test user is defined in `auth-built-in-db-bootstrap.json`, which is mounted into the EMQX container and loaded on startup.
108
109 The bootstrap file contains:
110
111 - User ID (username)
112 - Password hash (SHA256 with salt prefix)
113 - Salt value
114 - Superuser status
115
116 ## Setup Details
117
118 ### EMQX Ports
119
120 | Port | Description |
121 |-------|-----------------------------|
122 | 1883 | Standard MQTT (unencrypted) |
123 | 8883 | MQTT over TLS |
124 | 8083 | WebSocket MQTT |
125 | 8084 | WebSocket MQTT over TLS |
126 | 18083 | Dashboard |
127
128 ### EMQX Authentication Configuration
129
130 The docker-compose uses the latest (v6) EMQX authentication syntax:
131
132 ```yaml
133 environment:
134 # Enable authentication with built-in database
135 - EMQX_AUTHENTICATION__1__ENABLE=true
136 - EMQX_AUTHENTICATION__1__BACKEND=built_in_database
137 - EMQX_AUTHENTICATION__1__MECHANISM=password_based
138 - EMQX_AUTHENTICATION__1__USER_ID_TYPE=username
139 - EMQX_AUTHENTICATION__1__PASSWORD_HASH_ALGORITHM={"name":"sha256","salt_position":"prefix"}
140 - EMQX_AUTHENTICATION__1__BOOTSTRAP_FILE=/opt/emqx/etc/auth-built-in-db-bootstrap.json
141 - EMQX_AUTHENTICATION__1__BOOTSTRAP_TYPE=hash
142 # Disable anonymous access
143 - EMQX_ALLOW_ANONYMOUS=false
144 ```
145
146 ### Generating New Password Hashes
147
148 A Python script [`shoutrrr-user-pw-hash.py`](shoutrrr-user-pw-hash.py) is provided for generating new password hashes:
149
150 ```bash
151 python3 shoutrrr-user-pw-hash.py
152 ```
153
154 Output example:
155
156 ```bash
157 Salt: 28005eec628f27a17a5dd7fab3b659b4
158 Password hash: dff95fabfde15b11706761c4c890f01291b60d5a624de7c2dcdd2643a1ba61bd
159 ```
160
161 To add a new user:
162
163 1. Edit the script to set your desired password
164 2. Run the script to generate salt and hash
165 3. Add a new entry to [`auth-built-in-db-bootstrap.json`](auth-built-in-db-bootstrap.json):
166
167 ```json
168 {
169 "user_id": "new_username",
170 "password_hash": "<generated_hash>",
171 "salt": "<generated_salt>",
172 "is_superuser": false
173 }
174 ```
175
176 4. Restart the EMQX container to load the new user
177
178 ### TLS Setup
179
180 For TLS tests, generate certificates before starting the broker:
181
182 ```bash
183 cd testing/e2e/mqtt/certs
184 chmod +x generate.sh
185 ./generate.sh
186 ```
187
188 This generates self-signed certificates valid for `localhost` and `127.0.0.1`.
189
190 **Note on TLS:** The TLS tests require proper certificate validation. For development with self-signed certificates, set `SHOUTRRR_MQTT_TLS_SKIP_VERIFY=true`.
191
192 ### Environment Variables
193
194 A template `.env` file is provided with preconfigured defaults that should work if following the quick setup instructions.
195
196 **Default values (matching pre-configured setup):**
197 **Security Note**: Never commit real credentials to version control. The `.env` file is in `.gitignore`.
198
199 ```bash
200 # Required: MQTT broker URL
201 SHOUTRRR_MQTT_URL=mqtt://localhost:1883/shoutrrr/test
202
203 # MQTT authentication (pre-configured user)
204 SHOUTRRR_MQTT_USERNAME=shoutrrr
205 SHOUTRRR_MQTT_PASSWORD=testing
206
207 # TLS URL
208 SHOUTRRR_MQTT_TLS_URL=mqtts://localhost:8883/shoutrrr/test
209
210 # Skip TLS certificate verification (for self-signed certs)
211 SHOUTRRR_MQTT_TLS_SKIP_VERIFY=true
212
213 # Authentication is required (anonymous access disabled)
214 SHOUTRRR_MQTT_AUTH_REQUIRED=true
215 ```
216
217 ### URL Format
218
219 The MQTT URL format is:
220
221 ```uri
222 mqtt://[username:password@]host[:port]/topic[?options]
223 ```
224
225 URL options include:
226
227 - `qos`: QoS level (0, 1, or 2)
228 - `retained`: Whether to retain the message (true/false)
229 - `clientid`: Client ID for the connection
230
231 ## Running the Tests
232
233 ### Prerequisites
234
235 - Go 1.25+
236 - Running MQTT broker
237 - `.env` file with required environment variables
238
239 ### Execute E2E Tests
240
241 Run all e2e tests:
242
243 ```bash
244 go test ./testing/e2e/mqtt/ -v
245 ```
246
247 Run specific test files:
248
249 ```bash
250 # Test basic functionality
251 go test ./testing/e2e/mqtt/ -v -args -ginkgo.focus="basic"
252
253 # Test QoS levels
254 go test ./testing/e2e/mqtt/ -v -args -ginkgo.focus="QoS"
255
256 # Test authentication
257 go test ./testing/e2e/mqtt/ -v -args -ginkgo.focus="Authentication"
258
259 # Test TLS connections
260 go test ./testing/e2e/mqtt/ -v -args -ginkgo.focus="TLS"
261
262 # Test topics
263 go test ./testing/e2e/mqtt/ -v -args -ginkgo.focus="Topic"
264 ```
265
266 ### Test Behavior
267
268 - Tests will skip if required environment variables are missing
269 - Tests include delays between executions to respect broker rate limits
270 - All tests send actual messages to your MQTT broker - monitor your broker during test runs
271 - Each test includes an "E2E Test:" prefix to identify test messages
272
273 ### Expected Output
274
275 Successful test run will show messages being published to your MQTT broker. Use an MQTT client (like `mosquitto_sub`) to verify messages are being received:
276
277 ```bash
278 # Subscribe to test topic (with authentication)
279 mosquitto_sub -t "test/#" -v -u shoutrrr -P testing
280
281 # Or for TLS
282 mosquitto_sub -t "test/#" -v --cafile certs/ca.pem -p 8883 -u shoutrrr -P testing
283 ```
284
285 ## Test Structure
286
287 ```bash
288 testing/e2e/mqtt/
289 ├── .env # Environment variables (not committed)
290 ├── docker-compose.yaml # EMQX broker setup (Docker Compose)
291 ├── auth-built-in-db-bootstrap.json # Pre-configured MQTT user
292 ├── shoutrrr-user-pw-hash.py # Password hash generator script
293 ├── suite_test.go # Test suite setup and configuration
294 ├── basic_test.go # Basic message sending functionality
295 ├── qos_test.go # QoS level tests (0, 1, 2)
296 ├── retained_test.go # Retained message tests
297 ├── auth_test.go # Authentication tests
298 ├── tls_test.go # TLS connection tests
299 ├── topics_test.go # Topic variations tests
300 ├── certs/ # TLS certificates directory
301 │ ├── generate.sh # Certificate generation script
302 │ ├── ca.pem # CA certificate
303 │ ├── cert.pem # Server certificate
304 │ └── key.pem # Server private key
305 └── README.md # This file
306 ```
307
308 ### Test Organization
309
310 Each test file focuses on a specific feature category:
311
312 - **Basic Tests** (`basic_test.go`): Core message sending functionality
313 - **QoS Tests** (`qos_test.go`): Quality of Service level testing
314 - **Retained Tests** (`retained_test.go`): Retained message handling
315 - **Auth Tests** (`auth_test.go`): Username/password authentication
316 - **TLS Tests** (`tls_test.go`): Secure TLS connections
317 - **Topic Tests** (`topics_test.go`): Topic format variations and wildcards
318
319 ## MQTT URL Examples
320
321 ### Basic Connection
322
323 ```bash
324 SHOUTRRR_MQTT_URL=mqtt://localhost:1883/test
325 ```
326
327 ### With Authentication
328
329 ```bash
330 SHOUTRRR_MQTT_URL=mqtt://shoutrrr:testing@localhost:1883/test
331 ```
332
333 ### With QoS
334
335 ```bash
336 SHOUTRRR_MQTT_URL=mqtt://localhost:1883/test?qos=1
337 ```
338
339 ### With TLS
340
341 ```bash
342 SHOUTRRR_MQTT_TLS_URL=mqtts://localhost:8883/test
343 ```
344
345 ### Retained Message
346
347 ```bash
348 SHOUTRRR_MQTT_URL=mqtt://localhost:1883/alerts?retained=true
349 ```
350
351 ### Using EMQX Dashboard
352
353 Access the EMQX dashboard at <http://localhost:18083> with the default credentials `admin:public` to monitor messages and connections during testing.
354
355 ## Manual Docker Setup (Advanced)
356
357 If you prefer not to use docker-compose, you can run EMQX manually with the Docker CLI:
358
359 ```bash
360 docker run -d --name emqx \
361 -p 1883:1883 \
362 -p 8883:8883 \
363 -p 8083:8083 \
364 -p 8084:8084 \
365 -p 18083:18083 \
366 -e EMQX_NAME=emqx \
367 -e EMQX_HOST=127.0.0.1 \
368 -e EMQX_DASHBOARD__DEFAULT_USERNAME=admin \
369 -e EMQX_DASHBOARD__DEFAULT_PASSWORD=public \
370 -e EMQX_ALLOW_ANONYMOUS=false \
371 -v $(pwd)/auth-built-in-db-bootstrap.json:/opt/emqx/etc/auth-built-in-db-bootstrap.json:ro \
372 -e EMQX_AUTHENTICATION__1__ENABLE=true \
373 -e EMQX_AUTHENTICATION__1__BACKEND=built_in_database \
374 -e EMQX_AUTHENTICATION__1__MECHANISM=password_based \
375 -e EMQX_AUTHENTICATION__1__USER_ID_TYPE=username \
376 -e EMQX_AUTHENTICATION__1__PASSWORD_HASH_ALGORITHM='{"name":"sha256","salt_position":"prefix"}' \
377 -e EMQX_AUTHENTICATION__1__BOOTSTRAP_FILE=/opt/emqx/etc/auth-built-in-db-bootstrap.json \
378 -e EMQX_AUTHENTICATION__1__BOOTSTRAP_TYPE=hash \
379 emqx/emqx:latest
380 ```
381
382 ## Resources
383
384 - EMQX Docker Image: <https://hub.docker.com/r/emqx/emqx>
385 - EMQX Enterprise Documentation: <https://docs.emqx.com/en/emqx/latest/>