calypso/VTL-TESTING-GUIDE.md

# VTL Testing Guide

This guide provides step-by-step instructions for testing the Virtual Tape Library (VTL) endpoints.

## Prerequisites

1. **API Server Running**: The Calypso API should be running on `http://localhost:8080`
2. **Authentication Token**: You need a valid JWT token (get it via login)
3. **Backing Store Directory**: Ensure `/var/lib/calypso/vtl` exists or is writable

## Quick Start

### 1. Get Authentication Token

```bash
# Login and save token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')

# Save to file for scripts
echo "$TOKEN" > /tmp/calypso-test-token
```

### 2. Run Automated Tests

```bash
./scripts/test-vtl.sh
```

## Manual Testing

### Test 1: List Libraries (Initially Empty)

```bash
curl http://localhost:8080/api/v1/tape/vtl/libraries \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Expected**: Empty array `{"libraries": []}`

### Test 2: Create a VTL Library

```bash
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "vtl-test-01",
    "description": "Test Virtual Tape Library",
    "backing_store_path": "/var/lib/calypso/vtl",
    "slot_count": 10,
    "drive_count": 2
  }' | jq .
```

**Expected Response**:
```json
{
  "id": "uuid-here",
  "name": "vtl-test-01",
  "description": "Test Virtual Tape Library",
  "mhvtl_library_id": 1,
  "backing_store_path": "/var/lib/calypso/vtl/vtl-test-01",
  "slot_count": 10,
  "drive_count": 2,
  "is_active": true,
  "created_at": "...",
  "updated_at": "...",
  "created_by": "..."
}
```

**What Happens**:
- Creates directory: `/var/lib/calypso/vtl/vtl-test-01/tapes/`
- Creates 2 virtual drives in database
- Creates 10 virtual tapes (V00001 through V00010) with empty image files
- Each tape is 800 GB (LTO-8 default)

### Test 3: Get Library Details

```bash
LIBRARY_ID="your-library-id-here"

curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Expected**: Full library details with drives and tapes arrays

### Test 4: List Drives

```bash
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/drives \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Expected**: Array of 2 drives with status "idle"

### Test 5: List Tapes

```bash
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/tapes \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Expected**: Array of 10 tapes with barcodes V00001-V00010

### Test 6: Load a Tape

```bash
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/load \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slot_number": 1,
    "drive_number": 1
  }' | jq .
```

**Expected Response**:
```json
{
  "task_id": "uuid-here"
}
```

**Check Task Status**:
```bash
TASK_ID="task-id-from-above"

curl http://localhost:8080/api/v1/tasks/$TASK_ID \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**After Load**:
- Tape status changes from "idle" to "in_drive"
- Drive status changes from "idle" to "ready"
- Drive's `current_tape_id` is set

### Test 7: Get Library (After Load)

```bash
curl http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
  -H "Authorization: Bearer $TOKEN" | jq .
```

**Verify**:
- Drive 1 shows status "ready" and has `current_tape_id`
- Tape in slot 1 shows status "in_drive"

### Test 8: Unload a Tape

```bash
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/unload \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "drive_number": 1,
    "slot_number": 1
  }' | jq .
```

**After Unload**:
- Tape status changes back to "idle"
- Drive status changes back to "idle"
- Drive's `current_tape_id` is cleared

### Test 9: Create Additional Tape

```bash
curl -X POST http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID/tapes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "barcode": "CUSTOM001",
    "slot_number": 11,
    "tape_type": "LTO-8",
    "size_gb": 15000
  }' | jq .
```

**Expected**: New tape created with custom barcode and 15 TB size

### Test 10: Delete Library (Optional)

**Note**: Library must be inactive first

```bash
# First, deactivate library (would need update endpoint or direct DB)
# Then delete:
curl -X DELETE http://localhost:8080/api/v1/tape/vtl/libraries/$LIBRARY_ID \
  -H "Authorization: Bearer $TOKEN" | jq .
```

## Verification Checklist

- [ ] Library creation succeeds
- [ ] Directory structure created correctly
- [ ] Initial tapes created (10 tapes with barcodes V00001-V00010)
- [ ] Drives created (2 drives, status "idle")
- [ ] Load operation works (tape moves to drive, status updates)
- [ ] Unload operation works (tape returns to slot, status updates)
- [ ] Custom tape creation works
- [ ] Task status tracking works for async operations
- [ ] Database state persists correctly

## Troubleshooting

### Error: "failed to create backing store directory"
- **Solution**: Ensure `/var/lib/calypso/vtl` exists and is writable:
  ```bash
  sudo mkdir -p /var/lib/calypso/vtl
  sudo chown $USER:$USER /var/lib/calypso/vtl
  ```

### Error: "library not found"
- **Solution**: Check that you're using the correct library ID from the create response

### Error: "tape not found in slot"
- **Solution**: Verify slot number exists and has a tape. List tapes first to see available slots.

### Error: "no tape in drive"
- **Solution**: Load a tape to the drive before attempting to unload.

## Expected File Structure

After creating a library, you should see:

```
/var/lib/calypso/vtl/vtl-test-01/
└── tapes/
    ├── V00001.img
    ├── V00002.img
    ├── V00003.img
    └── ... (10 files total)
```

Each `.img` file is an empty tape image file (0 bytes initially).

## Next Steps

After successful testing:
1. Verify database records in `virtual_tape_libraries`, `virtual_tape_drives`, `virtual_tapes`
2. Test with multiple libraries
3. Test concurrent load/unload operations
4. Verify task status tracking
5. Check audit logs for all operations