particle-os-tools/TESTING_GUIDE.md

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

# 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

# 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

# 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

# Test orchestrator
particle-orchestrator help
particle-orchestrator status

# Test OCI integration
oci-integration --help

Phase 4: System Testing

# 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

# 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

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

Permission Issues

# 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

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

Tool Installation Issues

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

Advanced Testing

Functional Testing

# 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

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

Performance Testing

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

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

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

# 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