quality_app-v2/documentation/ASSIGN_TO_BOX_TESTING_GUIDE.md

# Assign to Box Form - Testing & Verification Guide

## Test Environment Setup

### Prerequisites
1. Application running on [http://localhost:5000](http://localhost:5000)
2. Logged in as a Quality Operator
3. Access to FG Scan page (`/quality/fg_scan`)
4. Database with active boxes created
5. QZ Tray running for label printing

---

## Test Scenarios

## 🧪 Test 1: Form Appears When Scanning Good Product

### Prerequisite State
- FG Scan page loaded
- "Scan to Boxes" checkbox is **UNCHECKED**

### Steps
1. Enter Operator Code: `OP01`
2. Enter CP Code: `CP-123456789AB` (or any 15-char CP code)
3. Enter OC1 Code: `OC01`
4. Enter OC2 Code: `OC02`
5. Enter Defect Code: `000` (GOOD quality)
6. Click "Scan" button

### Expected Result
✅ Modal "Assign to Box" appears with:
- Title: "Assign to Box"
- CP Code displayed: "CP-123456789AB"
- Green button: "📦 Quick Box Label Creation"
- Separator: "━━━━━━━  OR  ━━━━━━━"
- Input field: "Scan Box Number" (focused, ready for input)
- Input field: "Quantity" (defaulted to 1)
- Buttons: "Skip" and "Assign to Box"

### HTML Elements to Verify
```javascript
// Check modal visibility
document.getElementById('boxAssignmentModal').style.display
// Expected: 'flex'

// Check CP code display
document.getElementById('modal-cp-code').textContent
// Expected: 'CP-123456789AB'

// Check box number input
document.getElementById('boxNumber').value
// Expected: '' (empty, ready for input)

// Check quantity input
document.getElementById('boxQty').value
// Expected: '1'
```

---

## 🧪 Test 2: Form Does Not Appear for Defective Products

### Prerequisite State
- FG Scan page loaded
- "Scan to Boxes" checkbox is **UNCHECKED**

### Steps
1. Enter Operator Code: `OP01`
2. Enter CP Code: `CP-123456789AB`
3. Enter OC1 Code: `OC01`
4. Enter OC2 Code: `OC02`
5. Enter Defect Code: `001` (DEFECTIVE - any non-000 code)
6. Click "Scan" button

### Expected Result
✅ Modal does **NOT** appear
✅ Page reloads (showing defective product recorded)
✅ Scans table updates to show defective product entry

### Verification
```javascript
// Modal should still be hidden
document.getElementById('boxAssignmentModal').style.display
// Expected: 'none'
```

---

## 🧪 Test 3: Assign Existing Box (Form Submission)

### Prerequisite State
- Modal is open (from Test 1)
- A box exists in database with number "BOX-001"
- Modal shows CP code "CP-123456789AB"

### Steps
1. In "Scan Box Number" field, enter: `BOX-001`
2. Verify "Quantity" field shows: `1`
3. Click "Assign to Box" button

### Expected Result
✅ Button shows loading state: "⏳ Assigning..."
✅ Server processes request
✅ Success message: "✅ CP CP-123456789AB assigned to box BOX-001!"
✅ Modal closes
✅ Page reloads after 1 second
✅ Scans table updates to show CP linked to BOX-001

### Database Verification
```sql
-- Verify CP is linked to box
SELECT cp_code, box_id FROM scanfg_orders 
WHERE cp_code = 'CP-123456789AB'
ORDER BY created_at DESC LIMIT 1;

-- Should show box_id populated for BOX-001
```

---

## 🧪 Test 4: Modify Quantity Before Assignment

### Prerequisite State
- Modal is open (from Test 1)
- Modal shows CP code
- A box "BOX-002" exists in database

### Steps
1. In "Scan Box Number" field, enter: `BOX-002`
2. Click on "Quantity" field
3. Clear current value and enter: `5`
4. Verify "Quantity" now shows: `5`
5. Click "Assign to Box" button

### Expected Result
✅ Button shows loading state: "⏳ Assigning..."
✅ Request includes: `{"quantity": 5}`
✅ Success message: "✅ CP CP-XXXXXXXXXX assigned to box BOX-002!"
✅ Database updated with quantity = 5
✅ Modal closes and page reloads

### Database Verification
```sql
-- Verify quantity was recorded
SELECT box_id, cp_code, quantity FROM box_contents 
WHERE cp_code = 'CP-XXXXXXXXXX' AND quantity = 5;
```

---

## 🧪 Test 5: Validation - Empty Box Number

### Prerequisite State
- Modal is open (from Test 1)
- "Scan Box Number" field is **EMPTY**

### Steps
1. Verify "Scan Box Number" field is empty
2. Click "Assign to Box" button

### Expected Result
⚠️ Validation triggered
⚠️ Warning message: "⚠️ Please enter a box number"
✅ Modal remains open
✅ No API request sent
✅ Button returns to normal state

---

## 🧪 Test 6: Validation - Invalid Quantity

### Prerequisite State
- Modal is open (from Test 1)
- "Scan Box Number" field contains: `BOX-003`

### Steps
1. Verify "Scan Box Number" has value: `BOX-003`
2. Click on "Quantity" field
3. Enter invalid value: `-1` (or `0` or `abc`)
4. Click "Assign to Box" button

### Expected Result
⚠️ Validation triggered
⚠️ Warning message: "⚠️ Please enter a valid quantity"
✅ Modal remains open
✅ No API request sent
✅ Button returns to normal state

### Test Cases for Quantity Validation
| Input Value | Validation Result | Expected Message |
|------------|------------------|------------------|
| `-1` | ❌ Invalid | "Please enter a valid quantity" |
| `0` | ❌ Invalid | "Please enter a valid quantity" |
| `abc` | ❌ Invalid | "Please enter a valid quantity" |
| `1.5` | ❌ Invalid | "Please enter a valid quantity" |
| `` (empty) | ❌ Invalid | "Please enter a valid quantity" |
| `1` | ✅ Valid | Proceed |
| `5` | ✅ Valid | Proceed |
| `100` | ✅ Valid | Proceed |

---

## 🧪 Test 7: Skip Assignment (Cancel Modal)

### Prerequisite State
- Modal is open (from Test 1)
- Modal shows CP code

### Steps
1. Click "Skip" button (gray button at bottom)

### Expected Result
✅ Message: "✅ Scan recorded without box assignment"
✅ Modal closes immediately
✅ Page reloads after 500ms
✅ CP remains in database but **NOT linked** to any box

### Database Verification
```sql
-- Verify CP exists but box_id is NULL
SELECT cp_code, box_id FROM scanfg_orders 
WHERE cp_code = 'CP-XXXXXXXXXX'
ORDER BY created_at DESC LIMIT 1;
-- Expected: box_id = NULL
```

---

## 🧪 Test 8: Close Modal with X Button

### Prerequisite State
- Modal is open (from Test 1)
- Modal shows CP code

### Steps
1. Click the "×" (close) button in top-right of modal

### Expected Result
✅ Modal closes
✅ Page reloads after 500ms
✅ CP remains in database but **NOT linked** to any box

---

## 🧪 Test 9: Barcode Scan Into Box Number Field

### Prerequisite State
- Modal is open (from Test 1)
- "Scan Box Number" field has focus (should be automatic)
- Box barcode label available: `BOX-004`

### Steps
1. Focus on "Scan Box Number" field
2. Scan box barcode (e.g., with barcode scanner)
3. Barcode should populate field with: `BOX-004`
4. Field should automatically lose focus (if barcode scanner includes carriage return)
5. Click "Assign to Box" button

### Expected Result
✅ Barcode value appears in field
✅ Field accepts scan input correctly
✅ Assignment proceeds normally
✅ Success message displayed
✅ Modal closes and page reloads

---

## 🧪 Test 10: Quick Box Creation Button

### Prerequisite State
- Modal is open (from Test 1)
- Modal shows CP code: `CP-123456789AB`

### Steps
1. Click "📦 Quick Box Label Creation" button (green button)

### Expected Result
✅ Button shows loading state
✅ API request sent to create new box
✅ New box number generated (e.g., `BOX-NNNNNN`)
✅ Box label PDF generated
✅ QZ Tray prints label
✅ CP linked to new box
✅ Success message: "✅ Box [BOX-NNNNNN] created and printed!"
✅ Modal closes
✅ Page reloads
✅ Scans table shows CP with new box assignment

---

## 🧪 Test 11: Barcode Scanner Auto-Tab Behavior

### Prerequisite State
- Modal is open from Test 1
- "Scan Box Number" field has focus

### Steps
1. Configure barcode scanner to include carriage return on scan
2. Scan box barcode
3. Observe field behavior after scan

### Expected Result
✅ Barcode populates field
✅ Field loses focus (or browser moves to next field)
✅ Value is retained in input
✅ Ready for next input or button click

### Note
This depends on barcode scanner configuration. Some scanners include Tab or Enter. The field should handle both gracefully.

---

## 🧪 Test 12: Error Handling - Box Not Found

### Prerequisite State
- Modal is open (from Test 1)
- Database has boxes: `BOX-001`, `BOX-002`, `BOX-003`

### Steps
1. In "Scan Box Number" field, enter: `BOX-NONEXISTENT`
2. Click "Assign to Box" button

### Expected Result
❌ Error message: "❌ Error: Box BOX-NONEXISTENT not found"
✅ Modal remains open
✅ Button returns to normal state
✅ No database changes

### Verification
```javascript
// Check error was caught
console.log() should show:
// "Error: Box BOX-NONEXISTENT not found"
```

---

## 🧪 Test 13: Error Handling - Server Error

### Prerequisite State
- Modal is open (from Test 1)
- Backend API temporarily unavailable

### Steps
1. Stop backend service
2. In "Scan Box Number" field, enter: `BOX-001`
3. Click "Assign to Box" button

### Expected Result
❌ Error message: "❌ Error: [error details]"
✅ Modal remains open
✅ Button returns to normal state
✅ User can retry after server is back up

---

## 🧪 Test 14: Modal Layout Responsiveness

### Prerequisite State
- Modal is open (from Test 1)

### Steps

#### Desktop (1920x1080)
1. Open modal on desktop browser
2. Verify all elements visible without scrolling
3. Buttons aligned properly at bottom

#### Tablet (768x1024)
1. Open modal on tablet (or resize browser)
2. Verify modal is 90% of viewport width (max-width: 90%)
3. All form elements fit within modal
4. Buttons remain visible

#### Mobile (375x667)
1. Open modal on mobile (or resize browser)
2. Verify modal scales down to 90% width
3. Form elements stack vertically
4. Buttons visible at bottom
5. No horizontal scrolling needed

### Expected Result
✅ Modal is responsive
✅ No elements cut off
✅ All buttons clickable
✅ Fields readable on all screen sizes

---

## 🧪 Test 15: Field Focus & Tab Navigation

### Prerequisite State
- Modal is open (from Test 1)

### Steps
1. Verify "Scan Box Number" field has automatic focus
2. Press Tab → Field should move to "Quantity" field
3. Press Tab → Field should move to "Skip" button
4. Press Tab → Field should move to "Assign to Box" button
5. Press Shift+Tab → Navigate backwards

### Expected Result
✅ Tab order is logical: Box Number → Quantity → Skip → Assign
✅ Focus outline visible on each element
✅ All elements are keyboard accessible
✅ Enter key on button triggers action

---

## 🧪 Test 16: Form Reset After Assignment

### Prerequisite State
- Previous assignment completed successfully
- Modal is open again for new CP code

### Steps
1. Verify "Scan Box Number" field is **EMPTY**
2. Verify "Quantity" field is **1** (default)
3. Verify new CP code is displayed

### Expected Result
✅ Form fields are cleared between assignments
✅ Box number field is ready for next input
✅ Quantity is reset to default (1)
✅ Correct CP code displayed

### Verification
```javascript
// Check that fields are cleared
document.getElementById('boxNumber').value // Expected: ''
document.getElementById('boxQty').value // Expected: '1' (default)
document.getElementById('modal-cp-code').textContent // Expected: new CP code
```

---

## 🧪 Test 17: Multiple Rapid Submissions

### Prerequisite State
- Modal is open for CP: `CP-AAAAAAAAAAAA`
- Box `BOX-005` exists in database

### Steps
1. Rapidly click "Assign to Box" button **2-3 times** in succession
2. Observe server behavior

### Expected Result
✅ First click processes normally
✅ Button disabled after first click ("⏳ Assigning...")
✅ Second/third clicks ignored
✅ Only ONE database entry created
✅ No duplicate assignments
✅ Button re-enabled after response

### Verification
```sql
-- Check only ONE entry was created
SELECT COUNT(*) FROM box_contents 
WHERE cp_code = 'CP-AAAAAAAAAAAA' AND box_id = (
    SELECT id FROM boxes_crates WHERE box_number = 'BOX-005'
);
-- Expected: 1 (not 2 or 3)
```

---

## 🧪 Test 18: Form Data Validation

### Prerequisite State
- Modal is open with CP code: `CP-TESTCPCODE1`

### Steps
1. Inspect network requests
2. Submit form with:
   - Box Number: `BOX-TEST-001`
   - Quantity: `3`
3. Verify request payload

### Expected Result
✅ POST request to: `/quality/api/assign-cp-to-box`
✅ Content-Type: `application/json`
✅ Request body:
```json
{
  "box_number": "BOX-TEST-001",
  "cp_code": "CP-TESTCPCODE1",
  "quantity": 3
}
```

### Verification
```javascript
// Open DevTools → Network tab
// Look for POST request
// Check Request Body shows correct JSON
```

---

## Form Elements Summary

| Element | ID | Type | Required | Default | Validation |
|---------|----|----|----------|---------|-----------|
| Modal Container | `boxAssignmentModal` | div | N/A | hidden | CSS display |
| CP Code Display | `modal-cp-code` | span | N/A | - | JS populated |
| Create Box Button | `quickBoxLabel` | button | N/A | - | Click handler |
| Box Number Input | `boxNumber` | text | ✅ Yes | empty | Non-empty |
| Quantity Input | `boxQty` | number | ✅ Yes | 1 | Min 1, numeric |
| Skip Button | `cancelModal` | button | N/A | - | Click handler |
| Assign Button | `assignToBox` | button | N/A | - | Click handler |

---

## Quick Checklist

Before deploying to production, verify:

- [ ] Modal appears on defect code 000
- [ ] Modal hidden on other defect codes
- [ ] Box number input accepts manual entry
- [ ] Box number input accepts barcode scans
- [ ] Quantity field defaults to 1
- [ ] Quantity validation works for all cases
- [ ] "Assign to Box" button validates both fields
- [ ] "Assign to Box" button shows loading state
- [ ] "Skip" button works and reloads page
- [ ] "×" close button works
- [ ] Error handling for non-existent boxes
- [ ] Database updates correctly with box_id and quantity
- [ ] Multiple rapid clicks don't create duplicates
- [ ] Form resets between submissions
- [ ] Tab navigation works correctly
- [ ] Modal is responsive on all screen sizes
- [ ] Network request has correct payload
- [ ] Success/error messages display properly
- [ ] Page reloads after successful assignment
- [ ] CP location history recorded correctly

---

## Troubleshooting

### Issue: Modal doesn't appear when scanning with 000

**Possible Causes:**
1. Defect code is not exactly "000" (check for spaces, leading zeros)
2. `scanToBoxesEnabled` is false (checkbox not checked)
3. Form validation is failing (check console for validation errors)
4. JavaScript error in form submission (check browser console)

**Debug Steps:**
```javascript
// In browser console
console.log('scanToBoxesEnabled:', scanToBoxesEnabled);
console.log('Defect code value:', document.getElementById('defect_code').value);
// Check if form submitted via AJAX or regular POST
```

### Issue: Form fields have wrong IDs

**Problem:** Old code references `scan-box-input` instead of `boxNumber`

**Solution:** Update all references:
```javascript
// OLD (broken)
document.getElementById('scan-box-input').value

// NEW (correct)
document.getElementById('boxNumber').value
```

### Issue: Button doesn't respond to clicks

**Possible Causes:**
1. Event listener not attached (script not loaded)
2. Element ID mismatch
3. JavaScript error preventing handler execution

**Debug Steps:**
```javascript
// In browser console
let btn = document.getElementById('assignToBox');
console.log('Button found:', !!btn);
console.log('Button listeners:', getEventListeners(btn)); // Chrome only
```

### Issue: Database not updating after assignment

**Possible Causes:**
1. API endpoint not found (404 error)
2. Database connection error
3. SQL insert/update failing
4. User doesn't have required permissions

**Debug Steps:**
1. Check browser Network tab for request/response
2. Check server logs for SQL errors
3. Verify box exists in database
4. Verify CP code is valid

---

## Related Documentation

- [ASSIGN_TO_BOX_FORM_ANALYSIS.md](ASSIGN_TO_BOX_FORM_ANALYSIS.md)
- [BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md](BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md)
- [FG_SCAN_BOX_WORKFLOW_DOCUMENTATION_INDEX.md](FG_SCAN_BOX_WORKFLOW_DOCUMENTATION_INDEX.md)