qubit-fs-testkit
qubit-fs-testkit 0.9 provides reusable, capability-driven contracts for
qubit-fs 0.3 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 provider and need an isolated fixture to check its advertised
capabilities. The provider already depends on qubit-fs 0.3; add the testkit
only as a development dependency:
[]
= "0.9"
Implement FileSystemFixture around the provider's isolated facade. Its
file_system() returns the configured FileSystem whose
FileSystemProperties the suite checks; path() maps suite names into the
fixture namespace, and independent hooks seed, read, observe, and tear down
resources. The complete executable example is
fs_testkit_contract.rs.
It shows a rooted local facade, independent native-file observations, and the
run_all().assert_satisfied() assertion. The command below builds and runs the
example; a provider contract violation makes that assertion fail:
The example's fixture type is RootedFixture. A fresh suite checks the
provider's FileSystemProperties in its first phase; use a separate fixture
and suite for another run:
use FileSystemContract;
use FileSystemContractSuite;
let fixture = new;
let mut suite = new;
suite
.run_contract
.assert_satisfied;
let fixture = new;
let mut suite = new;
suite.run_all.assert_satisfied;
For an asynchronous provider, implement AsyncFileSystemFixture and supply the
provider runtime's future runner to the registration macro. Its development
dependency enables the feature explicitly:
[]
= { = "0.9", = ["async"] }
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. Their optionalrequired_checkscallback can require selected optional evidence for each phase; omitting it preserves the existing default policy. - 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. CopyNativeNonEmptyindependently verifies non-empty native copy results; see the user guide for optional and required modes.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.- Random-access checks run in the
Readphase.RandomAccessBoundscovers empty reads, EOF, clipping, overflow, and reader reuse after an error;RandomAccessRangeLimitindependently checks a finite declared maximum. Async cancellation passes only when the suite observesPendingat the injected gate. See the user guide for probe limits, evidence outcomes, and requiring both checks when complete boundary evidence is needed.
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.9 targets qubit-fs 0.3. Version 0.7 targeted qubit-fs 0.2;
historical list, cancellation, and recovery details are distinguished 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 ./.infra/bin/align-ci.sh to format code and
./.infra/bin/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