tests: Add integration test suite with bcvk VM support

Add a new integration-tests crate that exercises the cfsctl CLI as a
subprocess using libtest-mimic with linkme distributed slices (same
pattern as bcvk). Tests are split into two tiers:

Unprivileged CLI tests run without root, using --insecure to skip
fs-verity. Privileged tests create loopback ext4 filesystems with the
verity feature and run cfsctl without --insecure; when not root, they
automatically re-dispatch into a bcvk ephemeral VM.

Includes a Containerfile producing a bootable centos-bootc:stream10
image with cfsctl and the test binary baked in, plus a GHA workflow
using bootc-ubuntu-setup for CI.

Assisted-by: OpenCode (Claude Opus)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

.config/nextest.toml

@@ -0,0 +1,36 @@
+# cargo-nextest configuration for composefs-rs
+# https://nexte.st/book/configuration
+#
+# Integration tests use libtest-mimic which is fully compatible with nextest
+
+[store]
+dir = "target/nextest"
+
+[profile.default]
+test-threads = "num-cpus"
+slow-timeout = { period = "30s", terminate-after = 2 }
+fail-fast = false
+failure-output = "immediate"
+success-output = "never"
+status-level = "pass"
+
+# Profile for integration tests — run with limited parallelism due to QEMU/KVM resources
+[profile.integration]
+test-threads = 2
+# 20 minutes for VM tests on slow CI runners
+slow-timeout = { period = "1200s", terminate-after = 60 }
+fail-fast = false
+failure-output = "immediate"
+success-output = "never"
+status-level = "pass"
+default-filter = "package(integration-tests)"
+
+[profile.integration.junit]
+path = "junit.xml"
+store-success-output = true
+store-failure-output = true
+
+# VM tests boot an ephemeral QEMU instance per test, limit parallelism
+[[profile.integration.overrides]]
+filter = 'test(~^vm_)'
+threads-required = 4

.containerignore

@@ -0,0 +1,5 @@
+# Keep the build context small: exclude everything, then allowlist sources.
+*
+!Cargo.toml
+!Cargo.lock
+!crates/

.github/workflows/integration.yml

@@ -0,0 +1,42 @@
+name: Integration Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  COMPOSEFS_TEST_IMAGE: localhost/composefs-rs-test:latest
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  integration:
+    name: Integration tests
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup
+        uses: bootc-dev/actions/bootc-ubuntu-setup@main
+        with:
+          libvirt: true
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Run unprivileged integration tests
+        run: just integration-unprivileged
+
+      - name: Run privileged integration tests (via bcvk VM)
+        run: just integration-container

Containerfile

@@ -0,0 +1,50 @@
+# Containerfile for composefs-rs
+#
+# Builds cfsctl and integration test binaries, then produces a bootable
+# (bootc-compatible) container image suitable for privileged integration
+# testing via `bcvk ephemeral run-ssh`.
+#
+# Build:
+#   podman build --tag composefs-rs-test -f Containerfile .
+#
+# Uses BuildKit-style cache mounts for fast incremental Rust builds.
+
+# -- source snapshot (keeps layer graph clean) --
+FROM scratch AS src
+COPY . /src
+
+# -- build stage --
+FROM quay.io/centos-bootc/centos-bootc:stream10 AS build
+
+RUN dnf install -y \
+        rust cargo clippy rustfmt \
+        openssl-devel \
+        gcc \
+        composefs \
+    && dnf clean all
+
+COPY --from=src /src /src
+WORKDIR /src
+
+# Fetch dependencies (network-intensive, cached separately)
+RUN --mount=type=cache,target=/src/target \
+    --mount=type=cache,target=/root/.cargo/registry \
+    --mount=type=cache,target=/root/.cargo/git \
+    cargo fetch
+
+# Build cfsctl and integration test binary
+RUN --network=none \
+    --mount=type=cache,target=/src/target \
+    --mount=type=cache,target=/root/.cargo/registry \
+    --mount=type=cache,target=/root/.cargo/git \
+    cargo build --release -p cfsctl -p integration-tests && \
+    cp /src/target/release/cfsctl /usr/bin/cfsctl && \
+    cp /src/target/release/cfsctl-integration-tests /usr/bin/cfsctl-integration-tests
+
+# -- final bootable image --
+FROM quay.io/centos-bootc/centos-bootc:stream10
+
+RUN dnf install -y composefs openssl && dnf clean all
+
+COPY --from=build /usr/bin/cfsctl /usr/bin/cfsctl
+COPY --from=build /usr/bin/cfsctl-integration-tests /usr/bin/cfsctl-integration-tests

Justfile

@@ -12,9 +12,9 @@ build:
 build-release:
     cargo build --workspace --release
 
-# Run all tests
+# Run unit tests (excludes integration-tests crate)
 test:
-    cargo test --workspace
+    cargo test --workspace --exclude integration-tests
 
 # Run clippy lints
 clippy:
@@ -31,6 +31,26 @@ fmt:
 # Run all checks (clippy + fmt + test)
 check: clippy fmt-check test
 
+COMPOSEFS_TEST_IMAGE := "localhost/composefs-rs-test:latest"
+
+# Run integration tests (builds cfsctl first); pass extra args to the harness
+test-integration *ARGS: build
+    CFSCTL_PATH=$(pwd)/target/debug/cfsctl cargo run -p integration-tests -- {{ ARGS }}
+
+# Run only the fast unprivileged integration tests (no root, no VM)
+integration-unprivileged: build
+    CFSCTL_PATH=$(pwd)/target/debug/cfsctl cargo run -p integration-tests -- --skip privileged_
+
+# Build the test container image for VM-based integration tests
+integration-container-build:
+    podman build -t {{COMPOSEFS_TEST_IMAGE}} -f Containerfile .
+
+# Run all integration tests; privileged tests dispatch to a bcvk VM
+integration-container: build integration-container-build
+    COMPOSEFS_TEST_IMAGE={{COMPOSEFS_TEST_IMAGE}} \
+        CFSCTL_PATH=$(pwd)/target/debug/cfsctl \
+        cargo run -p integration-tests
+
 # Clean build artifacts
 clean:
     cargo clean

crates/integration-tests/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "integration-tests"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "cfsctl-integration-tests"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = "1"
+xshell = "0.2"
+libtest-mimic = "0.8"
+linkme = "0.3"
+paste = "1"
+rustix = { version = "1.0.0", default-features = false, features = ["process"] }
+tempfile = "3"
+
+[lints]
+workspace = true

crates/integration-tests/README.md

@@ -0,0 +1,106 @@
+# composefs-rs integration tests
+
+Integration tests for `cfsctl` that exercise the CLI as a subprocess.
+Unlike the workspace's unit tests, these run the actual binary against
+real repositories and (optionally) real kernels with fs-verity.
+
+The test binary uses `libtest-mimic` with `linkme` distributed slices
+instead of `#[test]`, following the same pattern as
+[bcvk](https://github.com/bootc-dev/bcvk).
+
+## Test tiers
+
+**CLI tests** (`test_*`) run on the host without root. They pass
+`--insecure` to skip fs-verity and use temp dirs for repositories.
+These are fast and need no special setup.
+
+**Privileged tests** (`privileged_*`) need root and real fs-verity
+support. They create loopback ext4 filesystems with the verity feature
+and run `cfsctl` without `--insecure`. When run on the host (not as
+root), each test automatically re-executes itself inside a
+[bcvk](https://github.com/bootc-dev/bcvk) ephemeral VM — no separate
+wrapper functions needed. Set `COMPOSEFS_TEST_IMAGE` to enable this.
+
+## Running
+
+```sh
+# Fast CLI tests only (no root, no VM)
+just integration-unprivileged
+
+# Everything, privileged tests auto-dispatch to bcvk VM
+just integration-container
+```
+
+The container image is built from the repo's `Containerfile` and
+includes both `cfsctl` and `cfsctl-integration-tests` at `/usr/bin/`.
+It's based on `centos-bootc:stream10` so bcvk can boot it as a VM.
+
+## Running privileged tests without bcvk
+
+If you have root and a kernel with fs-verity support (5.4+), you can
+skip the VM dispatch entirely. The tests create loopback ext4
+filesystems with the verity feature, so you need `mkfs.ext4` and
+`mount` available.
+
+**Direct execution as root** (e.g. inside a VM, a privileged
+container, or a test machine):
+
+```sh
+cfsctl-integration-tests privileged_
+```
+
+Or from the workspace:
+
+```sh
+sudo CFSCTL_PATH=$(pwd)/target/debug/cfsctl cargo run -p integration-tests -- privileged_
+```
+
+**Inside a privileged container** — useful on hosts without native
+fs-verity or when you don't want to install dependencies locally:
+
+```sh
+podman run --privileged -v $(pwd):/src:Z -w /src \
+  quay.io/fedora/fedora:41 \
+  bash -c 'dnf -y install cargo composefs e2fsprogs && \
+           cargo build -p cfsctl -p integration-tests && \
+           CFSCTL_PATH=$(pwd)/target/debug/cfsctl \
+           cargo run -p integration-tests -- privileged_'
+```
+
+### Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `CFSCTL_PATH` | Path to `cfsctl` binary. Auto-detected if not set. |
+| `COMPOSEFS_TEST_IMAGE` | Container image for VM dispatch. Setting this triggers bcvk auto-dispatch for privileged tests. |
+| `BCVK_PATH` | Path to `bcvk` binary. Found in `PATH` if not set. |
+| `COMPOSEFS_IN_VM` | Set automatically inside VMs to prevent recursive dispatch. |
+
+## Adding tests
+
+Define a function returning `anyhow::Result<()>` and register it:
+
+```rust
+fn test_my_feature() -> Result<()> {
+    let sh = Shell::new()?;
+    let cfsctl = cfsctl()?;
+    // ...
+    Ok(())
+}
+integration_test!(test_my_feature);
+```
+
+For privileged tests, call `require_privileged()` at the top. This
+handles both execution paths — running directly as root, or
+re-dispatching into a VM:
+
+```rust
+fn privileged_my_feature() -> Result<()> {
+    if require_privileged("privileged_my_feature")?.is_some() {
+        return Ok(());
+    }
+    // ... test body runs as root with fs-verity ...
+    Ok(())
+}
+integration_test!(privileged_my_feature);
+```

crates/integration-tests/src/lib.rs

@@ -0,0 +1,52 @@
+//! Integration test infrastructure for composefs-rs.
+//!
+//! Provides test registration via [`linkme`] distributed slices and the
+//! [`integration_test!`] macro, collected and executed by a custom
+//! [`libtest_mimic`] harness in `main.rs`.
+
+// linkme requires unsafe for distributed slices
+#![allow(unsafe_code)]
+
+/// A test function that returns a Result.
+pub type TestFn = fn() -> anyhow::Result<()>;
+
+/// Metadata for a registered integration test.
+#[derive(Debug)]
+pub struct IntegrationTest {
+    /// Name of the integration test.
+    pub name: &'static str,
+    /// Test function to execute.
+    pub f: TestFn,
+}
+
+impl IntegrationTest {
+    /// Create a new integration test with the given name and function.
+    pub const fn new(name: &'static str, f: TestFn) -> Self {
+        Self { name, f }
+    }
+}
+
+/// Distributed slice holding all registered integration tests.
+#[linkme::distributed_slice]
+pub static INTEGRATION_TESTS: [IntegrationTest];
+
+/// Register an integration test function with less boilerplate.
+///
+/// # Examples
+///
+/// ```ignore
+/// fn test_something() -> anyhow::Result<()> {
+///     Ok(())
+/// }
+/// integration_test!(test_something);
+/// ```
+#[macro_export]
+macro_rules! integration_test {
+    ($fn_name:ident) => {
+        ::paste::paste! {
+            #[::linkme::distributed_slice($crate::INTEGRATION_TESTS)]
+            static [<$fn_name:upper>]: $crate::IntegrationTest =
+                $crate::IntegrationTest::new(stringify!($fn_name), $fn_name);
+        }
+    };
+}