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
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

// 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

// 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

-- 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

-- 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

-- 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

// 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

// 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

-- 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:

{
  "box_number": "BOX-TEST-001",
  "cp_code": "CP-TESTCPCODE1",
  "quantity": 3
}

Verification

// 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:

// 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:

// 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:

// 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
• BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md
• FG_SCAN_BOX_WORKFLOW_DOCUMENTATION_INDEX.md