Debian Codegraph @

testing/e2e/twilio/README.md

raw
1 # Twilio End-to-End Tests
2
3 This directory contains end-to-end (e2e) tests for the Twilio SMS service in Shoutrrr.
4
5 ## Overview
6
7 The end-to-end tests validate the complete Twilio SMS functionality by making actual API requests to Twilio's messaging API.
8
9 ## Test Coverage
10
11 ### Basic SMS Functionality
12
13 - **Basic Test** (`basic_test.go`): Sends a plain text SMS message through the Twilio API
14 - **Title Test** (`title_test.go`): Sends an SMS with a title prepended to the message body via the `title` query parameter
15
16 ### Service Validation
17
18 - **Service ID Test** (`service_id_test.go`): Verifies that the service correctly identifies itself as `"twilio"` (does not send an SMS)
19
20 ## Setup Requirements
21
22 ### Twilio Account Configuration
23
24 1. Create or log in to a [Twilio account](https://www.twilio.com/)
25 2. Obtain the following from your Twilio console:
26 - **Account SID** (starts with `AC`)
27 - **Auth Token**
28 - **Messaging Service SID** (starts with `MG`) or a Twilio phone number as the sender
29 - **Recipient phone number** (E.164 format, e.g., `+1234567890`)
30
31 ### Environment Variables
32
33 The tests require the `SHOUTRRR_TWILIO_URL` environment variable. You can provide it via a `.env` file placed in this directory, or by setting it directly in your shell.
34
35 #### `.env` file
36
37 Create a `.env` file in this directory (`testing/e2e/twilio/.env`):
38
39 ```bash
40 SHOUTRRR_TWILIO_URL=twilio://<ACCOUNT_SID>:<AUTH_TOKEN>@<MESSAGING_SID>/<RECIPIENT_PHONE>
41 ```
42
43 **Security Note**: Never commit real account credentials to version control. The `.env` file is included in `.gitignore`.
44
45 #### Inline environment variable
46
47 ```bash
48 SHOUTRRR_TWILIO_URL='twilio://<ACCOUNT_SID>:<AUTH_TOKEN>@<MESSAGING_SID>/<RECIPIENT_PHONE>' \
49 go test ./testing/e2e/twilio/ -v
50 ```
51
52 ### URL Format
53
54 ```
55 twilio://<AccountSID>:<AuthToken>@<MessagingSID>/<RecipientPhone>
56 ```
57
58 | Component | Description | Example |
59 | ---------------- | ----------------------------------------------- | ---------------------------------- |
60 | `AccountSID` | Twilio Account SID | `ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
61 | `AuthToken` | Twilio Auth Token | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
62 | `MessagingSID` | Messaging Service SID or sender phone number | `MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
63 | `RecipientPhone` | Destination phone number in E.164 format | `+1234567890` |
64
65 ## Running the Tests
66
67 ### Prerequisites
68
69 - Go 1.25+
70 - Valid Twilio account credentials
71 - `SHOUTRRR_TWILIO_URL` environment variable set (via `.env` or shell)
72
73 ### Execute E2E Tests
74
75 Run all Twilio e2e tests:
76
77 ```bash
78 go test ./testing/e2e/twilio/ -v
79 ```
80
81 Run a specific test:
82
83 ```bash
84 # Basic SMS test
85 go test ./testing/e2e/twilio/ -v -args -ginkgo.focus="Basic"
86
87 # Title test
88 go test ./testing/e2e/twilio/ -v -args -ginkgo.focus="Title"
89
90 # Service ID test
91 go test ./testing/e2e/twilio/ -v -args -ginkgo.focus="Service ID"
92 ```
93
94 ### Test Behavior
95
96 - Tests will **skip** (not fail) if `SHOUTRRR_TWILIO_URL` is not set
97 - Two of the three tests send actual SMS messages — monitor your Twilio account and recipient device during test runs
98 - The service ID test only validates the service identifier and does not send any messages
99
100 ### Expected Output
101
102 A successful run produces 3 passing specs. The basic and title tests each deliver one SMS to the configured recipient phone number (2 messages total).
103
104 ## Test Structure
105
106 ```
107 testing/e2e/twilio/
108 ├── .env # Environment variables (not committed)
109 ├── README.md # This file
110 ├── suite_test.go # Test suite setup and .env file loading
111 ├── basic_test.go # Basic SMS sending
112 ├── title_test.go # SMS with title parameter
113 └── service_id_test.go # Service identifier validation
114 ```