Newsletter Integration Testing Guide

Newsletter Integration Testing Guide

This guide provides step-by-step instructions to thoroughly test the newsletter integration before going live.

🧪 Testing Stages

Stage 1: Local Testing

1.1 Basic Connectivity Test

# Set the webhook secret
export NEWSLETTER_WEBHOOK_SECRET='d9bd68f101c326057976e366c7c29ddfb3397abb2cbc01890488c6e9aeef0e2f'

# Run the basic webhook test
ruby scripts/test-newsletter-webhook.rb

Expected output: ✅ Success! Newsletter notification test passed.

1.2 Full Integration Test Suite

# Run comprehensive test suite
./scripts/test-newsletter-integration.sh

This will test:

• Ruby installation
• Webhook endpoint accessibility
• Security (invalid secret rejection)
• Notification script functionality
• Draft post handling
• GitHub Actions syntax

1.3 Simulate GitHub Actions Locally

# Simulate what happens in GitHub Actions
ruby scripts/simulate-github-action.rb

This creates a temporary environment and runs the full workflow locally.

Stage 2: GitHub Actions Testing (Isolated)

2.1 Set Up Test Environment

1. Add Webhook Secret to GitHub:
   • Go to Settings → Secrets and variables → Actions
   • Add NEWSLETTER_WEBHOOK_SECRET with the provided value
2. Create Test Branch:

   git checkout -b test-newsletter-integration
   git add .
   git commit -m "Add newsletter integration"
   git push origin test-newsletter-integration
   

2.2 Manual Workflow Test

1. Go to Actions tab in GitHub
2. Select “Test Newsletter Integration” workflow
3. Click “Run workflow”
4. Choose your test branch
5. Option: Enable “dry run” for first test

2.3 Automated Test

Push to a branch matching pattern test-newsletter-*:

git checkout -b test-newsletter-auto
git commit --allow-empty -m "Trigger test workflow"
git push origin test-newsletter-auto

Stage 3: Production Simulation

3.1 Create Realistic Test Post

# Create a test post that looks real
cat > _posts/$(date +%Y-%m-%d)-test-production-ready.md << 'EOF'
---
layout: post
title: "Test: New Feature Announcement"
date: $(date +%Y-%m-%d)
categories: [product-updates]
author: 
  name: "Your Name"
  avatar: "/assets/headshots/dakota.jpg"
excerpt: "Testing the newsletter system with a realistic post before going live."
---

This is a test of our newsletter notification system...
EOF

# Commit and push to test branch
git add _posts/
git commit -m "Add test post"
git push origin test-newsletter-integration

3.2 Verify in GitHub Actions

• Check Actions tab for workflow run
• Review logs for successful notification
• Confirm tracking file was updated

Stage 4: Pre-Production Checklist

4.1 API Verification

# Verify you can reach the production API
curl -I https://newsletter-subscribers.vercel.app/api/webhook/new-post

4.2 Final Safety Checks

• Webhook secret is in GitHub Secrets
• Test workflow succeeded
• No errors in GitHub Actions logs
• Tracking file (.github/notified-posts.json) works
• Draft posts are properly ignored
• Error handling doesn’t block deployment

Stage 5: Go-Live Process

5.1 Clean Up Test Files

# Remove test workflow (it's only for testing)
git rm .github/workflows/test-newsletter.yml

# Clean up any test posts
git rm _posts/*test*.md 2>/dev/null || true

# Commit changes
git add .
git commit -m "Clean up test files before go-live"

5.2 Merge to Main

# Create PR or merge directly
git checkout main
git merge test-newsletter-integration
git push origin main

5.3 First Real Post

When publishing your first real post after integration:

1. Monitor GitHub Actions in real-time
2. Check for the green checkmark
3. Verify subscribers received the email
4. Check .github/notified-posts.json was updated

🔍 Troubleshooting

Webhook Returns 401/403

• Verify webhook secret is correct
• Check it’s properly set in GitHub Secrets
• Ensure no extra spaces or quotes

No Notifications Sent

1. Check GitHub Actions logs
2. Verify post doesn’t have draft: true
3. Ensure post is new (not in tracking file)
4. Check webhook secret is set

Test Commands Reference

# Quick webhook test
ruby scripts/test-newsletter-webhook.rb

# Full test suite
./scripts/test-newsletter-integration.sh

# Simulate GitHub Actions
ruby scripts/simulate-github-action.rb

# Test with custom webhook URL (for local dev)
ruby scripts/test-newsletter-webhook.rb \
  --url http://localhost:3000/api/webhook/new-post \
  --secret test-secret

📊 Monitoring

After go-live, monitor success through:

1. GitHub Actions: Check workflow runs
2. Tracking File: .github/notified-posts.json
3. API Response: Look for success messages in logs
4. Subscriber Feedback: Confirm emails are received

🚨 Emergency Rollback

If issues occur after go-live:

# Disable workflow temporarily
mv .github/workflows/notify-newsletter.yml .github/workflows/notify-newsletter.yml.disabled
git add .
git commit -m "Temporarily disable newsletter notifications"
git push origin main

Then investigate and fix the issue before re-enabling.