# Particle-OS Testing Guide

## Overview

This guide provides a systematic approach to testing the Particle-OS system, from initial installation to full integration testing.

## Quick Start

### 1. Run Complete Test Suite

```bash
# Transfer the test script to your VM
scp tools/test-particle-os-complete.sh particle-os:~/particle-os-tools-test/

# On the VM, run the complete test suite
sudo ./test-particle-os-complete.sh
```

### 2. Manual Testing Steps

If you prefer to test manually, follow these phases:

#### Phase 1: Installation Testing

```bash
# Check if tools are installed and accessible
which apt-layer
which composefs-alternative
which bootc-alternative
which bootupd-alternative
which particle-orchestrator

# Test basic commands
apt-layer --help
composefs-alternative --help
bootc-alternative --help
bootupd-alternative --help
particle-orchestrator help

# Verify configuration
ls -la /usr/local/etc/particle-config.sh
```

#### Phase 2: Component Testing

```bash
# Test apt-layer
apt-layer --init
apt-layer status

# Test composefs-alternative
composefs-alternative --help

# Test bootc-alternative
bootc-alternative --help

# Test bootupd-alternative
bootupd-alternative --help
```

#### Phase 3: Integration Testing

```bash
# Test orchestrator
particle-orchestrator help
particle-orchestrator status

# Test OCI integration
oci-integration --help
```

#### Phase 4: System Testing

```bash
# Check directory structure
ls -la /var/lib/particle-os/
ls -la /var/log/particle-os/
ls -la /var/cache/particle-os/

# Check permissions
test -w /var/log/particle-os && echo "Log directory writable"
test -w /var/lib/particle-os && echo "Workspace directory writable"
```

#### Phase 5: Dependency Testing

```bash
# Check system dependencies
dpkg -l | grep squashfs-tools
dpkg -l | grep jq
dpkg -l | grep coreutils
dpkg -l | grep util-linux
which podman
which skopeo

# Check kernel modules
modprobe -n squashfs
```

## Test Results Interpretation

### Pass Rate Categories

- **90-100%**: Excellent - System is ready for production use
- **80-89%**: Good - Minor issues to address
- **70-79%**: Fair - Several issues need attention
- **Below 70%**: Poor - Major issues requiring immediate attention

### Common Issues and Solutions

#### Missing Dependencies

```bash
# Install missing system packages
sudo apt update
sudo apt install squashfs-tools jq coreutils util-linux podman skopeo
```

#### Permission Issues

```bash
# Fix directory permissions
sudo mkdir -p /var/lib/particle-os /var/log/particle-os /var/cache/particle-os
sudo chown -R root:root /var/lib/particle-os /var/log/particle-os /var/cache/particle-os
sudo chmod -R 755 /var/lib/particle-os /var/log/particle-os /var/cache/particle-os
```

#### Configuration Issues

```bash
# Reinstall configuration
sudo apt-layer --init
sudo apt-layer --reset
```

#### Tool Installation Issues

```bash
# Reinstall all tools
sudo ./install-particle-os.sh
```

## Advanced Testing

### Functional Testing

```bash
# Test apt-layer package management
apt-layer install-packages curl wget

# Test atomic OSTree workflow
apt-layer ostree compose install curl wget
apt-layer ostree log
apt-layer ostree status
apt-layer ostree rollback

# Test ComposeFS image creation (official tools)
mkcomposefs testdir test.cfs
composefs-fuse test.cfs /mnt/test-cfs

# Test bootc image building
bootc-alternative build test-image

# Test bootupd boot management
bootupd-alternative add-entry test-image
```

### Integration Testing

```bash
# Test full workflow
particle-orchestrator create-layer test-layer
particle-orchestrator build-image test-layer
particle-orchestrator deploy-image test-layer
```

### Performance Testing

```bash
# Test layer creation performance
time apt-layer install-packages curl wget

# Test image building performance
time composefs-alternative create large-image /large-source

# Test deployment performance
time particle-orchestrator deploy-image test-image
```

## Overlay/dpkg Install Workflow

# Download .deb files on host
sudo apt-get install --download-only htop

# Copy .deb files to overlay
sudo cp /var/cache/apt/archives/*.deb /var/lib/particle-os/live-overlay/mount/tmp/packages/

# Install in overlay with dpkg
sudo chroot /var/lib/particle-os/live-overlay/mount dpkg -i /tmp/packages/*.deb

# Clean up before commit
sudo rm -rf /var/lib/particle-os/live-overlay/mount/tmp/packages/
sudo rm -rf /var/lib/particle-os/live-overlay/mount/var/cache/apt/archives/*

## Troubleshooting

### Debug Mode

Enable debug output for detailed troubleshooting:

```bash
# Set debug environment variable
export PARTICLE_DEBUG=1

# Run tools with debug output
apt-layer --debug status
particle-orchestrator --debug help
```

### Log Analysis

Check logs for detailed error information:

```bash
# View system logs
sudo journalctl -u particle-os

# View tool-specific logs
tail -f /var/log/particle-os/apt-layer.log
tail -f /var/log/particle-os/orchestrator.log
```

### Configuration Validation

Validate configuration files:

```bash
# Check configuration syntax
bash -n /usr/local/etc/particle-config.sh

# Validate JSON configuration
jq . /usr/local/etc/particle-os/*.json
```

## Reporting Issues

When reporting issues, include:

1. **Test Results**: Output from `test-particle-os-complete.sh`
2. **System Information**: `uname -a`, `lsb_release -a`
3. **Configuration**: Contents of `/usr/local/etc/particle-config.sh`
4. **Logs**: Relevant log files from `/var/log/particle-os/`
5. **Steps to Reproduce**: Exact commands that caused the issue

## Continuous Testing

For ongoing development, consider:

1. **Automated Testing**: Set up CI/CD pipeline with automated tests
2. **Regression Testing**: Run tests after each code change
3. **Performance Monitoring**: Track performance metrics over time
4. **User Acceptance Testing**: Test with real-world scenarios

## Next Steps

After successful testing:

1. **Documentation**: Update user and developer guides
2. **Deployment**: Prepare for production deployment
3. **Monitoring**: Set up monitoring and alerting
4. **Maintenance**: Establish maintenance procedures