qubit-fs-testkit 0.7.1

Reusable provider contract checks for qubit-fs implementations
Documentation

qubit-fs-testkit

Rust CI Coverage Crates.io Rust License 中文文档

qubit-fs-testkit provides reusable, capability-driven contracts for qubit-fs provider implementations. Add it to a provider's development dependencies, supply an isolated fixture, and run the synchronous or runtime-neutral asynchronous suite without putting test support in production dependency graphs.

Installation

cargo add --dev qubit-fs-testkit@0.7

The synchronous contract suite is available without features. Add features = ["async"] to the development dependency when using the asynchronous suite.

Quick Start

You are shipping a new provider and need one isolated fixture to prove that every advertised capability matches observable behavior. For a provider that exposes a fresh test filesystem, implement FileSystemFixture and register independently named synchronous contracts:

qubit_fs_testkit::register_file_system_contract_tests! {
    module: provider_contracts,
    fixture: super::TestFixture::new,
}

For an asynchronous provider, supply the provider runtime's future runner:

qubit_fs_testkit::register_async_file_system_contract_tests! {
    module: async_provider_contracts,
    fixture: super::AsyncTestFixture::new,
    runner: super::runtime::block_on,
}

The suite follows advertised capabilities. It checks supported behavior and structured rejection of unavailable operations. Inapplicable checks and missing optional instrumentation remain explicit in the report.

The default assertion accepts a missing optional cancellation probe only when the report records a non-empty SkippedOptional reason. This means the run's required checks passed, while run.all_applicable_checks_verified() remains false until every applicable optional probe has evidence. Use run.assert_satisfied_with(&[check_id]) when a particular optional probe is a release requirement; any executed probe failure still fails the run.

Why This Project Exists

Each qubit-fs provider must show that declared capabilities match real filesystem behavior—preflight rejection, structured limits, publication outcomes, and cleanup. Rebuilding that matrix in every crate duplicates effort and drifts from the shared contract. qubit-fs-testkit centralizes capability-driven checks behind fixtures and registration macros so validation stays in development dependencies and out of production graphs.

What It Provides

  • FileSystemFixture and AsyncFileSystemFixture for an isolated facade and provider-specific path mapping; optional hooks support setup and observations outside the operation under test.
  • Borrowed run_all() and run_contract(...) entry points on both suites. The suite retains the ContractRun, including check evidence and cleanup failures. Call run.assert_satisfied() to enforce the complete result.
  • Registration macros that create one isolated, cleanup-safe test per named FileSystemContract phase.
  • Contracts for facade properties, core operations, capability preflight, structured error context, cleanup, and supported optional operations. Both suites cover every FileSystemCapability, including ranges, conditions, checksums, representations, copy policies, required guarantees, and temporary resource persistence.
  • prepare_copy_cancellation and prepare_write_cancellation provide optional stage-acknowledged probes. The suite verifies cancellation state, explicit recovery, and independent publication evidence. Missing probes can be required with run.assert_satisfied_with(&[check_id]); executed failures always fail the run.

Provider crates remain responsible for their own platform behavior, path encoding, security boundaries, service registration, and capabilities outside the suite's current coverage.

Learn More

Version 0.7 targets qubit-fs 0.2; list, cancellation, and recovery details are documented in the user guide.

Testing

# Run tests with the default feature set
cargo test

# Run tests with all declared features
cargo test --all-features

# Project CI checks
./ci-check.sh

# Check code coverage
./coverage.sh

License

Copyright (c) 2025 - 2026. Haixing Hu. All rights reserved.

Licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Contributing

Contributions are welcome. Please follow the Rust API guidelines, keep public API documentation and tests current, and run ./align-ci.sh to format code and ./ci-check.sh to satisfy CI requirements before submitting a pull request.

Author

Haixing Hu - Qubit Co. Ltd.

Repository: https://github.com/qubit-ltd/rs-fs-testkit