# 🧪 PROMOTION INTEGRATION TESTING GUIDE

This guide provides comprehensive manual testing scenarios for the enhanced promotion system integration in the POS.

## 📋 PRE-TEST SETUP

### 1. Database Setup

```bash
# Run migrations
php artisan migrate

# Seed test data
php artisan db:seed --class=PromotionPermissionsSeeder
php artisan db:seed --class=TestPromotionSeeder
```

### 2. Test Data Requirements

-   **Categories**: Hair Care, Hair Styling, Skincare
-   **Products**: Shampoo (50 EGP), Conditioner (40 EGP), Hair Serum (80 EGP)
-   **Customers**: Test Customer 1, Test Customer 2, VIP Customer
-   **Branches**: Main Branch, Secondary Branch
-   **Vouchers**: SAVE10, VIP20, EXPIRED

---

## 🛒 SALES WINDOW TESTING

### Test Case 1: Basic Buy X Get Y Promotion

**Scenario**: Buy 2 Hair Care items, Get 1 Free

**Steps**:

1. Open Sales window
2. Add 2x Shampoo (50 EGP each) to cart
3. Add 1x Conditioner (40 EGP) to cart
4. Observe promotion panel

**Expected Results**:

-   ✅ Promotion "Buy 2 Get 1 Free - Hair Care" appears
-   ✅ Conditioner shows as FREE (0 EGP)
-   ✅ Total: 100 EGP (instead of 140 EGP)
-   ✅ Free item shows "FREE" badge
-   ✅ Promotion summary shows "Applied to 1 item(s)"

### Test Case 2: Multi-Category Buy X Get Y

**Scenario**: Buy 2 from Hair Care OR Hair Styling, Get 1 Hair Styling free

**Steps**:

1. Add 2x Shampoo to cart
2. Check if Hair Styling product is suggested for free
3. Add suggested Hair Styling product
4. Verify it becomes free

**Expected Results**:

-   ✅ Cross-category promotion applies
-   ✅ Hair Styling product shows as FREE
-   ✅ Promotion works across different categories

### Test Case 3: Customer-Specific Promotion

**Scenario**: VIP Customer gets 20% off

**Steps**:

1. Select "VIP Customer" from customer dropdown
2. Add items worth 100+ EGP
3. Observe promotion application

**Expected Results**:

-   ✅ "VIP Customer Promotion" appears
-   ✅ 20% discount applied to total
-   ✅ Switch to regular customer → promotion disappears
-   ✅ Message: "Promotion not available for this customer"

### Test Case 4: Voucher-Based Promotion

**Scenario**: Apply voucher code for additional discount

**Steps**:

1. Add items to cart
2. Enter voucher code "SAVE10" in promotion panel
3. Click "Apply"
4. Observe results

**Expected Results**:

-   ✅ Voucher validation success message
-   ✅ Additional 10% discount applied
-   ✅ Voucher shows as "Applied: SAVE10"
-   ✅ Invalid voucher shows error message

### Test Case 5: Branch-Specific Promotion

**Scenario**: Promotion only available at Main Branch

**Steps**:

1. Ensure you're at Main Branch
2. Add qualifying items
3. Switch to Secondary Branch
4. Observe promotion behavior

**Expected Results**:

-   ✅ Promotion applies at Main Branch
-   ✅ Promotion disappears when switching branches
-   ✅ Message: "Promotion not available at this branch"

### Test Case 6: Promotion Stacking

**Scenario**: Multiple stackable promotions

**Steps**:

1. Add items that qualify for multiple promotions
2. Observe which promotions apply
3. Check stacking behavior

**Expected Results**:

-   ✅ Stackable promotions apply together
-   ✅ Exclusive promotions stop further applications
-   ✅ Correct order: Exclusive first, then stackable

### Test Case 7: Selection Strategy Testing

**Scenario**: Test "Cheapest" vs "Highest" selection

**Steps**:

1. Create promotion with "Cheapest" strategy
2. Add Shampoo (50 EGP) and Hair Serum (80 EGP)
3. Verify cheapest item gets discount
4. Change strategy to "Highest"
5. Verify highest item gets discount

**Expected Results**:

-   ✅ "Cheapest" strategy: Shampoo gets discount
-   ✅ "Highest" strategy: Hair Serum gets discount
-   ✅ Strategy affects which items are discounted

---

## 🔄 RETURN WINDOW TESTING

### Test Case 8: Return Promotional Item

**Scenario**: Return item that was part of promotion

**Steps**:

1. Complete sale with promotion applied
2. Open Return window
3. Select promotional item for return
4. Process return

**Expected Results**:

-   ✅ Refund amount = net paid amount (after discount)
-   ✅ No new promotions applied during return
-   ✅ Return summary shows original promotion info
-   ✅ Stock updated correctly

### Test Case 9: Return Free Item

**Scenario**: Return item that was free due to promotion

**Steps**:

1. Complete sale with free item from promotion
2. Return the free item
3. Process return

**Expected Results**:

-   ✅ No refund amount for free item
-   ✅ Return summary shows "Free item - no refund"
-   ✅ Stock updated correctly

---

## ♻️ EXCHANGE WINDOW TESTING

### Test Case 10: Exchange with New Promotions

**Scenario**: Exchange promotional item for new items

**Steps**:

1. Complete sale with promotion
2. Open Exchange window
3. Return promotional item
4. Add new items to cart
5. Apply new promotions to new items

**Expected Results**:

-   ✅ Return side: Original promotion preserved
-   ✅ New side: New promotions apply to new items
-   ✅ Net difference calculated correctly
-   ✅ Receipt shows both sides clearly

### Test Case 11: Exchange to Different Branch

**Scenario**: Exchange item at different branch

**Steps**:

1. Complete sale at Main Branch
2. Exchange at Secondary Branch
3. Add new items
4. Check promotion availability

**Expected Results**:

-   ✅ Only Secondary Branch promotions apply
-   ✅ Original promotion info preserved for return
-   ✅ Branch-specific promotions work correctly

---

## 🧮 EDGE CASES TESTING

### Test Case 12: Promotion Expiry During Session

**Scenario**: Promotion expires while user is in middle of transaction

**Steps**:

1. Start transaction with active promotion
2. Simulate promotion expiry (or wait if using real expiry)
3. Try to complete transaction

**Expected Results**:

-   ✅ Warning message about expired promotion
-   ✅ Promotion removed from cart
-   ✅ Totals recalculated without promotion
-   ✅ User can still complete transaction

### Test Case 13: Voucher Usage Limit Exceeded

**Scenario**: Voucher has reached usage limit

**Steps**:

1. Use voucher multiple times (if limit is low)
2. Try to use again
3. Observe behavior

**Expected Results**:

-   ✅ Error message: "Voucher usage limit exceeded"
-   ✅ Voucher not applied
-   ✅ Other promotions still work

### Test Case 14: Manual Discount Conflict

**Scenario**: Item has manual discount and promotion applies

**Steps**:

1. Apply manual discount to item
2. Add items to trigger promotion on same item
3. Observe conflict handling

**Expected Results**:

-   ✅ Warning: "Manual discount overridden by promotion"
-   ✅ Promotion discount replaces manual discount
-   ✅ User can choose to keep manual discount

### Test Case 15: Stock Validation with Promotions

**Scenario**: Promotion tries to give free item that's out of stock

**Steps**:

1. Set item stock to 0
2. Trigger promotion that would give that item free
3. Observe behavior

**Expected Results**:

-   ✅ Promotion doesn't apply if free item out of stock
-   ✅ Warning message about stock availability
-   ✅ Alternative suggestions if available

---

## 📊 RECEIPT & REPORTING TESTING

### Test Case 16: Receipt Generation

**Scenario**: Generate receipt with promotions

**Steps**:

1. Complete sale with multiple promotions
2. Generate receipt
3. Check receipt content

**Expected Results**:

-   ✅ Receipt shows "Promotions Applied" section
-   ✅ Each promotion listed with summary
-   ✅ Free items shown as 0.00 EGP
-   ✅ Discounted items show correct prices
-   ✅ Total calculations correct

### Test Case 17: Promotion Analytics

**Scenario**: Check promotion reports

**Steps**:

1. Complete several transactions with promotions
2. Go to Promotion Reports
3. Check analytics data

**Expected Results**:

-   ✅ Promotion usage counts correctly
-   ✅ Revenue impact calculated
-   ✅ Customer targeting data accurate
-   ✅ Branch performance data correct

---

## 🔧 TECHNICAL VALIDATION

### Test Case 18: API Integration

**Scenario**: Test promotion API endpoints

**Steps**:

1. Use browser dev tools to monitor API calls
2. Perform various promotion actions
3. Check API responses

**Expected Results**:

-   ✅ `/api/pos/promotions/preview` returns correct data
-   ✅ `/api/pos/promotions/apply` processes correctly
-   ✅ Error handling works for invalid requests
-   ✅ Response times acceptable (< 500ms)

### Test Case 19: Performance Testing

**Scenario**: Test with large number of promotions

**Steps**:

1. Create 50+ active promotions
2. Add items to cart
3. Measure response times

**Expected Results**:

-   ✅ System remains responsive
-   ✅ Promotion evaluation completes quickly
-   ✅ No memory leaks or performance degradation

### Test Case 20: Data Consistency

**Scenario**: Verify data integrity

**Steps**:

1. Complete transactions with promotions
2. Check database records
3. Verify invoice data

**Expected Results**:

-   ✅ Promotion data stored correctly in database
-   ✅ Invoice records include promotion info
-   ✅ Voucher usage tracked accurately
-   ✅ Customer targeting data preserved

---

## ✅ ACCEPTANCE CRITERIA CHECKLIST

-   [ ] **Sales Flow**: Promotions apply correctly to qualifying carts
-   [ ] **Multi-Category**: Buy X Get Y works across multiple categories
-   [ ] **Customer Targeting**: Specific customer promotions work correctly
-   [ ] **Branch Scoping**: Branch-specific promotions enforced
-   [ ] **Voucher Integration**: Voucher-based promotions function properly
-   [ ] **Return Logic**: Returns handle promotional items correctly
-   [ ] **Exchange Logic**: Exchanges preserve original promotions and apply new ones
-   [ ] **Receipt Generation**: Receipts show promotion information accurately
-   [ ] **Error Handling**: Invalid promotions handled gracefully
-   [ ] **Performance**: System remains responsive with promotions
-   [ ] **Data Integrity**: All promotion data stored and retrieved correctly
-   [ ] **User Experience**: Promotions enhance rather than complicate POS workflow

---

## 🐛 COMMON ISSUES & SOLUTIONS

### Issue: Promotion not applying

**Solution**: Check customer eligibility, branch scope, and date range

### Issue: Free items not showing correctly

**Solution**: Verify selection strategy and item availability

### Issue: Voucher not working

**Solution**: Check voucher validity, usage limits, and customer targeting

### Issue: Performance issues

**Solution**: Check database indexes and query optimization

### Issue: Receipt formatting problems

**Solution**: Verify promotion data structure in invoice generation

---

## 📝 TEST EXECUTION LOG

| Test Case | Status | Notes | Tester | Date |
| --------- | ------ | ----- | ------ | ---- |
| 1         | ⏳     |       |        |      |
| 2         | ⏳     |       |        |      |
| 3         | ⏳     |       |        |      |
| ...       | ⏳     |       |        |      |

**Legend**: ✅ Pass | ❌ Fail | ⏳ Pending | ⚠️ Partial