Sankofa/crossplane-provider-proxmox/MANUAL_TESTING.md

# Manual Testing Guide

This guide provides step-by-step instructions for manually testing the Proxmox provider.

## Prerequisites

- Kubernetes cluster with Crossplane installed
- Proxmox provider deployed
- ProviderConfig configured with valid credentials
- Access to Proxmox Web UI or API

## Test Scenarios

### 1. Tenant Tags Verification

**Objective**: Verify tenant tags are correctly applied and filtered.

#### Steps

1. **Create VM with tenant ID**:
```yaml
apiVersion: proxmox.sankofa.nexus/v1alpha1
kind: ProxmoxVM
metadata:
  name: test-vm-tenant
  labels:
    tenant-id: "test-tenant-123"
spec:
  forProvider:
    node: "test-node"
    name: "test-vm-tenant"
    cpu: 2
    memory: "4Gi"
    disk: "50Gi"
    storage: "local-lvm"
    network: "vmbr0"
    image: "100"
    site: "us-sfvalley"
  providerConfigRef:
    name: proxmox-provider-config
```

2. **Verify tag in Proxmox**:
   - Log into Proxmox Web UI
   - Find the created VM
   - Check Tags field
   - Should show: `tenant_test-tenant-123` (underscore, not colon)

3. **Verify tenant filtering**:
   - Use `ListVMs()` with tenant filter
   - Should only return VMs with matching tenant tag

4. **Cleanup**:
```bash
kubectl delete proxmoxvm test-vm-tenant
```

**Expected Results**:
- ✅ VM created with tag `tenant_test-tenant-123`
- ✅ Tag uses underscore separator
- ✅ Tenant filtering works correctly

---

### 2. API Adapter Authentication

**Objective**: Verify API authentication header format.

#### Steps

1. **Check TypeScript adapter code**:
   - Open `api/src/adapters/proxmox/adapter.ts`
   - Verify all 8 API calls use: `Authorization: PVEAPIToken ${token}`
   - Should NOT use: `Authorization: PVEAPIToken=${token}`

2. **Test API calls**:
   - Intercept network requests
   - Verify header format in all requests
   - Check all 8 endpoints:
     - `getNodes()`
     - `getVMs()`
     - `getResource()`
     - `createResource()`
     - `updateResource()`
     - `deleteResource()`
     - `getMetrics()`
     - `healthCheck()`

3. **Verify error messages**:
   - Test with invalid token
   - Verify clear error messages

**Expected Results**:
- ✅ All requests use correct header format (space, not equals)
- ✅ Authentication succeeds with valid token
- ✅ Clear error messages for auth failures

---

### 3. Proxmox Version Testing

**Objective**: Test compatibility across Proxmox versions.

#### Test on PVE 6.x

1. **Verify importdisk API detection**:
   - Create VM with cloud image
   - Check if importdisk is attempted
   - Verify graceful fallback if not supported

2. **Check version detection**:
   - Verify `SupportsImportDisk()` logic
   - Test error handling

#### Test on PVE 7.x

1. **Verify importdisk API**:
   - Should be supported
   - Test cloud image import

2. **Test all features**:
   - VM creation
   - Template cloning
   - Network validation

#### Test on PVE 8.x

1. **Verify compatibility**:
   - Test all features
   - Verify no breaking changes

**Expected Results**:
- ✅ Works correctly on all versions
- ✅ Graceful handling of API differences
- ✅ Appropriate error messages

---

### 4. Node Configuration Testing

**Objective**: Test multi-node deployments.

#### Steps

1. **Test multiple nodes**:
   - Deploy VMs to different nodes
   - Verify node selection works
   - Test node parameterization in compositions

2. **Test node health checks**:
   - Verify health check before VM creation
   - Test with unhealthy node
   - Verify appropriate error handling

3. **Test node parameterization**:
   - Use composition with node parameter
   - Verify node is set correctly

**Expected Results**:
- ✅ VMs deploy to correct nodes
- ✅ Health checks work correctly
- ✅ Parameterization works

---

### 5. Error Scenarios

**Objective**: Test error handling and recovery.

#### Test Cases

1. **Node Unavailable**:
   ```bash
   # Stop Proxmox node
   # Attempt to create VM
   # Verify error handling
   ```

2. **Storage Full**:
   ```bash
   # Fill storage to capacity
   # Attempt to create VM
   # Verify quota error
   ```

3. **Network Bridge Missing**:
   ```yaml
   # Use non-existent bridge
   network: "vmbr999"
   # Verify validation error
   ```

4. **Invalid Credentials**:
   ```yaml
   # Update ProviderConfig with wrong password
   # Verify authentication error
   ```

5. **Quota Exceeded**:
   ```yaml
   # Request resources exceeding quota
   # Verify quota error
   ```

**Expected Results**:
- ✅ Appropriate error messages
- ✅ No retry on non-retryable errors
- ✅ Retry on transient errors
- ✅ Proper cleanup on failure

---

### 6. Network Bridge Validation

**Objective**: Verify network bridge validation works.

#### Steps

1. **List available bridges**:
   ```bash
   # Check bridges on node
   kubectl get proxmoxvm -o yaml | grep network
   ```

2. **Test with existing bridge**:
   ```yaml
   network: "vmbr0"  # Should exist
   ```
   - Should succeed

3. **Test with non-existent bridge**:
   ```yaml
   network: "vmbr999"  # Should not exist
   ```
   - Should fail with clear error

4. **Verify validation timing**:
   - Check that validation happens before VM creation
   - Verify error in status conditions

**Expected Results**:
- ✅ Validation happens before VM creation
- ✅ Clear error messages
- ✅ No partial VM creation

---

### 7. Validation Rules

**Objective**: Test all validation rules.

#### Test Cases

1. **VM Name Validation**:
   - Test valid names
   - Test invalid characters
   - Test length limits

2. **Memory Validation**:
   - Test minimum (128 MB)
   - Test maximum (2 TB)
   - Test various formats

3. **Disk Validation**:
   - Test minimum (1 GB)
   - Test maximum (100 TB)
   - Test various formats

4. **CPU Validation**:
   - Test minimum (1)
   - Test maximum (1024)

5. **Image Validation**:
   - Test template ID format
   - Test volid format
   - Test image name format

**Expected Results**:
- ✅ All validation rules enforced
- ✅ Clear error messages
- ✅ Appropriate validation timing

---

## Test Checklist

Use this checklist to verify all functionality:

- [ ] Tenant tags created correctly
- [ ] Tenant filtering works
- [ ] API authentication works
- [ ] All 8 API endpoints work
- [ ] Works on PVE 6.x
- [ ] Works on PVE 7.x
- [ ] Works on PVE 8.x
- [ ] Multi-node deployment works
- [ ] Node health checks work
- [ ] Network bridge validation works
- [ ] All validation rules enforced
- [ ] Error handling works correctly
- [ ] Retry logic works
- [ ] Error messages are clear
- [ ] Status updates are accurate

---

## Reporting Issues

When reporting test failures, include:

1. **Test scenario**: Which test failed
2. **Steps to reproduce**: Detailed steps
3. **Expected behavior**: What should happen
4. **Actual behavior**: What actually happened
5. **Error messages**: Full error output
6. **Environment**: Proxmox version, Kubernetes version, etc.
7. **Logs**: Relevant logs from controller and Proxmox

---

## Success Criteria

All tests should:
- ✅ Complete without errors
- ✅ Produce expected results
- ✅ Have clear error messages when appropriate
- ✅ Clean up resources properly