resf-testing-repo/README.md

# Rocky Linux Testing Framework

Simple, portable Sparrowdo testing framework for Rocky Linux.

## Overview

This framework provides automated testing for Rocky Linux:

- **VM Isolation**: Each test runs in a fresh VM
- **Parallel Execution**: Run multiple tests concurrently
- **Fast Provisioning**: Linked clones (copy-on-write) for speed
- **Bootstrap Once**: Golden image approach saves time

Two implementations available:
- **Ansible**: Provider-aware, structured roles, better for automation (recommended)
- **Shell Scripts**: Simple scripts, easy to integrate anywhere (libvirt only)

## Prerequisites

```bash
sudo dnf install -y qemu-kvm libvirt virt-install guestfs-tools rakudo ansible
sudo systemctl enable --now libvirtd
sudo usermod -a -G libvirt $(whoami)
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N ""
```

## Quick Start

### Ansible (Recommended)

```bash
cd ansible

# 1. Add your tests to vars/test-definitions.yml
# 2. Build golden image (interactive prompt for Rocky version)
ansible-playbook playbooks/libvirt/build-golden-image.yml

# 3. Run all tests
ansible-playbook playbooks/run-tests.yml

# 4. Run specific test
ansible-playbook playbooks/run-tests.yml -e "test_filter=Sparky_Knot"
```

### Shell Scripts

```bash
# Download base image
BASE=$(./scripts/download-image.sh \
  https://download.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud-Base.latest.x86_64.qcow2)

# Build golden image
./scripts/build-golden.sh "$BASE" /var/lib/libvirt/images/golden.qcow2

# Run test
./scripts/run-test.sh my-test \
  https://github.com/your-org/test-repo.git \
  /var/lib/libvirt/images/golden.qcow2
```

## How It Works

```
Download QCOW2 → Build Golden Image → Run Tests → Cleanup
                 (bootstrap once)     (parallel)
```

**Golden Image Creation:**
1. Copy base QCOW2 image
2. Install Raku, Sparrowdo via virt-customize
3. Create `rocky` user with sudo and SSH keys
4. Boot VM and run `sparrowdo --bootstrap` (once)
5. Shutdown, save as golden image

**Test Execution:**
1. Provision VM as linked clone (~1 second)
2. Clone test repository
3. Run `sparrowdo --no_sudo`
4. Cleanup VM

## Directory Structure

```
.
├── ansible/                      # Ansible implementation (provider-aware)
│   ├── inventory/
│   │   ├── hosts.yml            # Provider groups (libvirt, aws, azure)
│   │   └── group_vars/          # Provider-specific settings
│   ├── vars/
│   │   └── test-definitions.yml # Centralized test list
│   ├── playbooks/
│   │   ├── libvirt/             # Libvirt-specific playbooks
│   │   │   └── build-golden-image.yml
│   │   ├── aws/                 # AWS playbooks (future)
│   │   ├── azure/               # Azure playbooks (future)
│   │   └── run-tests.yml        # Provider-agnostic test runner
│   ├── tasks/
│   │   └── run-test-with-infrastructure.yml
│   └── roles/                   # Reusable roles
│       ├── download_image/
│       ├── golden_image/
│       ├── bootstrap_sparrowdo/
│       ├── provision_vm/
│       ├── run_test/
│       └── cleanup_vm/
├── scripts/                     # Shell scripts (libvirt only)
│   ├── download-image.sh
│   ├── build-golden.sh
│   ├── run-test.sh
│   └── cleanup_vm.sh
└── docs/
    ├── ANSIBLE-GUIDE.md
    └── BOOTSTRAP-APPROACH.md
```

## Ansible Roles

| Role | Purpose |
|------|---------|
| `download_image` | Download and cache QCOW2 images |
| `golden_image` | Build golden image with virt-customize |
| `bootstrap_sparrowdo` | Bootstrap Sparrowdo on golden image |
| `provision_vm` | Provision VM as linked clone |
| `run_test` | Execute test workflow |
| `cleanup_vm` | Clean up VMs and disks |

## Shell Scripts

| Script | Purpose |
|--------|---------|
| `download-image.sh` | Download and cache QCOW2 images |
| `build-golden.sh` | Build golden image |
| `bootstrap_golden.sh` | Bootstrap Sparrowdo |
| `run-test.sh` | Run single test |
| `provision_vm.sh` | Create VM |
| `cleanup_vm.sh` | Cleanup single VM |
| `cleanup-all.sh` | Cleanup multiple VMs |

## Test Definitions

### Ansible
Edit `ansible/vars/test-definitions.yml` to add tests:

```yaml
tests:
  - name: "Sparky_Knot"
    repo_url: "https://git.resf.org/testing/Sparky_Knot.git"
    # Optional: branch, timeout

  - name: "ssh-test"
    repo_url: "https://github.com/your-org/ssh-test.git"
    branch: "develop"
    timeout: 600
```

### Test Repository Format

Your test repository needs `sparrowfile` or `main.raku`:

```raku
#!/usr/bin/env raku
use Sparrowdo;

task-run 'check-sshd', %(
    plugin => 'systemd-service',
    args => ['sshd', 'running']
);
```

## Configuration

### Ansible

**Provider Groups:**
- `inventory/hosts.yml` - Provider groups (libvirt, aws, azure)
- `inventory/group_vars/all.yml` - Settings for all providers
- `inventory/group_vars/libvirt.yml` - Libvirt-specific (VM resources, packages)
- `inventory/group_vars/aws.yml` - AWS-specific (future)
- `inventory/group_vars/azure.yml` - Azure-specific (future)

**Test Definitions:**
- `vars/test-definitions.yml` - Centralized test repository list

**Example override:**
```bash
ansible-playbook playbooks/run-tests.yml -e "vm_memory=4096"
```

### Shell Scripts
Pass parameters directly:
```bash
./scripts/provision_vm.sh <vm_name> <golden_image> [timeout]
```

## Documentation

- [Ansible Guide](docs/ANSIBLE-GUIDE.md) - Complete Ansible documentation
- [Bootstrap Approach](docs/BOOTSTRAP-APPROACH.md) - How golden image works

## Key Features

### Ansible Implementation
- **Provider-aware** - Supports libvirt, AWS, Azure (cloud providers in progress)
- **Interactive prompts** - No need to remember image URLs
- **Test definitions** - Centralized test list in `vars/test-definitions.yml`
- **Result tracking** - Shows passed/failed tests with summary report
- **Automatic cleanup** - Infrastructure cleaned up after each test

## Troubleshooting

```bash
# List VMs
virsh -c qemu:///system list --all

# Get VM IP
virsh -c qemu:///system domifaddr <vm-name>

# SSH to VM
ssh -i ~/.ssh/id_rsa rocky@<vm-ip>

# Ansible verbose mode
ansible-playbook playbooks/run-tests.yml -vvv

# Run specific test
ansible-playbook playbooks/run-tests.yml -e "test_filter=Sparky_Knot"
```

## License

[Your License Here]

## Authors

Rocky Linux Testing Team