271 lines
No EOL
6 KiB
Markdown
271 lines
No EOL
6 KiB
Markdown
# 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 |