qubit-fs-testkit 0.9.2

Reusable provider contract checks for qubit-fs implementations
Documentation

qubit-fs-testkit

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

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

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

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:

[dev-dependencies]
qubit-fs-testkit = "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:

cargo run --manifest-path ../rs-fs-local/Cargo.toml --example fs_testkit_contract

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 qubit_fs_testkit::FileSystemContract;
use qubit_fs_testkit::FileSystemContractSuite;

let fixture = RootedFixture::new();
let mut suite = FileSystemContractSuite::new(&fixture);
suite
    .run_contract(FileSystemContract::Properties)
    .assert_satisfied();

let fixture = RootedFixture::new();
let mut suite = FileSystemContractSuite::new(&fixture);
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:

[dev-dependencies]
qubit-fs-testkit = { version = "0.9", features = ["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

  • 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. Their optional required_checks callback 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.
  • CopyNativeNonEmpty independently verifies non-empty native copy results; see the user guide for optional and required modes.
  • 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.
  • Random-access checks run in the Read phase. RandomAccessBounds covers empty reads, EOF, clipping, overflow, and reader reuse after an error; RandomAccessRangeLimit independently checks a finite declared maximum. Async cancellation passes only when the suite observes Pending at 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
cargo test

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

# Project CI checks
./.infra/bin/ci-check.sh

# Check code coverage
./.infra/bin/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 ./.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