Testing and Continuous Integration

Relevant source files

• .github/workflows/ci.yml
• .gitignore

This page documents the comprehensive testing and continuous integration strategy for the axvcpu crate, including the CI/CD pipeline architecture, multi-architecture testing matrix, documentation generation, and development workflows. The testing framework ensures code quality and compatibility across multiple CPU architectures and Rust toolchain versions.

For information about build dependencies and external integrations, see Dependencies and Integration.

CI/CD Pipeline Overview

The axvcpu crate employs a GitHub Actions-based CI/CD pipeline that validates code quality, builds across multiple target architectures, and automatically generates and deploys documentation. The pipeline is configured to run on both push events and pull requests, ensuring comprehensive validation of all code changes.

CI Pipeline Architecture

flowchart TD
A["GitHub Push/PR"]
B["CI Job Matrix"]
C["Documentation Job"]
D["rust-toolchain Matrix"]
E["targets Matrix"]
F["nightly-2024-12-25"]
G["nightly"]
H["x86_64-unknown-linux-gnu"]
I["x86_64-unknown-none"]
J["riscv64gc-unknown-none-elf"]
K["aarch64-unknown-none-softfloat"]
L["Code Quality Checks"]
M["cargo fmt --check"]
N["cargo clippy"]
O["cargo build"]
P["cargo test"]
Q["Unit Tests Enabled"]
R["Build Only"]
S["cargo doc --no-deps"]
T["GitHub Pages Deploy"]
U["target/doc Output"]

A --> B
A --> C
B --> D
B --> E
C --> S
C --> T
D --> F
D --> G
E --> H
E --> I
E --> J
E --> K
F --> L
G --> L
H --> Q
I --> R
J --> R
K --> R
L --> M
L --> N
L --> O
L --> P
O --> R
P --> Q
S --> U
U --> T

Sources: .github/workflows/ci.yml(L1 - L58) 

The pipeline consists of two primary jobs that run in parallel, ensuring both functional correctness and documentation quality.

Multi-Architecture Testing Matrix

The CI system validates axvcpu across multiple CPU architectures and Rust toolchain versions to ensure broad compatibility with the ArceOS hypervisor ecosystem.

Target Architecture Configuration

Rust Toolchain Matrix

The pipeline tests against two Rust toolchain configurations:

• nightly-2024-12-25: Pinned stable nightly for reproducible builds
• nightly: Latest nightly for early detection of compatibility issues

Both toolchains include essential components: rust-src, clippy, and rustfmt.

Sources: .github/workflows/ci.yml(L11 - L12)  .github/workflows/ci.yml(L16 - L19) 

Code Quality and Validation Pipeline

Static Analysis and Formatting

flowchart TD
A["Source Code"]
B["rustfmt Check"]
C["clippy Analysis"]
D["Compilation"]
E["Unit Tests"]
F["Format Validation"]
G["Lint Analysis"]
H["Multi-Arch Builds"]
I["Test Execution"]
J["CI Pass/Fail"]

A --> B
B --> C
B --> F
C --> D
C --> G
D --> E
D --> H
E --> I
F --> J
G --> J
H --> J
I --> J

Sources: .github/workflows/ci.yml(L22 - L30) 

The validation pipeline enforces code quality through multiple stages:

Format Checking

• Command: cargo fmt --all -- --check
• Purpose: Ensures consistent code formatting across the entire codebase
• Failure Mode: Pipeline fails if any files are not properly formatted

Static Analysis

• Command: cargo clippy --target ${{ matrix.targets }} --all-features -- -A clippy::new_without_default
• Configuration: Allows new_without_default lint to accommodate API design patterns
• Scope: Runs across all target architectures with full feature enablement

Build Validation

• Command: cargo build --target ${{ matrix.targets }} --all-features
• Coverage: All target architectures in the matrix
• Features: Full feature set enabled to validate complete functionality

Unit Testing

• Command: cargo test --target ${{ matrix.targets }} -- --nocapture
• Restriction: Only runs on x86_64-unknown-linux-gnu target
• Output: Detailed test output with --nocapture flag

Sources: .github/workflows/ci.yml(L23 - L30) 

Documentation Generation and Deployment

Documentation Pipeline

flowchart TD
A["Documentation Job"]
B["Rust Toolchain Setup"]
C["cargo doc Build"]
D["Index Page Generation"]
E["Branch Check"]
F["Default Branch?"]
G["Deploy to gh-pages"]
H["Build Only"]
I["RUSTDOCFLAGS Validation"]
J["Broken Links Check"]
K["Missing Docs Check"]
L["GitHub Pages Site"]
M["Pipeline Failure"]

A --> B
B --> C
C --> D
C --> I
D --> E
E --> F
F --> G
F --> H
G --> L
I --> J
I --> K
J --> M
K --> M

Sources: .github/workflows/ci.yml(L32 - L58) 

Documentation Configuration

The documentation build process includes strict validation and automatic deployment:

Rustdoc Validation

• Environment: RUSTDOCFLAGS: -D rustdoc::broken_intra_doc_links -D missing-docs
• Validation: Treats broken internal links and missing documentation as errors
• Purpose: Ensures comprehensive and accurate API documentation

Build Process

• Command: cargo doc --no-deps --all-features
• Scope: Generates documentation without external dependencies
• Features: Includes all feature flags for complete API coverage

Index Generation

printf '<meta http-equiv="refresh" content="0;url=%s/index.html">' $(cargo tree | head -1 | cut -d' ' -f1) > target/doc/index.html

This automatically creates a redirect from the root documentation page to the main crate documentation.

Deployment Strategy

• Target: GitHub Pages via gh-pages branch
• Trigger: Only on default branch pushes
• Method: Single-commit deployment using JamesIves/github-pages-deploy-action@v4
• Source: target/doc directory

Sources: .github/workflows/ci.yml(L40)  .github/workflows/ci.yml(L48 - L57) 

Development Environment and Build Artifacts

Ignored Build Artifacts

The development environment excludes specific build artifacts from version control:

Sources: .gitignore(L2 - L18) 

Testing Strategy and Coverage

The testing approach balances comprehensive validation with practical constraints:

Architecture-Specific Testing

• Full Testing: Limited to x86_64-unknown-linux-gnu for unit test execution
• Build Validation: All target architectures undergo compilation and static analysis
• Rationale: Bare-metal targets cannot execute standard unit tests

Error Handling and Validation

• Continue on Error: Documentation builds continue on non-default branches
• Fail Fast: CI jobs use fail-fast: false to complete all matrix combinations
• Branch Protection: Only default branch builds trigger documentation deployment

The testing framework ensures that axvcpu maintains compatibility across the supported architectures while providing comprehensive validation of core functionality through the Linux-based test environment.

Sources: .github/workflows/ci.yml(L8 - L9)  .github/workflows/ci.yml(L29 - L30)  .github/workflows/ci.yml(L47)