apt-ostree/TESTING.md

# apt-ostree Testing Suite

A comprehensive testing framework for `apt-ostree` that handles different deployment scenarios in Debian-based OSTree systems.

## 🚀 Quick Start

```bash
# Install just (if not already installed)
sudo apt install just

# Run comprehensive system test
just test-system

# Check system environment
just detect-env

# Test CLI functionality only
just test-cli
```

## 🔍 Environment Detection

The testing suite automatically detects your system environment:

- **🐳 Container Environment**: Podman, Docker, LXC
- **🚀 Booted OSTree System**: Live deployment with write access
- **💾 Disk-based System**: QCOW2, VMDK, or mounted images
- **🆕 Fresh Installation**: New system without OSTree

## 📋 Available Test Targets

### Environment Detection
- `detect-env` - Detect system environment and show status
- `test-environments` - Test apt-ostree in different environments

### Specific Tests
- `test-cli` - Test CLI functionality
- `test-ostree` - Test OSTree integration
- `test-container` - Test in container environment
- `test-booted-system` - Test on booted OSTree system
- `test-disk-system` - Test on disk-based OSTree system
- `test-fresh-install` - Test on fresh installation

### Comprehensive Testing
- `test-system` - Run comprehensive system test
- `test-commands` - Test specific commands
- `test-errors` - Test error handling
- `test-performance` - Test performance

### Utilities
- `test-report` - Generate test report
- `clean` - Clean up test artifacts
- `help` - Show help message

## 🐳 Container Testing

### Test in Existing Container
```bash
# If already running in container
just test-container
```

### Create Temporary Container
```bash
# Creates temporary container for testing
just run-container-test
```

This will:
- Use Podman if available, fallback to Docker
- Mount current directory as `/workspace`
- Run basic CLI tests
- Clean up automatically

## 🚀 Booted OSTree System Testing

For systems running live OSTree deployments:

```bash
# Test on booted system
just test-booted-system
```

This tests:
- OSTree deployment status
- System-specific commands
- Write access to OSTree directories

## 💾 Disk-based System Testing

For QCOW2, VMDK, or mounted OSTree images:

```bash
# Test on disk-based system
just test-disk-system
```

This detects:
- OSTree configuration files
- Directory permissions
- Read-only vs. writable status

## 🆕 Fresh Installation Testing

For new systems without OSTree:

```bash
# Test on fresh installation
just test-fresh-install
```

This tests:
- Basic CLI functionality
- Help system
- Version information
- No OSTree dependencies

## 📊 Test Reports

Generate comprehensive test reports:

```bash
# Generate test report
just test-report

# View report
cat test-report.txt
```

Reports include:
- System environment detection
- CLI test results
- OSTree integration status
- Performance metrics

## 🔧 Customization

### Add Custom Tests
Add new test targets to the `justfile`:

```makefile
# Custom test example
test-custom:
    @echo "🧪 Running custom test..."
    @apt-ostree custom-command
    @echo "✅ Custom test complete"
```

### Environment Variables
Set environment variables for testing:

```bash
# Set test environment
export APT_OSTREE_TEST_ENV=production
export APT_OSTREE_LOG_LEVEL=debug

# Run tests
just test-system
```

## 🐛 Troubleshooting

### Common Issues

#### OSTree Not Available
```bash
# Check if OSTree is installed
which ostree

# Install OSTree if needed
sudo apt install ostree
```

#### Permission Denied
```bash
# Check directory permissions
ls -la /ostree

# Run with appropriate privileges
sudo just test-booted-system
```

#### Container Issues
```bash
# Check container runtime
which podman || which docker

# Verify container access
ls -la /.dockerenv /run/.containerenv
```

### Debug Mode
Enable verbose output:

```bash
# Run with debug output
just --verbose test-system
```

## 📈 Performance Testing

Test command performance:

```bash
# Run performance tests
just test-performance
```

This measures:
- Help command response time
- Search command performance
- Version command speed

## 🧹 Cleanup

Clean up test artifacts:

```bash
# Remove test files
just clean
```

## 🔄 Continuous Integration

### GitHub Actions Example
```yaml
name: Test apt-ostree
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-rust@v3
      - run: |
          sudo apt install just ostree
          just test-system
          just test-report
      - uses: actions/upload-artifact@v3
        with:
          name: test-report
          path: test-report.txt
```

### Local CI
```bash
# Run tests before commit
just test-system && just test-report

# Check for failures
grep -i "❌\|FAIL" test-report.txt
```

## 📚 Examples

### Development Workflow
```bash
# 1. Check environment
just detect-env

# 2. Run basic tests
just test-cli

# 3. Test in container
just run-container-test

# 4. Full system test
just test-system

# 5. Generate report
just test-report
```

### Production Testing
```bash
# Test on production system
just test-booted-system

# Performance testing
just test-performance

# Error handling
just test-errors
```

### CI/CD Pipeline
```bash
# Automated testing
just test-system
just test-performance
just test-report

# Exit on failure
if grep -q "❌\|FAIL" test-report.txt; then
    echo "Tests failed!"
    exit 1
fi
```

## 🤝 Contributing

When adding new tests:

1. **Follow naming convention**: `test-<feature>`
2. **Add to help section**: Update the `help` target
3. **Include in system test**: Add to `test-system` target
4. **Document usage**: Add examples to this README

## 📄 License

This testing suite is part of the `apt-ostree` project and follows the same license terms.

---

**Happy Testing! 🧪✨**