# Manual Testing Guide for Item Search API

## Prerequisites
1. Start the API server: `npm run start:dev`
2. Obtain a JWT token by logging in
3. Use a tool like curl, Postman, or Thunder Client

## Test Cases

### Test 1: Basic Search (Valid Query)
```bash
curl -X GET "http://localhost:3000/items/search?q=rice" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Status: 200 OK
- Response: Array of items matching "rice" in code, name, or description
- Max 10 items returned

---

### Test 2: Case-Insensitive Search
```bash
# Uppercase
curl -X GET "http://localhost:3000/items/search?q=RICE" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Lowercase
curl -X GET "http://localhost:3000/items/search?q=rice" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Mixed case
curl -X GET "http://localhost:3000/items/search?q=RiCe" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- All three queries should return the same results
- Case should not affect matching

---

### Test 3: Partial Match
```bash
curl -X GET "http://localhost:3000/items/search?q=bas" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Returns items containing "bas" anywhere in code, name, or description
- Example: "RICE-BASMATI-001", "Basmati Rice", etc.

---

### Test 4: Query Too Short (< 2 characters)
```bash
# Single character
curl -X GET "http://localhost:3000/items/search?q=r" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Empty query
curl -X GET "http://localhost:3000/items/search?q=" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# No query parameter
curl -X GET "http://localhost:3000/items/search" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Status: 200 OK
- Response: `[]` (empty array)

---

### Test 5: Special Characters (Regex Injection Prevention)
```bash
# Parentheses
curl -X GET "http://localhost:3000/items/search?q=rice(premium)" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Asterisk (would match everything if not escaped)
curl -X GET "http://localhost:3000/items/search?q=.*" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Brackets
curl -X GET "http://localhost:3000/items/search?q=item[test]" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Dollar sign and caret
curl -X GET "http://localhost:3000/items/search?q=^test$" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Status: 200 OK
- No server errors
- Special characters treated as literal characters, not regex operators
- Returns items matching the literal string

---

### Test 6: No Results
```bash
curl -X GET "http://localhost:3000/items/search?q=nonexistentitem12345" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Status: 200 OK
- Response: `[]` (empty array)

---

### Test 7: Result Limiting (10 items max)
```bash
# Search for a common term that matches many items
curl -X GET "http://localhost:3000/items/search?q=rice" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Status: 200 OK
- Response: Array with maximum 10 items
- Even if more items match, only 10 are returned

---

### Test 8: Authentication Required
```bash
# Without Authorization header
curl -X GET "http://localhost:3000/items/search?q=rice"
```

**Expected Result:**
- Status: 401 Unauthorized
- Error message about missing or invalid token

---

### Test 9: Search by Item Code
```bash
curl -X GET "http://localhost:3000/items/search?q=RICE-001" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Returns items with "RICE-001" in their itemCode

---

### Test 10: Search by Item Name
```bash
curl -X GET "http://localhost:3000/items/search?q=basmati" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Returns items with "basmati" in their itemName

---

### Test 11: Search by Description
```bash
curl -X GET "http://localhost:3000/items/search?q=premium" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Result:**
- Returns items with "premium" in their description

---

## Response Format

Successful responses should follow this format:

```json
[
  {
    "_id": "507f1f77bcf86cd799439011",
    "itemCode": "RICE-BASMATI-001",
    "itemName": "Premium Basmati Rice",
    "description": "High quality basmati rice from India",
    "bagWeightKg": 25,
    "unit": "BAG/1x25kg",
    "brand": "Premium Brand",
    "barcode": "1234567890",
    "countryOfOrigin": "India",
    "blend": null,
    "grainType": "Long Grain",
    "varietyType": "Basmati",
    "processType": "Polished",
    "packing": "Bag",
    "variant": null,
    "riceName": "Basmati",
    "category": "Rice",
    "normalizedName": "premium basmati rice",
    "status": "Active",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z"
  }
]
```

---

## How to Get JWT Token

1. Login to get token:
```bash
curl -X POST "http://localhost:3000/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
```

2. Copy the `access_token` from the response
3. Use it in the Authorization header: `Bearer YOUR_TOKEN_HERE`

---

## Troubleshooting

### Issue: 401 Unauthorized
- **Cause**: Missing or invalid JWT token
- **Solution**: Login again to get a fresh token

### Issue: Empty results when items should exist
- **Cause**: Query might be < 2 characters or no items match
- **Solution**: Check query length and verify items exist in database

### Issue: Server error with special characters
- **Cause**: This should NOT happen - regex escaping should prevent this
- **Solution**: If this occurs, there's a bug in the implementation

### Issue: More than 10 results returned
- **Cause**: This should NOT happen - limit is enforced
- **Solution**: If this occurs, there's a bug in the implementation

---

## Performance Testing

To test performance with many results:

```bash
# Time the request
time curl -X GET "http://localhost:3000/items/search?q=rice" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Expected Performance:**
- Response time: < 300ms for typical datasets
- Consistent performance regardless of total items in database (due to limit)

---

## Integration with Frontend

Once manual testing is complete, the frontend can integrate using:

```typescript
// lib/api.ts
export async function searchItems(query: string): Promise<ItemRecord[]> {
  if (!query || query.length < 2) return [];
  return JSON.parse(
    await apiFetch(`/items/search?q=${encodeURIComponent(query)}`)
  ) as ItemRecord[];
}
```

Remember to:
1. Use `encodeURIComponent()` to properly encode the query
2. Debounce the search input (300ms recommended)
3. Show loading indicator during API call
4. Handle empty results gracefully