Send and receive SMS messages using your Android phone programmatically via a simple HTTP API
docs: add integration test implementation plan
Acho Arnold704355d9804b
diff --git a/docs/superpowers/plans/2026-05-03-integration-test-setup.md b/docs/superpowers/plans/2026-05-03-integration-test-setup.mdnew file mode 100644index 00000000..9a8f8cb6--- /dev/null+++ b/docs/superpowers/plans/2026-05-03-integration-test-setup.md@@ -0,0 +1,1107 @@+# Integration Test Setup Implementation Plan++> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.++**Goal:** Create a CI-gated integration test that validates the full SMS send/receive flow using Docker, a phone emulator, and real FCM code paths redirected to the emulator.++**Architecture:** Docker Compose brings up PostgreSQL + Redis + API + Emulator. The API's Firebase SDK is configured to route FCM traffic to the emulator via a custom HTTP transport. A Go test runner on the host exercises the API and asserts on message state.++**Tech Stack:** Go, Docker Compose, PostgreSQL, Redis, Firebase Admin Go SDK, GitHub Actions++---++## File Structure++```+tests/+├── docker-compose.yml # orchestrates all services+├── seed.sql # seeds test user, phone, API keys+├── .env.test # API environment config for tests+├── firebase-credentials.json # fake service account JSON+├── go.mod # test runner Go module+├── go.sum+├── integration_test.go # test cases (send SMS, receive SMS)+├── helpers_test.go # HTTP client, polling, constants+└── emulator/+ ├── Dockerfile # builds emulator binary+ ├── go.mod # emulator Go module+ ├── go.sum+ ├── main.go # entry point, HTTP server setup+ ├── fcm_handler.go # fake FCM endpoint handler+ ├── token_handler.go # fake OAuth2 token endpoint+ └── events.go # fires SENT/DELIVERED events to API++api/pkg/di/container.go # modified: FCM transport redirect+.github/workflows/integration-test.yml # new CI workflow+```++---++### Task 1: Create Feature Branch++**Files:**++- None (git operations only)++- [ ] **Step 1: Create and switch to feature branch from main**++```bash+cd C:\Users\Arnold\Work\NdoleStudio\httpsms.com+git checkout main+git pull origin main+git checkout -b feature/integration-tests+```++- [ ] **Step 2: Verify branch**++Run: `git branch --show-current`+Expected: `feature/integration-tests`++---++### Task 2: API Modification — FCM Transport Override++**Files:**++- Modify: `api/pkg/di/container.go:396-405` (FirebaseApp method)++- [ ] **Step 1: Add the FCM redirect transport and modify FirebaseApp**++In `api/pkg/di/container.go`, modify the `FirebaseApp()` method to check for `FCM_ENDPOINT` env var. When set, use ONLY a custom HTTP client (no credentials). When not set, use credentials as before.++**Important:** `option.WithHTTPClient()` takes precedence over all other options in the Firebase SDK. Do NOT combine it with `option.WithAuthCredentialsJSON()`. Use one or the other.++Create a new file `api/pkg/di/fcm_transport.go`:++```go+package di++import (+ "net/http"+ "net/url"+)++// fcmRedirectTransport rewrites Firebase SDK HTTP requests to a custom endpoint.+// Used in integration tests to redirect FCM traffic to the emulator.+type fcmRedirectTransport struct {+ target *url.URL+ base http.RoundTripper+}++func (t *fcmRedirectTransport) RoundTrip(req *http.Request) (*http.Response, error) {+ req.URL.Scheme = t.target.Scheme+ req.URL.Host = t.target.Host+ return t.base.RoundTrip(req)+}+```++Then modify `FirebaseApp()` in `container.go`:++```go+// FirebaseApp creates a new instance of firebase.App+func (container *Container) FirebaseApp() (app *firebase.App) {+ container.logger.Debug(fmt.Sprintf("creating %T", app))++ var opts []option.ClientOption++ if fcmEndpoint := os.Getenv("FCM_ENDPOINT"); fcmEndpoint != "" {+ container.logger.Info(fmt.Sprintf("using FCM endpoint override: %s", fcmEndpoint))+ targetURL, err := url.Parse(fcmEndpoint)+ if err != nil {+ container.logger.Fatal(stacktrace.Propagate(err, "cannot parse FCM_ENDPOINT"))+ }+ opts = append(opts, option.WithHTTPClient(&http.Client{+ Transport: &fcmRedirectTransport{+ target: targetURL,+ base: http.DefaultTransport,+ },+ }))+ } else {+ opts = append(opts, option.WithAuthCredentialsJSON(option.ServiceAccount, container.FirebaseCredentials()))+ }++ app, err := firebase.NewApp(context.Background(), nil, opts...)+ if err != nil {+ msg := "cannot initialize firebase application"+ container.logger.Fatal(stacktrace.Propagate(err, msg))+ }+ return app+}+```++- [ ] **Step 2: Add `net/url` import if not already present**++Ensure the `net/url` package is imported in `container.go` (or the new file).++- [ ] **Step 3: Verify API still builds**++Run: `cd api && go build ./...`+Expected: Build succeeds with no errors.++- [ ] **Step 4: Commit**++```bash+git add api/pkg/di/+git commit -m "feat(api): add FCM_ENDPOINT transport override for integration tests"+```++---++### Task 3: Emulator — Project Scaffolding++**Files:**++- Create: `tests/emulator/go.mod`+- Create: `tests/emulator/emulator.go`+- Create: `tests/emulator/Dockerfile`++Note: `main.go` references `NewEmulator()` and handlers, so we create the struct first. `main.go` is created AFTER all handlers exist (Task 6b).++- [ ] **Step 1: Initialize emulator Go module**++```bash+mkdir -p tests/emulator+cd tests/emulator+go mod init github.com/NdoleStudio/httpsms/tests/emulator+```++- [ ] **Step 2: Create `tests/emulator/emulator.go`**++```go+package main++import "net/http"++// Emulator acts as a fake Android phone that receives FCM pushes+// and responds with message events.+type Emulator struct {+ apiBaseURL string+ phoneAPIKey string+ httpClient *http.Client+}++// NewEmulator creates a new Emulator instance.+func NewEmulator(apiBaseURL, phoneAPIKey string) *Emulator {+ return &Emulator{+ apiBaseURL: apiBaseURL,+ phoneAPIKey: phoneAPIKey,+ httpClient: &http.Client{},+ }+}++// HealthHandler returns 200 OK for health checks.+func (e *Emulator) HealthHandler(w http.ResponseWriter, r *http.Request) {+ w.WriteHeader(http.StatusOK)+ w.Write([]byte("ok"))+}+```++- [ ] **Step 3: Create `tests/emulator/Dockerfile`**++```dockerfile+FROM golang:1.22 AS builder++WORKDIR /app+COPY go.mod go.sum ./+RUN go mod download+COPY . .+RUN CGO_ENABLED=0 GOOS=linux go build -o /bin/emulator .++FROM alpine:latest+RUN apk add --no-cache ca-certificates+COPY --from=builder /bin/emulator /bin/emulator+EXPOSE 9090+ENTRYPOINT ["/bin/emulator"]+```++- [ ] **Step 4: Commit**++```bash+git add tests/emulator/+git commit -m "feat(tests): scaffold emulator Go project"+```++---++### Task 4: Emulator — Token Handler++**Files:**++- Create: `tests/emulator/token_handler.go`++- [ ] **Step 1: Create `tests/emulator/token_handler.go`**++```go+package main++import (+ "encoding/json"+ "net/http"+)++// TokenHandler returns a fake OAuth2 access token.+// The Firebase Admin SDK calls this endpoint to get an access token+// before making FCM API calls.+func (e *Emulator) TokenHandler(w http.ResponseWriter, r *http.Request) {+ response := map[string]interface{}{+ "access_token": "fake-access-token",+ "token_type": "Bearer",+ "expires_in": 3600,+ }++ w.Header().Set("Content-Type", "application/json")+ json.NewEncoder(w).Encode(response)+}+```++- [ ] **Step 2: Commit**++```bash+git add tests/emulator/token_handler.go+git commit -m "feat(tests): add fake OAuth2 token handler to emulator"+```++---++### Task 5: Emulator — FCM Handler++**Files:**++- Create: `tests/emulator/fcm_handler.go`++- [ ] **Step 1: Create `tests/emulator/fcm_handler.go`**++```go+package main++import (+ "encoding/json"+ "fmt"+ "log"+ "net/http"+)++// fcmRequest represents the FCM v1 API request body+type fcmRequest struct {+ Message struct {+ Data map[string]string `json:"data"`+ Token string `json:"token"`+ Android struct {+ Priority string `json:"priority"`+ } `json:"android"`+ } `json:"message"`+}++// fcmResponse represents the FCM v1 API response+type fcmResponse struct {+ Name string `json:"name"`+}++// FCMHandler handles fake FCM send requests from the Firebase Admin SDK.+func (e *Emulator) FCMHandler(w http.ResponseWriter, r *http.Request) {+ var req fcmRequest+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {+ http.Error(w, "invalid request body", http.StatusBadRequest)+ return+ }++ messageID := req.Message.Data["KEY_MESSAGE_ID"]+ if messageID == "" {+ http.Error(w, "missing KEY_MESSAGE_ID in data", http.StatusBadRequest)+ return+ }++ log.Printf("received FCM push for message: %s", messageID)++ // Respond with success immediately (like real FCM would)+ resp := fcmResponse{+ Name: fmt.Sprintf("projects/httpsms-test/messages/fake-%s", messageID),+ }+ w.Header().Set("Content-Type", "application/json")+ json.NewEncoder(w).Encode(resp)++ // Process the message asynchronously (like a real phone would)+ go e.processMessage(messageID)+}+```++- [ ] **Step 3: Commit**++```bash+git add tests/emulator/emulator.go tests/emulator/fcm_handler.go+git commit -m "feat(tests): add FCM handler to emulator"+```++---++### Task 6: Emulator — Event Firing++**Files:**++- Create: `tests/emulator/events.go`++- [ ] **Step 1: Create `tests/emulator/events.go`**++```go+package main++import (+ "bytes"+ "encoding/json"+ "fmt"+ "log"+ "net/http"+ "time"+)++// messageEvent is the payload for posting a message event to the API+type messageEvent struct {+ Timestamp time.Time `json:"timestamp"`+ EventName string `json:"event_name"`+}++// processMessage simulates a phone receiving an FCM push and sending the SMS.+// It calls /messages/outstanding, then fires SENT and DELIVERED events.+func (e *Emulator) processMessage(messageID string) {+ // Step 1: Fetch outstanding message (like real phone does)+ e.fetchOutstanding(messageID)++ // Step 2: Wait briefly then fire SENT+ time.Sleep(200 * time.Millisecond)+ if err := e.fireEvent(messageID, "SENT"); err != nil {+ log.Printf("error firing SENT event for message %s: %v", messageID, err)+ return+ }++ // Step 3: Wait briefly then fire DELIVERED+ time.Sleep(200 * time.Millisecond)+ if err := e.fireEvent(messageID, "DELIVERED"); err != nil {+ log.Printf("error firing DELIVERED event for message %s: %v", messageID, err)+ return+ }++ log.Printf("completed processing message: %s", messageID)+}++// fetchOutstanding calls GET /v1/messages/outstanding to mimic the real phone behavior+func (e *Emulator) fetchOutstanding(messageID string) {+ url := fmt.Sprintf("%s/v1/messages/outstanding?message_id=%s", e.apiBaseURL, messageID)++ req, _ := http.NewRequest("GET", url, nil)+ req.Header.Set("x-api-key", e.phoneAPIKey)++ resp, err := e.httpClient.Do(req)+ if err != nil {+ log.Printf("error fetching outstanding message %s: %v", messageID, err)+ return+ }+ defer resp.Body.Close()+ log.Printf("fetched outstanding message %s: status %d", messageID, resp.StatusCode)+}++// fireEvent posts a message event (SENT or DELIVERED) to the API+func (e *Emulator) fireEvent(messageID, eventName string) error {+ url := fmt.Sprintf("%s/v1/messages/%s/events", e.apiBaseURL, messageID)++ event := messageEvent{+ Timestamp: time.Now().UTC(),+ EventName: eventName,+ }++ body, _ := json.Marshal(event)+ req, _ := http.NewRequest("POST", url, bytes.NewReader(body))+ req.Header.Set("Content-Type", "application/json")+ req.Header.Set("x-api-key", e.phoneAPIKey)++ resp, err := e.httpClient.Do(req)+ if err != nil {+ return fmt.Errorf("HTTP error: %w", err)+ }+ defer resp.Body.Close()++ if resp.StatusCode >= 400 {+ return fmt.Errorf("API returned status %d for %s event", resp.StatusCode, eventName)+ }++ log.Printf("fired %s event for message %s: status %d", eventName, messageID, resp.StatusCode)+ return nil+}+```++- [ ] **Step 2: Commit**++```bash+git add tests/emulator/events.go+git commit -m "feat(tests): add event firing to emulator"+```++---++### Task 6b: Emulator — Main Entry Point++**Files:**++- Create: `tests/emulator/main.go`++- [ ] **Step 1: Create `tests/emulator/main.go`**++Now that all handlers exist (HealthHandler, TokenHandler, FCMHandler), create the entry point:++```go+package main++import (+ "log"+ "net/http"+ "os"+)++func main() {+ apiBaseURL := os.Getenv("API_BASE_URL")+ if apiBaseURL == "" {+ apiBaseURL = "http://api:8000"+ }++ phoneAPIKey := os.Getenv("PHONE_API_KEY")+ if phoneAPIKey == "" {+ phoneAPIKey = "pk_test-phone-api-key"+ }++ emulator := NewEmulator(apiBaseURL, phoneAPIKey)++ mux := http.NewServeMux()+ mux.HandleFunc("GET /health", emulator.HealthHandler)+ mux.HandleFunc("POST /token", emulator.TokenHandler)+ mux.HandleFunc("POST /v1/projects/{project}/messages:send", emulator.FCMHandler)++ port := os.Getenv("PORT")+ if port == "" {+ port = "9090"+ }++ log.Printf("emulator listening on :%s", port)+ if err := http.ListenAndServe(":"+port, mux); err != nil {+ log.Fatalf("server error: %v", err)+ }+}+```++- [ ] **Step 2: Verify emulator builds**++```bash+cd tests/emulator+go build ./...+```++Expected: Build succeeds.++- [ ] **Step 3: Commit**++```bash+git add tests/emulator/main.go+git commit -m "feat(tests): add emulator main entry point"+```++---++### Task 7: Test Infrastructure — Seed Data & Config++**Files:**++- Create: `tests/seed.sql`+- Create: `tests/.env.test`+- Create: `tests/firebase-credentials.json`++- [ ] **Step 1: Create `tests/seed.sql`**++This script must match the exact table schema from entities. The tables are auto-migrated by GORM, so we insert after API startup. Actually — since we need the user to exist BEFORE the API processes requests, we seed via Docker's postgres init scripts.++Note: GORM auto-migrates tables on API startup. The seed SQL runs AFTER table creation. We use a Docker healthcheck + depends_on to ensure ordering. Alternatively, we can use a startup script that waits for the API to be ready, then seeds. The simplest approach: mount `seed.sql` as a Postgres init script — but that runs before GORM migrates.++**Better approach:** Create a `tests/seed.sh` script that waits for the API to start (which runs GORM migrations), then seeds the database via `psql`.++```sql+-- tests/seed.sql+-- Seed test data for integration tests+-- Run AFTER GORM has migrated the schema (i.e., after API starts)++-- Test user+INSERT INTO users (id, email, api_key, timezone, subscription_name, created_at, updated_at)+VALUES (+ 'test-user-id',+ '[email protected]',+ 'test-user-api-key',+ 'UTC',+ 'pro-monthly',+ NOW(),+ NOW()+) ON CONFLICT (id) DO NOTHING;++-- System user (for event queue auth)+INSERT INTO users (id, email, api_key, timezone, subscription_name, created_at, updated_at)+VALUES (+ 'system-user-id',+ '[email protected]',+ 'system-user-api-key',+ 'UTC',+ 'pro-monthly',+ NOW(),+ NOW()+) ON CONFLICT (id) DO NOTHING;++-- Test phone+INSERT INTO phones (id, user_id, fcm_token, phone_number, messages_per_minute, sim, max_send_attempts, message_expiration_seconds, created_at, updated_at)+VALUES (+ 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',+ 'test-user-id',+ 'fake-fcm-token',+ '+18005550199',+ 60,+ 'SIM1',+ 2,+ 600,+ NOW(),+ NOW()+) ON CONFLICT (id) DO NOTHING;++-- Phone API key (for emulator to authenticate as phone)+INSERT INTO phone_api_keys (id, name, user_id, user_email, phone_numbers, phone_ids, api_key, created_at, updated_at)+VALUES (+ 'b2c3d4e5-f6a7-8901-bcde-f12345678901',+ 'Integration Test Phone Key',+ 'test-user-id',+ '[email protected]',+ '{"+18005550199"}',+ '{"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}',+ 'pk_test-phone-api-key',+ NOW(),+ NOW()+) ON CONFLICT (id) DO NOTHING;+```++- [ ] **Step 2: Create `tests/.env.test`**++```env+ENV=production+GCP_PROJECT_ID=httpsms-test+USE_HTTP_LOGGER=true+ENTITLEMENT_ENABLED=false+EVENTS_QUEUE_TYPE=emulator+EVENTS_QUEUE_NAME=events-local+EVENTS_QUEUE_ENDPOINT=http://localhost:8000/v1/events+EVENTS_QUEUE_USER_API_KEY=system-user-api-key+EVENTS_QUEUE_USER_ID=system-user-id+FCM_ENDPOINT=http://emulator:9090+DATABASE_URL=postgresql://dbusername:dbpassword@postgres:5432/httpsms+DATABASE_URL_DEDICATED=postgresql://dbusername:dbpassword@postgres:5432/httpsms+REDIS_URL=redis://@redis:6379+APP_PORT=8000+APP_NAME=httpSMS+APP_URL=http://localhost:8000+SWAGGER_HOST=localhost:8000+SMTP_FROM_NAME=httpSMS+SMTP_USERNAME=+SMTP_PASSWORD=+SMTP_HOST=localhost+SMTP_PORT=2525+PUSHER_APP_ID=+PUSHER_KEY=+PUSHER_SECRET=+PUSHER_CLUSTER=+GCS_BUCKET_NAME=+UPTRACE_DSN=+CLOUDFLARE_TURNSTILE_SECRET_KEY=+```++- [ ] **Step 3: Create `tests/firebase-credentials.json`**++Generate an RSA private key for the fake service account. This must be a valid RSA key so the Firebase SDK can sign JWT tokens (even though the emulator won't validate them).++```bash+cd tests+openssl genrsa -out /tmp/test-key.pem 2048+```++Then create the JSON file with the key embedded:++```json+{+ "type": "service_account",+ "project_id": "httpsms-test",+ "private_key_id": "test-key-id",+ "private_key": "<contents of /tmp/test-key.pem with newlines as \\n>",+ "client_email": "[email protected]",+ "client_id": "123456789",+ "auth_uri": "http://emulator:9090/auth",+ "token_uri": "http://emulator:9090/token",+ "auth_provider_x509_cert_url": "http://emulator:9090/certs",+ "client_x509_cert_url": "http://emulator:9090/certs/test"+}+```++Note: The `FIREBASE_CREDENTIALS` env var in `.env.test` should be set to the full contents of this JSON file (single-line). The docker-compose will handle this.++- [ ] **Step 4: Commit**++```bash+git add tests/seed.sql tests/.env.test tests/firebase-credentials.json+git commit -m "feat(tests): add seed data and test environment config"+```++---++### Task 8: Docker Compose for Tests++**Files:**++- Create: `tests/docker-compose.yml`++- [ ] **Step 1: Create `tests/docker-compose.yml`**++```yaml+services:+ postgres:+ image: postgres:alpine+ environment:+ POSTGRES_DB: httpsms+ POSTGRES_PASSWORD: dbpassword+ POSTGRES_USER: dbusername+ ports:+ - "5435:5432"+ healthcheck:+ test: ["CMD-SHELL", "pg_isready -U dbusername -d httpsms"]+ interval: 5s+ timeout: 5s+ retries: 10+ start_period: 5s++ redis:+ image: redis:latest+ command: redis-server+ ports:+ - "6379:6379"+ healthcheck:+ test: ["CMD", "redis-cli", "ping"]+ interval: 5s+ timeout: 5s+ retries: 10++ emulator:+ build:+ context: ./emulator+ ports:+ - "9090:9090"+ environment:+ API_BASE_URL: http://api:8000+ PHONE_API_KEY: pk_test-phone-api-key+ PORT: "9090"+ healthcheck:+ test: ["CMD", "wget", "--spider", "-q", "http://localhost:9090/health"]+ interval: 5s+ timeout: 5s+ retries: 10++ api:+ build:+ context: ../api+ ports:+ - "8000:8000"+ depends_on:+ postgres:+ condition: service_healthy+ redis:+ condition: service_healthy+ emulator:+ condition: service_healthy+ env_file:+ - .env.test+ environment:+ FIREBASE_CREDENTIALS: "${FIREBASE_CREDENTIALS}"+ healthcheck:+ test: ["CMD", "wget", "--spider", "-q", "http://localhost:8000/"]+ interval: 5s+ timeout: 10s+ retries: 20+ start_period: 30s++ seed:+ image: postgres:alpine+ depends_on:+ api:+ condition: service_healthy+ environment:+ PGPASSWORD: dbpassword+ volumes:+ - ./seed.sql:/seed.sql:ro+ entrypoint:+ [+ "psql",+ "-h",+ "postgres",+ "-U",+ "dbusername",+ "-d",+ "httpsms",+ "-f",+ "/seed.sql",+ ]+ restart: "no"+```++- [ ] **Step 2: Commit**++```bash+git add tests/docker-compose.yml+git commit -m "feat(tests): add docker-compose for integration test stack"+```++---++### Task 9: Test Runner — Go Module & Helpers++**Files:**++- Create: `tests/go.mod`+- Create: `tests/helpers_test.go`++- [ ] **Step 1: Initialize test runner Go module**++```bash+cd tests+go mod init github.com/NdoleStudio/httpsms/tests+go get github.com/stretchr/testify+```++- [ ] **Step 2: Create `tests/helpers_test.go`**++```go+package tests++import (+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "testing"+ "time"++ "github.com/stretchr/testify/require"+)++const (+ apiBaseURL = "http://localhost:8000"+ userAPIKey = "test-user-api-key"+ phoneAPIKey = "pk_test-phone-api-key"+ testPhone = "+18005550199"+ testContact = "+18005550100"+)++// apiClient returns an HTTP client configured for API calls+func apiClient() *http.Client {+ return &http.Client{Timeout: 10 * time.Second}+}++// doRequest performs an HTTP request with the given API key+func doRequest(t *testing.T, method, url string, body io.Reader, apiKey string) *http.Response {+ t.Helper()+ req, err := http.NewRequest(method, url, body)+ require.NoError(t, err)+ req.Header.Set("Content-Type", "application/json")+ req.Header.Set("x-api-key", apiKey)++ resp, err := apiClient().Do(req)+ require.NoError(t, err)+ return resp+}++// pollMessageStatus polls GET /v1/messages/{id} until the message reaches the target status or times out+func pollMessageStatus(t *testing.T, messageID, targetStatus string, timeout time.Duration) map[string]interface{} {+ t.Helper()+ deadline := time.Now().Add(timeout)++ for time.Now().Before(deadline) {+ url := fmt.Sprintf("%s/v1/messages/%s", apiBaseURL, messageID)+ resp := doRequest(t, "GET", url, nil, userAPIKey)++ body, err := io.ReadAll(resp.Body)+ resp.Body.Close()+ require.NoError(t, err)++ if resp.StatusCode == http.StatusOK {+ var result map[string]interface{}+ require.NoError(t, json.Unmarshal(body, &result))++ data, ok := result["data"].(map[string]interface{})+ if ok && data["status"] == targetStatus {+ return data+ }+ }++ time.Sleep(200 * time.Millisecond)+ }++ t.Fatalf("message %s did not reach status %q within %v", messageID, targetStatus, timeout)+ return nil+}+```++- [ ] **Step 3: Commit**++```bash+git add tests/go.mod tests/go.sum tests/helpers_test.go+git commit -m "feat(tests): add test runner module and helpers"+```++---++### Task 10: Test Runner — Integration Tests++**Files:**++- Create: `tests/integration_test.go`++- [ ] **Step 1: Create `tests/integration_test.go`**++```go+package tests++import (+ "bytes"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "testing"+ "time"++ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestSendSMS_E2E(t *testing.T) {+ // Step 1: Send an SMS via the API+ sendPayload := map[string]interface{}{+ "from": testPhone,+ "to": testContact,+ "content": "Hello from integration test",+ }+ body, _ := json.Marshal(sendPayload)++ url := fmt.Sprintf("%s/v1/messages/send", apiBaseURL)+ resp := doRequest(t, "POST", url, bytes.NewReader(body), userAPIKey)+ defer resp.Body.Close()++ respBody, err := io.ReadAll(resp.Body)+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode, "send response: %s", string(respBody))++ // Step 2: Extract message ID+ var sendResult map[string]interface{}+ require.NoError(t, json.Unmarshal(respBody, &sendResult))+ data := sendResult["data"].(map[string]interface{})+ messageID := data["id"].(string)+ require.NotEmpty(t, messageID)++ t.Logf("sent message with ID: %s", messageID)++ // Step 3: Poll until message is delivered+ message := pollMessageStatus(t, messageID, "delivered", 15*time.Second)++ // Step 4: Assert final state+ assert.Equal(t, "delivered", message["status"])+ assert.Equal(t, testPhone, message["owner"])+ assert.Equal(t, testContact, message["contact"])+ assert.Equal(t, "Hello from integration test", message["content"])+}++func TestReceiveSMS_E2E(t *testing.T) {+ // Step 1: Simulate receiving an SMS (phone -> API)+ receivePayload := map[string]interface{}{+ "from": testContact,+ "to": testPhone,+ "content": "Hi there from integration test",+ "encrypted": false,+ "sim": "SIM1",+ "timestamp": time.Now().UTC().Format(time.RFC3339),+ }+ body, _ := json.Marshal(receivePayload)++ url := fmt.Sprintf("%s/v1/messages/receive", apiBaseURL)+ resp := doRequest(t, "POST", url, bytes.NewReader(body), phoneAPIKey)+ defer resp.Body.Close()++ respBody, err := io.ReadAll(resp.Body)+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, resp.StatusCode, "receive response: %s", string(respBody))++ // Step 2: Extract message ID+ var receiveResult map[string]interface{}+ require.NoError(t, json.Unmarshal(respBody, &receiveResult))+ data := receiveResult["data"].(map[string]interface{})+ messageID := data["id"].(string)+ require.NotEmpty(t, messageID)++ t.Logf("received message with ID: %s", messageID)++ // Step 3: Verify message exists via GET+ getURL := fmt.Sprintf("%s/v1/messages/%s", apiBaseURL, messageID)+ getResp := doRequest(t, "GET", getURL, nil, userAPIKey)+ defer getResp.Body.Close()++ getBody, err := io.ReadAll(getResp.Body)+ require.NoError(t, err)+ require.Equal(t, http.StatusOK, getResp.StatusCode)++ var getMessage map[string]interface{}+ require.NoError(t, json.Unmarshal(getBody, &getMessage))+ messageData := getMessage["data"].(map[string]interface{})++ // Step 4: Assert message fields+ assert.Equal(t, "received", messageData["status"])+ assert.Equal(t, testPhone, messageData["owner"])+ assert.Equal(t, testContact, messageData["contact"])+ assert.Equal(t, "Hi there from integration test", messageData["content"])+}+```++- [ ] **Step 2: Verify test file compiles**++```bash+cd tests+go vet ./...+```++Expected: No errors (tests won't pass yet without the stack running).++- [ ] **Step 3: Commit**++```bash+git add tests/integration_test.go+git commit -m "feat(tests): add send and receive SMS integration tests"+```++---++### Task 11: GitHub Actions Workflow++**Files:**++- Create: `.github/workflows/integration-test.yml`++- [ ] **Step 1: Create `.github/workflows/integration-test.yml`**++```yaml+name: integration-test++on:+ push:+ branches:+ - main+ pull_request:+ branches:+ - main++jobs:+ integration-test:+ runs-on: ubuntu-latest+ steps:+ - name: Checkout 🛎+ uses: actions/checkout@v4++ - name: Set up Go+ uses: actions/setup-go@v5+ with:+ go-version: "1.22"++ - name: Load Firebase credentials+ run: |+ echo "FIREBASE_CREDENTIALS=$(jq -c . tests/firebase-credentials.json)" >> $GITHUB_ENV++ - name: Start services 🐳+ working-directory: ./tests+ run: docker compose up -d --build --wait++ - name: Wait for seed to complete+ working-directory: ./tests+ run: |+ echo "Waiting for seed container to finish..."+ docker compose wait seed || true+ sleep 2++ - name: Run integration tests 🧪+ working-directory: ./tests+ run: go test -v -timeout 120s ./...++ - name: Collect logs on failure 📋+ if: failure()+ working-directory: ./tests+ run: |+ docker compose logs api+ docker compose logs emulator++ - name: Stop services 🛑+ if: always()+ working-directory: ./tests+ run: docker compose down -v+```++- [ ] **Step 2: Commit**++```bash+git add .github/workflows/integration-test.yml+git commit -m "ci: add integration test workflow"+```++---++### Task 12: Local End-to-End Verification++**Files:**++- None (verification only)++- [ ] **Step 1: Generate the fake Firebase credentials file**++```bash+cd tests+openssl genrsa 2048 > /tmp/test-key.pem+# Create firebase-credentials.json with the key (use a script or manually format)+```++- [ ] **Step 2: Build and start the stack**++```bash+cd tests+export FIREBASE_CREDENTIALS=$(jq -c . firebase-credentials.json)+docker compose up -d --build+```++- [ ] **Step 3: Wait for all services to be healthy**++```bash+docker compose ps+# All services should show "healthy" or "exited (0)" for seed+```++- [ ] **Step 4: Run the tests**++```bash+cd tests+go test -v -timeout 120s ./...+```++Expected: Both tests pass.++- [ ] **Step 5: Tear down**++```bash+docker compose down -v+```++- [ ] **Step 6: Push branch and create PR**++```bash+git push -u origin feature/integration-tests+gh pr create --title "feat: add integration test setup for API" --body "Adds E2E integration tests that validate the full SMS send/receive flow using Docker and a phone emulator."+```