Creative Ad Testing Service - Complete Local Testing Guide

🎯 Project Overview

This project provides an n8n custom node for AI-powered creative ad testing using Microsoft TinyTroupe persona simulation. Perfect for marketers who need to test different versions of ad copy for the SAME product to determine which messaging resonates best with their target audience.

💡 How Professionals Use This

• A/B Test Headlines: Compare emotional vs. rational messaging approaches
• Optimize Copy Variations: Test different value propositions for the same product
• Pre-Campaign Testing: Validate ad copy before spending on paid advertising
• Message Positioning: Compare feature-focused vs. benefit-focused copy
• Audience Insights: Understand why certain copy resonates with different demographics

Example: Testing 3 different headlines for your SaaS product:

1. "Boost Team Productivity by 40%" (metric-focused)
2. "Stop Wasting Time on Endless Meetings" (problem-focused)
3. "Join 50,000+ Teams Already Saving Time" (social proof-focused)

✨ What You Get

• n8n Custom Node: Drag-and-drop ad testing in n8n workflows
• AI Persona Simulation: Uses Microsoft TinyTroupe with OpenAI GPT-4
• Geographic Targeting: 7 different regions with culturally-aware personas
• Comprehensive Analysis: Sentiment, engagement scores, and improvement suggestions
• Production Ready: Full API backend with job queuing and result polling

---

🚀 Complete Local Testing Setup

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• OpenAI API Key (Get one here)
• n8n (we'll install this)

---

📋 Step-by-Step Testing Guide

Step 1: Set Up the Backend API

# 1. Clone and navigate to backend
cd backend

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Set up environment variables
cp ../env.docker.example .env
# Edit .env and add your OPENAI_API_KEY
echo "OPENAI_API_KEY=your_openai_key_here" >> .env

# 4. Test TinyTroupe integration
python3 test_tinytroupe_integration.py

# 5. Start the backend server
python3 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

✅ Verify Backend: Open http://localhost:8000/docs - you should see the FastAPI documentation.

---

Step 2: Install n8n Locally

# Install n8n globally
npm install -g n8n

# Verify installation
n8n --version

---

Step 3: Install the Creative Ad Tester Node

# Navigate to the n8n node directory
cd n8n-node

# Build the node
npm run build

# Link for development (easier than packaging)
npm link

# Verify linking
npm list -g | grep creative-ad-tester

Alternative: Package Installation Method

# If linking doesn't work, use packaging:
npm pack
npm install -g n8n-nodes-creative-ad-tester-1.0.2.tgz

🔄 IMPORTANT: After installing the node, you MUST restart n8n to load it properly.

---

Step 4: Start n8n with Custom Node

# IMPORTANT: Kill any existing n8n processes first
killall node 2>/dev/null || true

# Start n8n (it will automatically detect the custom node)
n8n start

# n8n will be available at: http://localhost:5678

🎉 You should see n8n running at http://localhost:5678

✅ Verify Node Installation: In n8n, click the "+" to add a node and search for "Creative Ad Tester". If it doesn't appear, the installation didn't work.

---

Step 5: Configure n8n Credentials

1. Open n8n: Go to http://localhost:5678
2. Go to Settings: Click the settings icon in the bottom left
3. Add Credentials:
   • Click "Credentials" → "New Credential"
   • Search for "Creative Ad Tester API"
   • Configure:
     • API Key: test-key-123 (any value works for local testing)
     • Base URL: http://127.0.0.1:8000
4. Test Connection: Click "Test" - should show "Connected successfully"
5. Save: Give it a name like "Creative Ad Tester - Local"

---

Step 6: Test the Node in n8n

⚠️ IMPORTANT: If the Creative Ad Tester node doesn't appear when you search for it, see n8n-node/TROUBLESHOOTING.md for detailed solutions.

Recommended: Manual Workflow Creation

1. Create New Workflow in n8n
2. Add Manual Trigger (drag from the left panel)
3. Add Creative Ad Tester Node:
   • Click "+" to add a node
   • Search for "Creative Ad Tester"
   • If it doesn't appear, the installation failed - see troubleshooting guide
   • Drag it to the canvas and connect to the manual trigger
4. Configure the Node:
   • Ad Copies: Add 2 text ads with any content
   • Geography: Select "US-West-Coast"
   • Persona Count: Set to 2-3 (for faster testing)
   • Credentials: Select your saved credentials
5. Execute the Test:
   • Click "Execute Workflow" button
   • The workflow will submit a job and poll for results
   • Results should appear in 30-60 seconds for 2-3 personas
   • You'll see detailed persona reactions, sentiment analysis, and winning ad determination

Alternative: Import Test Workflow

Try importing the pre-made workflow:

• n8n-node/working-test-workflow.json (recommended - tests 3 variations of the same product)

---

Step 7: Understanding the Results

The workflow will return structured results like:

{
  "job_id": "uuid",
  "status": "completed",
  "ad_results": [
    {
      "ad_title": "Tech Innovation Ad",
      "ad_content": "Discover the future...",
      "persona_reactions": [
        {
          "persona_name": "Liam Chen-Smith",
          "reaction": "I find this ad compelling because...",
          "sentiment": "positive",
          "engagement_score": 0.8,
          "reasoning": "..."
        }
      ],
      "overall_sentiment": "positive",
      "average_engagement": 0.75,
      "winning_elements": ["Strong value proposition", "Clear call-to-action"],
      "improvement_suggestions": ["Add social proof", "Strengthen urgency"]
    }
  ],
  "test_metadata": {
    "geography": "US-West-Coast",
    "persona_count": 3,
    "ad_count": 2,
    "test_framework": "Microsoft TinyTroupe"
  }
}

---

🧪 Alternative Testing Methods

Quick API Testing (Without n8n)

# Test backend directly - Testing 3 variations of copy for the same product
curl -X POST "http://localhost:8000/api/v1/test-ads" \
  -H "Content-Type: application/json" \
  -d '{
    "ad_copies": [
      {
        "type": "text",
        "content": "Boost your team productivity by 40% with our AI project management tool. Start free trial today!",
        "title": "Metric-Focused Copy"
      },
      {
        "type": "text", 
        "content": "Stop wasting time on endless meetings and unclear priorities. Our AI tool gets teams organized fast. Free trial available.",
        "title": "Problem-Focused Copy"
      },
      {
        "type": "text", 
        "content": "Join 50,000+ teams already using our AI project management solution. Proven 40% productivity boost. Try free for 14 days!",
        "title": "Social Proof Copy"
      }
    ],
    "geography": "US-West-Coast",
    "test_parameters": {
      "persona_count": 3,
      "simulation_depth": "detailed"
    }
  }'

# Check status (use job_id from response)
curl "http://localhost:8000/api/v1/jobs/{job_id}/status"

# Get results (when status is "completed")
curl "http://localhost:8000/api/v1/jobs/{job_id}/results"

Docker Testing

# One-command setup with Docker
./setup-docker-dev.sh

# Test with provided script
./test-api.sh

---

🛠 Customizing Your Tests

Geographic Options

• US-West-Coast - Tech professionals, environmentally conscious
• US-East-Coast - Business professionals, fashion-conscious
• US-Midwest - Family-oriented, value-conscious
• US-South - Traditional values, community-focused
• UK - Polite, understated, privacy-conscious
• Canada - Environmentally aware, polite, healthcare-conscious
• Australia - Casual, direct, outdoor lifestyle

Demographics Options

• Age Range: 18-24, 25-34, 35-44, 45-54, 55+
• Income Level: low, middle, high
• Interests: Comma-separated (e.g., "technology, sustainability, fitness")

Test Parameters

• Persona Count: 2-20 (more personas = more comprehensive but slower)
• Interaction Style: quick, detailed, conversational
• Max Wait Time: 5-30 minutes

---

🔧 Troubleshooting

Backend Issues

# Check if backend is running
curl http://localhost:8000/health

# Common fixes
rm backend/tinytroupe_api_cache.pickle  # Clear corrupted cache
export OPENAI_API_KEY="your-key"       # Set API key
pip install -r backend/requirements.txt # Reinstall dependencies

n8n Node Issues

# Node not appearing in n8n
npm list -g | grep creative-ad-tester  # Check if installed
killall node && n8n start             # Restart n8n

# Reinstall node
npm uninstall -g n8n-nodes-creative-ad-tester
cd n8n-node && npm pack && npm install -g *.tgz

Workflow Import Issues

• Can't find workflow file: The file is located at n8n-node/working-test-workflow.json from the project root
• Node shows "Install this node to use it": The custom node isn't installed - follow Step 3 again
• Credentials not available: Create credentials first (Step 5) before importing workflow
• Import button grayed out: Make sure you're selecting a .json file
• Workflow doesn't load: Try creating a new workflow manually and adding the Creative Ad Tester node
• Node appears as "CUSTOM.creativeAdTester": This is correct - the node is properly installed

Credential Issues

• Ensure Base URL is http://127.0.0.1:8000 (no trailing slash) - use IPv4, not localhost
• API Key can be any value for local testing
• Test connection before saving credentials
• If you get "ECONNREFUSED ::1:8000", change localhost to 127.0.0.1

Common Errors

• "Address already in use": Kill processes on port 8000: lsof -ti:8000 | xargs kill
• "TinyTroupe errors": Check OpenAI API key and account billing
• "Node not found": Restart n8n completely after installing the node
• "API timeout": Increase max wait time or reduce persona count
• "Invalid URL": Check credentials - make sure Base URL is http://127.0.0.1:8000
• "Status code 422": Node/API version mismatch - rebuild and reinstall the node

---

📊 Performance Notes

• 2-3 personas: ~30-60 seconds
• 5-8 personas: ~2-3 minutes
• 10+ personas: ~5-10 minutes
• API costs: ~$0.10-0.50 per test (depending on persona count)

---

🎯 What's Next?

Production Deployment

See DEPLOYMENT_ROADMAP.md for:

• AWS ECS Fargate deployment
• Real authentication system
• Rate limiting and monitoring
• Community node publication

Advanced Features

• Image ad testing
• Multi-language support
• Custom persona creation
• Industry-specific templates

---

📚 Additional Resources

• API Documentation: http://localhost:8000/docs (when backend is running)
• TinyTroupe GitHub: https://github.com/microsoft/TinyTroupe
• n8n Community: https://community.n8n.io/
• OpenAI API: https://platform.openai.com/docs

---

✅ Testing Checklist

Complete this checklist to verify everything is working:

• Backend starts without errors (uvicorn main:app --reload)
• Health check responds (curl localhost:8000/health)
• TinyTroupe test passes (python3 test_tinytroupe_integration.py)
• n8n installs and starts (n8n start)
• Creative Ad Tester node appears in n8n node list
• Credentials can be configured and tested
• Test workflow imports successfully
• Test workflow executes and returns results
• Results contain persona reactions and analysis

🎉 If all items are checked, your Creative Ad Tester n8n node is fully operational!

---

Need help? Check the troubleshooting section or review the logs in both the backend terminal and n8n interface.