Testing Strategies & CI Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu utilizes a multi-layered approach to ensure code quality and stability across its suite of Bash-based virtualization tools. The project implements automated Continuous Integration (CI) workflows that encompass shell script linting, Pull Request (PR) validation, and functional testing of the OS download engine, quickget. These strategies are designed to support a project that automates complex VM creation for approximately 1000 operating system editions.
The testing lifecycle begins in the development environment, often managed via Nix, and extends through GitHub Actions workflows that trigger on every pull request. This ensures that new features, such as adding a new OS or updating VM configurations, do not introduce regressions or violate the project's strict coding standards.
Sources: AGENTS.md:3-8, README.md:54-55
Local Development and Manual Testing
Before code is submitted to the repository, developers are encouraged to use specific tools and commands to verify their changes locally. The project provides a Nix-based development environment to ensure consistency across different host systems.
Development Environment Tools
Quickemu leverages Nix flakes to provide a reproducible development shell. This shell includes all necessary runtime dependencies and patches the quickemu script to use Nix store paths for specific components like OVMF and Samba.
| Command | Description |
|---|---|
nix develop | Enters a shell with all build and runtime dependencies. |
direnv reload | Updates the local environment and patches quickemu for testing. |
shellcheck <script> | Validates Bash scripts against project standards. |
Sources: AGENTS.md:15-20, AGENTS.md:25
Manual Verification Commands
Developers use quickget flags to verify OS definitions and download logic without performing full installations. This is critical when adding new distributions to the os_info() logic.
- Standard Check:
./quickget --check <os> [release] [edition] - Architecture Check:
./quickget --arch arm64 --check <os> - Comprehensive Check:
./quickget --check-all-arch <os>
Sources: AGENTS.md:26-29
Automated CI Workflows
Quickemu employs several GitHub Actions workflows to automate the validation of contributions. These workflows are triggered by Pull Requests to ensure that all code meets the project's quality bar before merging.
Workflow Overview
The CI suite focuses on three main areas: code style (linting), metadata validation (PR titles), and functional verification.
| Workflow | Purpose |
|---|---|
lint-shellcheck | Runs shellcheck with a severity level of "warning" on all scripts. |
lint-pr | Validates that the PR title adheres to the Conventional Commits specification. |
test-quickget | Tests the functionality and URL construction logic of quickget. |
test-build-quickemu | Verifies the build process and basic integrity of the main launcher. |
flake-checker | Validates the integrity and structure of the Nix flake configuration. |
Sources: AGENTS.md:73-77
Contribution Flow
The following diagram illustrates the flow from a developer's local environment through the automated CI gates:
The CI process ensures that every contribution is syntactically correct and functionally sound before integration.
Sources: AGENTS.md:68-77, CONTRIBUTING.md:11-13
Commit and Code Standards
Testing strategies are reinforced by strict adherence to specific standards for code structure and commit metadata.
Conventional Commits
To maintain a clean and searchable history, Quickemu requires Conventional Commits. This is enforced both by the lint-pr CI workflow and manual review.
- fix(quickget): Used for fixing download methods or updating releases.
- feat(quickget): Used when adding support for a new operating system.
- ci: Used for changes to the workflows described above.
Sources: AGENTS.md:54-65
Coding Style Requirements
All scripts must be compatible with Bash 4.0+ and pass shellcheck. Because quickget uses dynamic dispatch for OS-specific functions (where functions are called via variables), certain ShellCheck rules (like SC2317) are disabled globally to avoid false positives.
# Example of coding convention in quickget
function releases_ubuntu() {
# Logic to return available versions
}
Sources: AGENTS.md:32-41
Security and Vulnerability Testing
While Quickemu is a "best-efforts" community project, it maintains a structured approach to security. Security updates are prioritized for the current major version (4.9.x), while older versions (below 4.8) are officially unsupported. Vulnerabilities are tracked via the GitHub Issue tracker under a specific "Report a vulnerability" category.
Sources: SECURITY.md:5-15
Summary
Quickemu's testing and CI strategy relies on a combination of local verification via Nix and automated validation via GitHub Actions. By enforcing ShellCheck compliance, Conventional Commits, and automated URL checks for quickget, the project maintains a high level of reliability for its ~1000 supported OS editions. These workflows ensure that the "optimum configuration" promised by quickemu remains accurate as upstream OS mirrors and configurations evolve.