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