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§
Sourcefn file_system(&self) -> &FileSystem
fn file_system(&self) -> &FileSystem
Returns the concrete synchronous filesystem facade under test.
§Returns
The isolated filesystem facade owned by this fixture.
Sourcefn path(&self, relative: &str) -> FixtureResult<Path>
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.
Sourcefn teardown(&self) -> FixtureResult<()>
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§
Sourcefn random_access_operation(&self) -> FixtureSupport<bool>
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.
Sourcefn replace_random_access_path(
&self,
path: &Path,
bytes: &[u8],
) -> FixtureResult<FixtureSupport<()>>
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.
Sourcefn snapshot_namespace_paths(&self) -> FixtureResult<FixtureSupport<Vec<Path>>>
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.
Sourcefn prepare_copy(
&self,
scenario: CopyScenario,
source_relative: &str,
target_relative: &str,
bytes: &[u8],
) -> FixtureResult<FixturePreparation<CopyFixtureCase>>
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.
Sourcefn prepare_delete(
&self,
_scenario: DeleteScenario,
relative: &str,
bytes: &[u8],
) -> FixtureResult<FixturePreparation<Path>>
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.
Sourcefn prepare_read(
&self,
scenario: ReadScenario,
relative: &str,
bytes: &[u8],
) -> FixtureResult<FixturePreparation<Path>>
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.
Sourcefn prepare_write(
&self,
scenario: WriteScenario,
relative: &str,
bytes: &[u8],
) -> FixtureResult<FixturePreparation<WriteFixtureCase>>
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.
Sourcefn copy_fallback_only(&self) -> bool
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.
Sourcefn list_prefix(&self, root: &Path, relative: &str) -> FixtureResult<String>
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.
Sourcefn seed_file(
&self,
relative: &str,
bytes: &[u8],
) -> FixtureResult<FixtureSupport<Path>>
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.
Sourcefn read_file(&self, path: &Path) -> FixtureResult<FixtureSupport<Vec<u8>>>
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.
Sourcefn exists_out_of_band(&self, path: &Path) -> FixtureResult<FixtureSupport<bool>>
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.
Sourcefn write_file_out_of_band(
&self,
path: &Path,
bytes: &[u8],
) -> FixtureResult<FixtureSupport<()>>
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.
Sourcefn resource_version(
&self,
path: &Path,
) -> FixtureResult<FixtureSupport<ResourceVersion>>
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.
Sourcefn stale_resource_version(
&self,
path: &Path,
) -> FixtureResult<FixtureSupport<ResourceVersion>>
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.
Sourcefn checksum_failure_case(
&self,
relative: &str,
) -> FixtureResult<FixtureSupport<Path>>
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.
Sourcefn seed_empty_directory(
&self,
relative: &str,
) -> FixtureResult<FixtureSupport<Path>>
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.
Sourcefn seed_symlink(&self, relative: &str) -> FixtureResult<FixtureSupport<Path>>
fn seed_symlink(&self, relative: &str) -> FixtureResult<FixtureSupport<Path>>
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.
Sourcefn copy_fast_path_case(
&self,
method: CopyMethod,
) -> FixtureResult<FixtureSupport<CopyFixtureCase>>
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".