Debian Codegraph @

testing/integration/matrix/README.md

raw
1 # Matrix Integration Tests
2
3 This directory contains black-box integration tests for the Matrix service in Shoutrrr.
4 The tests validate Matrix service functionality without making external calls, using the "dummy" URL pattern to bypass client initialization.
5
6 ## Overview
7
8 These are **black-box integration tests** that verify the Matrix service's public API and behavior without connecting to an actual Matrix server. The tests use the special `dummy://` URL pattern to prevent client initialization while still testing configuration parsing and service behavior.
9
10 ## Test Characteristics
11
12 - **Package**: `matrix_test`
13 - **Framework**: [Testify](https://github.com/stretchr/testify)
14 - **Location**: `testing/integration/matrix`
15 - **External Calls**: None (tests bypass client initialization)
16 - **Mocking**: Uses dummy URLs to avoid external connections
17
18 ## Test Coverage
19
20 ### Service Initialization
21
22 - Valid URL parsing with access token authentication
23 - Valid URL parsing with password authentication
24 - URL parsing with custom title parameter
25 - URL parsing with TLS disable option
26 - Error handling for missing host
27 - Error handling for missing credentials
28
29 ### Send Method
30
31 - Behavior with uninitialized client (dummy URL)
32 - Error handling when client is not initialized
33 - Empty message handling
34 - Service ID retrieval
35
36 ### Configuration
37
38 - URL parsing and configuration setting
39 - Special characters in passwords
40 - Port specification in URLs
41 - Query parameter handling (title, disableTLS)
42 - Room alias configuration
43
44 ## Running the Tests
45
46 Run all integration tests:
47
48 ```bash
49 go test -v ./testing/integration/matrix/...
50 ```
51
52 Run specific test files:
53
54 ```bash
55 go test ./testing/integration/matrix/ -run TestService -v
56 go test ./testing/integration/matrix/ -run TestConfig -v
57 ```
58
59 Run with coverage:
60
61 ```bash
62 go test -cover ./testing/integration/matrix/...
63 ```
64
65 ## Test Structure
66
67 ```bash
68 testing/integration/matrix/
69 ├── utils_test.go # Helper functions and testLogger implementation
70 ├── service_test.go # Service initialization and Send method tests
71 ├── config_test.go # Configuration parsing and URL handling tests
72 └── README.md # This documentation
73 ```
74
75 ## Helper Functions
76
77 ### testLogger
78
79 A minimal logger implementation for testing that satisfies the `types.StdLogger` interface:
80
81 ```go
82 type testLogger struct {
83 messages []string
84 }
85 ```
86
87 Methods:
88
89 - `Print(v ...any)` - Logs a message
90 - `Printf(format string, v ...any)` - Logs a formatted message
91 - `Println(v ...any)` - Logs a message with newline
92
93 ### createTestService
94
95 Creates a Matrix service with the given URL string:
96
97 ```go
98 func createTestService(t *testing.T, serviceURL string) *matrix.Service
99 ```
100
101 Uses the "dummy" URL special case to avoid actual client initialization, allowing tests to verify configuration handling without network connections.
102
103 ## Test Patterns
104
105 Tests use table-driven testing for comprehensive coverage:
106
107 ```go
108 func TestServiceInitializeWithValidURL(t *testing.T) {
109 tests := []struct {
110 name string
111 serviceURL string
112 }{
113 // Test cases...
114 }
115
116 for _, tt := range tests {
117 t.Run(tt.name, func(t *testing.T) {
118 // Test logic...
119 })
120 }
121 }
122 ```
123
124 ## Environment
125
126 No environment variables are required for integration tests since they do not connect to external services.
127
128 ## Related Files
129
130 - Matrix Service Implementation: `pkg/services/chat/matrix/service.go`
131 - Matrix Configuration: `pkg/services/chat/matrix/config.go`
132 - Matrix Types: `pkg/services/chat/matrix/types.go`