# 🧪 Complete Testing Guide: ImmigoPro Auto-Charging

## ✅ What's Ready
- Automated charging command created
- Scheduler configured to run daily at 2:00 AM  
- Webhook updated to save customer ID automatically
- Command only affects ImmigoPro subscriptions (safe for existing subscriptions)

## 🚀 How to Test (Step-by-Step)

### Step 1: Make a Fresh Test Purchase

1. **Go to**: `http://localhost:5174/packages` (or your payments portal)
2. **Select**: Any ImmigoPro package
3. **Choose**: Any payment plan (3-month, 6-month, or 12-month recommended for testing)
4. **Complete**: Stripe checkout with test card `4242 4242 4242 4242`
5. **Webhook**: Will automatically activate subscription and save payment method

### Step 2: Check Subscription Status

```bash
cd backend
php check_immigopro_subscription.php
```

You should see:
- ✅ Status: active
- ✅ Paid: 0/X installments
- ✅ Payment Method: Stored (pm_xxx...)
- ✅ Next Charge Date: ~30 days from now

### Step 3: Force Next Charge to Today (For Testing)

```bash
# Replace 6 with your actual subscription ID
php force_next_charge.php 6
```

This sets `next_charge_date` to NOW so the command will process it immediately.

### Step 4: Run the Charging Command

```bash
php artisan immigopro:charge-installments
```

**Expected Result:**
```
Processing: ImmigoPro Subscription #6
  Package: Your Package Name
  User ID: XX
  Installment: 1 of 12
  Amount: $XX.XX
  ✓ SUCCESS: Charged $XX.XX
  Payment Intent: pi_xxxxx
  Progress: 1/12 paid
  Next charge: 2026-02-XX
```

### Step 5: Verify Progress

```bash
php check_immigopro_subscription.php
```

You should now see:
- ✅ Paid: 1/X installments (increased!)
- ✅ Next Charge Date: ~30 days in future

### Step 6: Test All Installments (Rapid Testing)

Repeat steps 3-5 multiple times to charge all installments quickly:

```bash
# Charge installment 2
php force_next_charge.php 6
php artisan immigopro:charge-installments

# Charge installment 3
php force_next_charge.php 6
php artisan immigopro:charge-installments

# ... continue until all installments paid
```

### Step 7: Verify Auto-Stop

After the LAST installment is paid, you should see:

```
  ✓ SUCCESS: Charged $XX.XX
  Progress: 12/12 paid
  🎉 Subscription completed! All installments paid.
```

**Check status:**
```bash
php check_immigopro_subscription.php
```

Should show:
- ✅ Status: **completed** (not active anymore!)
- ✅ Paid: 12/12
- ✅ Next Charge Date: **N/A** (null)

**Run command again:**
```bash
php artisan immigopro:charge-installments
```

Should show:
```
Found 0 ImmigoPro subscriptions due for charging
No charges needed at this time.
```

✅ **This proves auto-stop is working!** The subscription is completed and won't be charged again.

## 🎯 What This Tests

✅ Monthly installment charging  
✅ Progress tracking (paid_installments counter)  
✅ Next charge date calculation (+30 days)  
✅ Status change from `active` to `completed`  
✅ Auto-stop when all installments paid  
✅ Query exclusion of completed subscriptions  
✅ Only affects ImmigoPro subscriptions  

## 📊 Test Different Scenarios

### Test 3-Month Plan ($200 package)
- Upfront: $80
- Monthly: $40 × 3
- Total tests: 3 charges after upfront

### Test 6-Month Plan
- Upfront: 35% of price
- Monthly: Remaining ÷ 6
- Total tests: 6 charges after upfront

### Test 12-Month Plan  
- Upfront: 25% of price
- Monthly: Remaining ÷ 12
- Total tests: 12 charges after upfront

### Test Full Payment
- Upfront: 95% of price (5% discount)
- Monthly: None
- Status: Should immediately be `completed`
- Should NEVER appear in charging queue

## ⚠️ Important Notes

1. **Stripe CLI must be running** for webhooks during testing:
   ```bash
   stripe listen --forward-to localhost:8000/api/v1/webhooks/stripe
   ```

2. **New purchases required** - Old test subscriptions from before webhook update won't have customer IDs properly saved

3. **Backend must be running** on `localhost:8000`

4. **Test cards** - Use Stripe test cards only:
   - Success: `4242 4242 4242 4242`
   - Decline: `4000 0000 0000 0002`

## 🚀 Production Setup

When ready for production:

1. **Add to server crontab:**
   ```bash
   * * * * * cd /path/to/backend && php artisan schedule:run >> /dev/null 2>&1
   ```

2. **Verify webhook endpoint** is configured in Stripe Dashboard:
   - URL: `https://yourdomain.com/api/v1/webhooks/stripe`
   - Events: `checkout.session.completed`

3. **Monitor logs** at `backend/storage/logs/laravel.log`

## 🎉 Success Criteria

The system is working correctly when:
- ✅ Installments charged automatically every 30 days
- ✅ Progress tracked correctly (paid_installments increments)
- ✅ Status changes to 'completed' after last payment
- ✅ No more charges after completion
- ✅ Regular subscriptions unaffected
- ✅ Failed payments logged without breaking system
