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

# 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

./scripts/test-vtl.sh

Manual Testing

Test 1: List Libraries (Initially Empty)

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

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

Test 2: Create a VTL Library

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:

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

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

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

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

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:

{
  "task_id": "uuid-here"
}

Check Task Status:

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)

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

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

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

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

  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