# Stripe Testing Guide

## Testing Stripe Integration Without Real Transactions

### 1. Use Stripe Test Mode

Stripe provides test API keys that allow you to simulate payments without real money:

1. Get your test keys from https://dashboard.stripe.com/test/apikeys
2. Set environment variables with test keys:
   ```bash
   export STRIPE_SECRET_KEY="sk_test_..."
   export STRIPE_WEBHOOK_SECRET="whsec_test_..."
   export STRIPE_PRICE_ID_PRO="price_test_..."
   ```

### 2. Use Stripe Test Cards

In test mode, use these test card numbers:
- **Success**: `4242 4242 4242 4242`
- **Decline**: `4000 0000 0000 0002`
- **3D Secure**: `4000 0025 0000 3155`

Any future expiry date and any 3-digit CVC will work.

### 3. Trigger Test Webhooks

Use Stripe CLI to trigger webhook events locally:

```bash
# Install Stripe CLI
# https://stripe.com/docs/stripe-cli

# Login
stripe login

# Forward webhooks to local server
stripe listen --forward-to localhost:8000/stripe/webhook

# Trigger specific events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger invoice.payment_failed
```

### 4. Run Unit Tests

The billing module includes unit tests that mock Stripe webhooks:

```bash
# Run billing tests
AREA=Test python3 Biz/PodcastItLater/Billing.py test

# Or use bild
bild --test Biz/PodcastItLater/Billing.py
```

### 5. Test Migration on Production

To fix the production database missing columns issue, you need to trigger the migration.

The migration runs automatically when `Database.init_db()` is called, but production may have an old database.

**Option A: Restart the web service**
The init_db() runs on startup, so restarting should apply migrations.

**Option B: Run migration manually**
```bash
# SSH to production
# Run Python REPL with proper environment
python3
>>> import os
>>> os.environ["AREA"] = "Live"
>>> os.environ["DATA_DIR"] = "/var/podcastitlater"
>>> import Biz.PodcastItLater.Core as Core
>>> Core.Database.init_db()
```

### 6. Verify Database Schema

Check that billing columns exist:

```bash
sqlite3 /var/podcastitlater/podcast.db
.schema users
```

Should show:
- `stripe_customer_id TEXT`
- `stripe_subscription_id TEXT`
- `subscription_status TEXT`
- `current_period_start TEXT`
- `current_period_end TEXT`
- `plan_tier TEXT NOT NULL DEFAULT 'free'`
- `cancel_at_period_end INTEGER DEFAULT 0`

### 7. End-to-End Test Flow

1. Start in test mode: `AREA=Test PORT=8000 python3 Biz/PodcastItLater/Web.py`
2. Login with test account
3. Go to /billing
4. Click "Upgrade Now"
5. Use test card: 4242 4242 4242 4242
6. Stripe CLI will forward webhook to your local server
7. Verify subscription updated in database

### 8. Common Issues

**KeyError in webhook**: Make sure you're using safe `.get()` access for all Stripe object fields, as the structure can vary.

**Database column missing**: Run migrations by restarting the service or calling `Database.init_db()`.

**Webhook signature verification fails**: Make sure `STRIPE_WEBHOOK_SECRET` matches your endpoint secret from Stripe dashboard.