qubit-fs-testkit
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
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:
register_file_system_contract_tests!
For an asynchronous provider, supply the provider runtime's future runner:
register_async_file_system_contract_tests!
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
FileSystemFixtureandAsyncFileSystemFixturefor an isolated facade and provider-specific path mapping; optional hooks support setup and observations outside the operation under test.- Borrowed
run_all()andrun_contract(...)entry points on both suites. The suite retains theContractRun, including check evidence and cleanup failures. Callrun.assert_satisfied()to enforce the complete result. - Registration macros that create one isolated, cleanup-safe test per named
FileSystemContractphase. - 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_cancellationandprepare_write_cancellationprovide optional stage-acknowledged probes. The suite verifies cancellation state, explicit recovery, and independent publication evidence. Missing probes can be required withrun.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
# Run tests with all declared features
# Project CI checks
# Check code coverage
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