# Manual Testing Guide: Cross-Product Shipping Feature

This guide provides step-by-step instructions for manually testing the cross-product shipping calculation feature in development.

## Feature Summary

**What Changed:**

- **Before**: When an order had multiple items from different products, each product group calculated its shipping independently (each got its own "first" rate)
- **After**: The highest "first" shipping rate applies globally across ALL items in an order, regardless of product. Remaining items use their "additional" rates


**Example Impact:**


```
Order: 1× T-Shirt ($20 first, $10 add) + 1× Candle ($7 first, $3 add)

BEFORE (Old Logic):
- T-Shirt: $20 first
- Candle: $7 first
- Total shipping: $27

AFTER (New Logic):
- T-Shirt: $20 first (highest)
- Candle: $3 additional
- Total shipping: $23 ✅ ($4 savings)
```

## Pre-Testing Checklist

- [ ] Development environment is running (`npm run dev`)
- [ ] Database has test merchant stores connected (Etsy and/or Shopify)
- [ ] Database has products with varying shipping rates
- [ ] You have access to the dashboard orders page


## Test Scenarios

### Test 1: Single Product with Multiple Quantities (Baseline - No Change Expected)

**Purpose**: Verify no regression for single-product orders

**Steps**:

1. Navigate to Dashboard → Orders
2. Find or create an order with multiple items of the **same product**
  - Example: 3× T-Shirt (same design, same size)
3. Click "Checkout" or view order details


**Expected Behavior**:

- Shipping should calculate normally: highest first rate + additional rates for remaining items
- **No change from previous behavior**


**Example Calculation**:

- 3× T-Shirt ($20 each, first=$8, add=$4)
- Shipping: $8 (first) + $4 (add) + $4 (add) = $16 ✅


**What to Check**:

- [ ] Order total matches expected calculation
- [ ] Shipping breakdown is displayed correctly
- [ ] No errors in browser console


### Test 2: Multiple Different Products, Single Quantity Each (Core New Behavior)

**Purpose**: Verify cross-product logic applies correctly

**Steps**:

1. Navigate to Dashboard → Orders
2. Create or find an order with items from **different products**:
  - 1× Product A (high shipping)
  - 1× Product B (medium shipping)
  - 1× Product C (low shipping)
3. View order details or checkout page


**Expected Behavior**:

- Only the **highest** first rate should be charged once
- Other items should use their **additional** rates
- Total shipping should be **lower** than before


**Example Calculation**:


```
1× Premium T-Shirt ($25, first=$20, add=$10)
1× Candle ($15, first=$7, add=$3)
1× Card ($5, first=$5, add=$0) ← note: additional=0

BEFORE: $20 + $7 + $5 = $32 shipping
AFTER: $20 (T-Shirt first) + $3 (Candle add) + $5 (Card first, because add=0) = $28 ✅
Product cost: $25 + $15 + $5 = $45
TOTAL: $73
```

**What to Check**:

- [ ] Shipping total is lower than sum of all first rates
- [ ] Order total is correct
- [ ] Shipping breakdown shows which item uses "first"
- [ ] No errors in console


### Test 3: Multiple Products with Mixed Quantities (Complex Scenario)

**Purpose**: Verify logic works with multiple items of multiple products

**Steps**:

1. Create or find an order with:
  - 2-3× Product A
  - 2-3× Product B
  - 1-2× Product C
2. View order details or proceed to checkout


**Expected Behavior**:

- One item globally gets the highest first rate
- All other items use their additional rates (respecting the additional=0 quirk)


**Example Calculation**:


```
2× T-Shirt ($20 each, first=$20, add=$10)
3× Candle ($12 each, first=$7, add=$3)

5 items total:
- Highest first: $20 (T-Shirt)
- Remaining: $10 + $3 + $3 + $3 = $19
- Total shipping: $39
- Product cost: (2×$20) + (3×$12) = $76
- TOTAL: $115
```

**What to Check**:

- [ ] Total shipping is (highest first) + (sum of additionals)
- [ ] Order total matches expected calculation
- [ ] All items display correctly in shipping breakdown
- [ ] No errors


### Test 4: The "additional=0" Quirk

**Purpose**: Verify items with additional=0 use their first rate instead

**Steps**:

1. Find or create a product with shipping rates where **additional = 0**
  - Example: Greeting Cards often have first=$5, additional=$0
2. Create an order mixing this product with others
3. View order details


**Expected Behavior**:

- The item with additional=0 should use its **first rate** for additional units
- This is intentional ("additional=0 means match the first price")


**Example Calculation**:


```
1× T-Shirt ($20, first=$10, add=$5)
1× Card ($8, first=$5, add=$0) ← note the 0!

AFTER:
- $10 (T-Shirt first, highest)
- $5 (Card uses first because additional=0)
- Total shipping: $15
- Product cost: $28
- TOTAL: $43
```

**What to Check**:

- [ ] Items with additional=0 show first rate for additional units
- [ ] Calculation is correct
- [ ] No division by zero or null errors


### Test 5: International Shipping

**Purpose**: Verify destination-based rate resolution still works

**Steps**:

1. Create an order with destination country set to non-US (e.g., Canada, UK)
2. Ensure products have INTL shipping rates configured
3. View order totals


**Expected Behavior**:

- Should use INTL rates when available
- Falls back to DEFAULT if country-specific rate not found
- Cross-product logic still applies


**What to Check**:

- [ ] INTL rates are applied correctly
- [ ] Fallback logic works (INTL → DEFAULT)
- [ ] Cross-product max calculation uses resolved rates
- [ ] No errors


### Test 6: Order List View

**Purpose**: Verify order list displays correct totals

**Steps**:

1. Navigate to Dashboard → Orders
2. View the orders table


**Expected Behavior**:

- Each order row shows the correct total
- Totals match what you see in detail view
- No layout issues


**What to Check**:

- [ ] Order totals display correctly in table
- [ ] No NaN or undefined values
- [ ] Sorting works if applicable
- [ ] Page loads without errors


### Test 7: Checkout Flow

**Purpose**: Verify end-to-end checkout works correctly

**Steps**:

1. Select multiple pending orders with mixed products
2. Click "Checkout"
3. Review the checkout summary
4. (Optional) Complete payment in test mode


**Expected Behavior**:

- Checkout summary shows correct totals per order
- Grand total is accurate
- Payment intent created with correct amount
- No errors during checkout


**What to Check**:

- [ ] Checkout summary matches order detail calculations
- [ ] Can proceed through checkout without errors
- [ ] Payment intent amount matches (check Stripe dashboard)
- [ ] After payment, order records are correct


### Test 8: Package Insert

**Purpose**: Verify package insert cost still applies correctly

**Steps**:

1. Find or create an order where store has a package insert enabled
2. View order total


**Expected Behavior**:

- $0.25 per order should be added to total
- This is order-level, not item-level


**What to Check**:

- [ ] $0.25 is added for package insert
- [ ] Only added once per order (not per item)
- [ ] Total is correct


## Regression Testing

### Areas That Should NOT Change:

1. **Customer-paid amounts** (from Etsy/Shopify) - These are historical and should not recalculate
2. **Payment transaction records** - Existing records should remain unchanged
3. **Single-product orders** - Should calculate identically to before
4. **Product costs** - Only shipping changes, not product pricing
5. **API responses** - Same structure, just different values


## Known Issues to Watch For

### Potential Issues:

1. **NaN or null values** in shipping calculations
  - Check: Items with missing shipping_rates
  - Fix: Should default to 0
2. **Incorrect order in item expansion**
  - Check: Items might be processed in unexpected order
  - Verify: Calculation is order-independent (max is max)
3. **Performance with large orders**
  - Check: Orders with 10+ items
  - Verify: No slow rendering or calculation delays
4. **UI display confusion**
  - Check: Shipping breakdown labels
  - Users might expect per-product grouping still


## Console Debugging

### Useful Console Commands:


```javascript
// In browser console on order detail page:

// Check order data
console.log('Order:', orderData)

// Check calculation
console.log('Shipping breakdown:', shippingDisplayInfo)

// Manually test calculation
import { calculateOrderTotalCents } from '@lib/pricing'
console.log(calculateOrderTotalCents([orderData], {}, {}))
```

## Database Verification

### Check Payment Records:


```sql
-- View recent payment transactions
SELECT
  pt.id,
  pt.amount_cents,
  pt.created_at,
  o.id as order_id
FROM payment_transaction pt
JOIN order o ON pt.id = ANY(o.payment_transaction_ids)
ORDER BY pt.created_at DESC
LIMIT 10;

-- Verify no data corruption
SELECT COUNT(*) FROM payment_transaction
WHERE amount_cents IS NULL
   OR amount_cents < 0;
```

## Rollback Procedure

If critical issues are found:

1. **Immediate**: Revert deployment via Vercel dashboard
2. **Notify**: Alert affected merchants if any incorrect charges occurred
3. **Investigate**: Check logs for specific error patterns
4. **Fix**: Address issue in code
5. **Re-test**: Run through all test scenarios again
6. **Re-deploy**: Deploy fixed version


## Success Criteria

✅ **All Tests Pass** - No errors in any test scenario
✅ **Calculations Correct** - Spot-check 5-10 orders manually
✅ **No Console Errors** - Clean browser console
✅ **No Database Errors** - No null/invalid records
✅ **UI Displays Properly** - Shipping breakdowns make sense
✅ **Checkout Works** - Can complete test payments
✅ **Performance Good** - No slowdowns

## Questions or Issues?

If you encounter any unexpected behavior:

1. Check browser console for errors
2. Compare calculation manually using test examples
3. Verify test data matches expected format
4. Check if it's a display issue vs. calculation issue


**Note**: This change **reduces** merchant costs (good!), so any unexpected increases in totals should be investigated immediately.