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

# 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

# If already running in container
just test-container

Create Temporary Container

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

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

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

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

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

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

Environment Variables

Set environment variables for testing:

# 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

# Check if OSTree is installed
which ostree

# Install OSTree if needed
sudo apt install ostree

Permission Denied

# Check directory permissions
ls -la /ostree

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

Container Issues

# Check container runtime
which podman || which docker

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

Debug Mode

Enable verbose output:

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

📈 Performance Testing

Test command performance:

# Run performance tests
just test-performance

This measures:

• Help command response time
• Search command performance
• Version command speed

🧹 Cleanup

Clean up test artifacts:

# Remove test files
just clean

🔄 Continuous Integration

GitHub Actions Example

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

# Run tests before commit
just test-system && just test-report

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

📚 Examples

Development Workflow

# 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

# Test on production system
just test-booted-system

# Performance testing
just test-performance

# Error handling
just test-errors

CI/CD Pipeline

# 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! 🧪✨