Debian Codegraph @

testing/integration/twilio/README.md

raw
1 # Twilio Integration Tests
2
3 This directory contains integration tests for the Twilio SMS service in Shoutrrr.
4 The tests validate Twilio SMS functionality by mocking HTTP requests to Twilio's API, ensuring feature parity with Twilio's Messages API.
5
6 ## Test Coverage
7
8 ### API Compliance
9
10 - API URL format validation (`https://api.twilio.com/2010-04-01/Accounts/{SID}/Messages.json`)
11 - Valid URL format parsing
12 - Payload structure (form-encoded: `Body`, `To`, `From` fields)
13 - Basic Auth header construction
14 - Content-Type header (`application/x-www-form-urlencoded`)
15 - HTTP method (POST)
16 - HTTPS requirement
17 - MessagingServiceSid support (replaces `From` field)
18
19 ### Configuration
20
21 - Multiple recipient handling
22 - Phone number normalization (dashes, parentheses, dots)
23 - MessagingServiceSid configuration
24 - Title parameter (prepended to message body)
25 - Empty title handling
26
27 ### Send Functionality
28
29 - Basic message sending
30 - Multiple recipient delivery
31 - Title via URL query parameter
32 - Title via params map
33 - Unicode message support
34 - Empty message handling
35 - Service initialization
36
37 ### Error Handling
38
39 - HTTP error responses (400, 401, 403, 404, 500)
40 - Network errors
41 - Twilio API error parsing (code and message extraction)
42 - Malformed API error responses
43 - Partial failure (multi-recipient with mixed results)
44 - Empty error body handling
45
46 ## Running the Tests
47
48 ### Mocked Integration Tests (Default)
49
50 Run all integration tests with mocked Twilio API responses:
51
52 ```bash
53 go test ./testing/integration/twilio/ -v
54 ```
55
56 Or run specific test categories:
57
58 ```bash
59 go test ./testing/integration/twilio/ -run TestAPICompliance -v
60 go test ./testing/integration/twilio/ -run TestConfig -v
61 go test ./testing/integration/twilio/ -run TestSend -v
62 go test ./testing/integration/twilio/ -run TestErrors -v
63 ```
64
65 ## Test Structure
66
67 The test suite is organized as a flat directory structure with individual test files for each feature category:
68
69 ```bash
70 testing/integration/twilio/
71 ├── api_compliance_test.go # API compliance and Twilio webhook specification validation
72 ├── config_test.go # Configuration options (phone normalization, recipients, title, MessagingServiceSid)
73 ├── errors_test.go # Error handling and edge cases (HTTP errors, API errors, partial failures)
74 ├── send_test.go # Send functionality (basic send, multi-recipient, title, unicode)
75 ├── utils_test.go # Shared test utilities (mock HTTP client, helpers)
76 └── README.md # This documentation
77 ```
78
79 ### Test Organization
80
81 Each test file contains independent black-box tests for specific Twilio service behaviors.
82 Tests validate that the service correctly interacts with external APIs without inspecting internal data structures:
83
84 - **API Compliance Tests** (`api_compliance_test.go`): Service behavior with different Twilio API response scenarios
85 - **Config Tests** (`config_test.go`): Service configuration application in external API requests
86 - **Send Tests** (`send_test.go`): Service handling of various message types and external API responses
87 - **Error Tests** (`errors_test.go`): Service error handling when external APIs return failures