Skip to main content

FileSystemFixture

Trait FileSystemFixture 

Source
pub trait FileSystemFixture {
Show 22 methods // Required methods fn file_system(&self) -> &FileSystem; fn path(&self, relative: &str) -> FixtureResult<Path>; fn teardown(&self) -> FixtureResult<()>; // Provided methods fn random_access_operation(&self) -> FixtureSupport<bool> { ... } fn replace_random_access_path( &self, path: &Path, bytes: &[u8], ) -> FixtureResult<FixtureSupport<()>> { ... } fn snapshot_namespace_paths( &self, ) -> FixtureResult<FixtureSupport<Vec<Path>>> { ... } fn prepare_copy( &self, scenario: CopyScenario, source_relative: &str, target_relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<CopyFixtureCase>> { ... } fn prepare_delete( &self, _scenario: DeleteScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<Path>> { ... } fn prepare_read( &self, scenario: ReadScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<Path>> { ... } fn prepare_write( &self, scenario: WriteScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<WriteFixtureCase>> { ... } fn copy_fallback_only(&self) -> bool { ... } fn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String> { ... } fn seed_file( &self, relative: &str, bytes: &[u8], ) -> FixtureResult<FixtureSupport<Path>> { ... } fn read_file(&self, path: &Path) -> FixtureResult<FixtureSupport<Vec<u8>>> { ... } fn exists_out_of_band( &self, path: &Path, ) -> FixtureResult<FixtureSupport<bool>> { ... } fn write_file_out_of_band( &self, path: &Path, bytes: &[u8], ) -> FixtureResult<FixtureSupport<()>> { ... } fn resource_version( &self, path: &Path, ) -> FixtureResult<FixtureSupport<ResourceVersion>> { ... } fn stale_resource_version( &self, path: &Path, ) -> FixtureResult<FixtureSupport<ResourceVersion>> { ... } fn checksum_failure_case( &self, relative: &str, ) -> FixtureResult<FixtureSupport<Path>> { ... } fn seed_empty_directory( &self, relative: &str, ) -> FixtureResult<FixtureSupport<Path>> { ... } fn seed_symlink( &self, relative: &str, ) -> FixtureResult<FixtureSupport<Path>> { ... } fn copy_fast_path_case( &self, method: CopyMethod, ) -> FixtureResult<FixtureSupport<CopyFixtureCase>> { ... }
}
Expand description

Supplies an isolated facade and provider-specific contract observations.

§Examples

use qubit_fs_testkit::{FileSystemContractSuite, FileSystemFixture};

let fixture = RustdocSyncFixture::new();
let suite = FileSystemContractSuite::new(&fixture);
assert!(suite.run().report().checks().is_empty());

Required Methods§

Source

fn file_system(&self) -> &FileSystem

Returns the concrete synchronous filesystem facade under test.

§Returns

The isolated filesystem facade owned by this fixture.

Source

fn path(&self, relative: &str) -> FixtureResult<Path>

Maps a testkit-relative name to an isolated logical path.

§Parameters
  • relative - Suite-generated name relative to the fixture namespace.
§Returns

The corresponding logical path within the isolated namespace.

§Errors

Returns FixtureError when the name cannot be represented by the provider’s path model.

Source

fn teardown(&self) -> FixtureResult<()>

Independently releases every resource owned by this fixture.

This mandatory operation must be idempotent and must reclaim partially prepared resources and staging state, including resources unknown to the suite. Use a native or out-of-band channel independent of the facade under test. Return an error if cleanup could not be confirmed. A cancelled asynchronous attempt must remain safe to retry.

§Returns

Ok(()) when cleanup is confirmed; otherwise, a fixture error describing the cleanup failure.

§Errors

Returns FixtureError when any owned resource or staging state could not be reclaimed or confirmed.

Provided Methods§

Source

fn random_access_operation(&self) -> FixtureSupport<bool>

Independently reports whether the provider implements the random-access SPI operation. This must reflect provider configuration, not facade range-read support. Unsupported means the suite cannot determine the declaration and reports the optional check as skipped.

§Returns

Supported(true) or Supported(false) with the independent SPI declaration, or Unsupported when the fixture cannot observe it.

Source

fn replace_random_access_path( &self, path: &Path, bytes: &[u8], ) -> FixtureResult<FixtureSupport<()>>

Replaces a logical path while preserving objects already opened through the provider. The implementation must use an independent fixture path and must not perform the replacement through the facade under test.

§Parameters
  • path - Seeded path to replace.
  • bytes - Content of the replacement object.
§Returns

Supported(()) when replacement is observable, otherwise Unsupported.

§Errors

Returns FixtureError when replacement setup fails.

Source

fn snapshot_namespace_paths(&self) -> FixtureResult<FixtureSupport<Vec<Path>>>

Snapshots every logical path in the isolated configured namespace.

Use the underlying SDK or fixture model, never the facade list method. Include resources created by earlier checks, not only the current seed. Returns unsupported when independent completeness cannot be established.

Source

fn prepare_copy( &self, scenario: CopyScenario, source_relative: &str, target_relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<CopyFixtureCase>>

Independently prepares a copy source and a scenario-specific target.

File scenarios contain the supplied bytes and use file options, with required atomicity or durability for the respective strong scenario. Native cases provide an independently seeded source containing 1..=64 KiB; missing independent source evidence is reported as unverified. ServerSide cases use provider-selected bytes that are independently seeded and readable, contain 1..=64 KiB, and require server-side copy. The suite independently checks source contents and target absence before execution, then source and target contents after execution; unavailable preparation or observation evidence is reported as unverified. Ready cases have distinct paths, and Conflict targets contain b"existing". Teardown must clean partial setup even when preparation fails.

§Parameters
  • scenario - Copy behavior the contract suite will exercise.
  • source_relative - Testkit-relative source path to prepare.
  • target_relative - Testkit-relative destination path to prepare.
  • bytes - File content used to seed file copy scenarios.
§Returns

A ready copy case or an unavailable result when the fixture cannot independently prepare the requested scenario.

§Errors

Returns FixtureError when fixture setup fails.

Source

fn prepare_delete( &self, _scenario: DeleteScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<Path>>

Independently prepares an existing file for a selected deletion scenario. Version hooks must provide evidence for DeleteScenario::IfMatch.

§Parameters
  • _scenario - Deletion behavior the contract suite will exercise.
  • relative - Testkit-relative path for the file to seed.
  • bytes - Exact initial content of the file.
§Returns

A ready file path or an unavailable result when independent seeding is unsupported.

§Errors

Returns FixtureError when fixture setup fails.

Source

fn prepare_read( &self, scenario: ReadScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<Path>>

Independently prepares one read scenario and its initial content.

A Ready path must contain the supplied bytes, except for the explicit corruption scenario. Version observations remain independent fixture hooks. Preparation errors must not become inapplicability declarations.

§Parameters
  • scenario - Read behavior for which the resource is prepared.
  • relative - Testkit-relative path for the resource.
  • bytes - Expected initial content except in the corruption scenario.
§Returns

A ready resource path or an unavailable result when independent setup is unsupported.

§Errors

Returns FixtureError when fixture setup fails.

Source

fn prepare_write( &self, scenario: WriteScenario, relative: &str, bytes: &[u8], ) -> FixtureResult<FixturePreparation<WriteFixtureCase>>

Prepares one write scenario without invoking the tested write facade.

The default prepares CreateNew and durable creation requests. Atomic replacement, creation conflicts and append use independent seeding. Other scenarios require provider-specific setup and evidence.

§Parameters
  • scenario - Write behavior the contract suite will exercise.
  • relative - Testkit-relative path for the resource.
  • bytes - Content the write case supplies to the tested operation.
§Returns

A ready write case or an unavailable result when the fixture cannot independently prepare the requested scenario.

§Errors

Returns FixtureError when fixture setup fails.

Source

fn copy_fallback_only(&self) -> bool

Reports whether copy requests must use the stream fallback.

Override this when the fixture is designed to exercise only fallback copying, so contract checks do not expect provider-native fast paths.

§Returns

true when the suite must restrict copy checks to stream fallback; otherwise, false.

Source

fn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String>

Maps a relative list prefix for the supplied root.

§Parameters
  • root - Logical directory passed to the list operation.
  • relative - Testkit-relative descendant selected by the contract.
§Returns

The provider-specific prefix expected by its list implementation.

§Errors

Returns FixtureError when the prefix cannot be represented for the supplied root.

Source

fn seed_file( &self, relative: &str, bytes: &[u8], ) -> FixtureResult<FixtureSupport<Path>>

Seeds a complete file outside the operation currently under test.

§Parameters
  • relative - Testkit-relative path for the seeded file.
  • bytes - Exact content to publish.
§Returns

Supported(path) when seeding succeeds, or Unsupported when the fixture cannot prepare files out of band.

§Errors

Returns FixtureError when provider-specific setup fails.

Source

fn read_file(&self, path: &Path) -> FixtureResult<FixtureSupport<Vec<u8>>>

Reads a complete file outside the operation currently under test.

§Parameters
  • path - Logical path to observe.
§Returns

Supported(bytes) with the complete content, or Unsupported when the fixture cannot observe files out of band.

§Errors

Returns FixtureError when provider-specific observation fails.

Source

fn exists_out_of_band(&self, path: &Path) -> FixtureResult<FixtureSupport<bool>>

Observes whether a resource exists without using the tested facade.

This independent observation lets a contract check distinguish the operation’s effect from the facade’s own reported result.

§Parameters
  • path - Logical resource path to inspect.
§Returns

Supported(true) or Supported(false) when existence can be observed, or Unsupported when no independent observation is available.

§Errors

Returns FixtureError when the provider’s independent observation fails.

Source

fn write_file_out_of_band( &self, path: &Path, bytes: &[u8], ) -> FixtureResult<FixtureSupport<()>>

Writes a complete resource through fixture-owned setup facilities.

This hook prepares or restores state without exercising the facade operation whose contract is under test.

§Parameters
  • path - Logical resource path to write.
  • bytes - Exact content to publish.
§Returns

Supported(()) when the out-of-band write is available, or Unsupported when the fixture cannot write independently.

§Errors

Returns FixtureError when fixture-owned setup fails.

Source

fn resource_version( &self, path: &Path, ) -> FixtureResult<FixtureSupport<ResourceVersion>>

Observes the current provider version outside the operation under test.

The returned token is evidence for version-conditional contract checks and must come from an observation independent of the tested operation.

§Parameters
  • path - Logical resource path whose version is observed.
§Returns

Supported(version) when a provider version is available, or Unsupported when it cannot be observed independently.

§Errors

Returns FixtureError when version observation fails.

Source

fn stale_resource_version( &self, path: &Path, ) -> FixtureResult<FixtureSupport<ResourceVersion>>

Returns a valid version that does not match the current resource.

The token must be valid for the provider’s conditional operation while being guaranteed not to identify the resource’s current version.

§Parameters
  • path - Logical resource path whose current version must not match.
§Returns

Supported(version) with a valid stale token, or Unsupported when the fixture cannot establish that condition.

§Errors

Returns FixtureError when stale-token preparation fails.

Source

fn checksum_failure_case( &self, relative: &str, ) -> FixtureResult<FixtureSupport<Path>>

Supplies an independently prepared resource whose checksum is invalid.

The resource must be readable as a checksum-corruption scenario without using the read operation under test to create the corruption.

§Parameters
  • relative - Testkit-relative path for the corrupted resource.
§Returns

Supported(path) when an invalid-checksum resource is prepared, or Unsupported when the provider cannot offer this scenario.

§Errors

Returns FixtureError when preparation fails.

Source

fn seed_empty_directory( &self, relative: &str, ) -> FixtureResult<FixtureSupport<Path>>

Seeds an empty directory or prefix outside the operation under test.

Providers may represent directories as explicit resources or prefixes; the returned path identifies the seeded logical root in either model.

§Parameters
  • relative - Testkit-relative path for the empty directory.
§Returns

Supported(path) when setup succeeds, or Unsupported when this provider cannot seed an empty directory.

§Errors

Returns FixtureError when setup fails.

Seeds a symbolic link outside the operation under test.

The link target is chosen by the provider; this hook reports support only when the resulting link can be used by the relevant contract.

§Parameters
  • relative - Testkit-relative path at which to create the link.
§Returns

Supported(path) when the link is prepared, or Unsupported when the provider cannot create a suitable symbolic link.

§Errors

Returns FixtureError when link setup fails.

Source

fn copy_fast_path_case( &self, method: CopyMethod, ) -> FixtureResult<FixtureSupport<CopyFixtureCase>>

Supplies a case in which the requested native copy method must apply.

§Parameters
  • method - Native copy method the prepared request must exercise.
§Returns

Supported(case) when the fixture can prepare an applicable request, or Unsupported when no such provider-specific case is available. For Native, the case must be a single file with a distinct, independently confirmed absent target and an independently seeded source containing 1..=64 KiB. Return Unsupported when those native-specific premises cannot be guaranteed; a streamed result does not satisfy this request. The source and target are registered for fixture cleanup as soon as the case is returned.

§Errors

Returns FixtureError when provider-specific case preparation fails.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§