qubit-fs-testkit 0.7.0

Reusable provider contract checks for qubit-fs implementations
Documentation
// =============================================================================
//    Copyright (c) 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================
//! Structured filesystem error assertions.

use qubit_fs::error::FsError;
use qubit_fs::error::FsErrorKind;
use qubit_fs::error::FsOperation;
use qubit_fs::metadata::FileSystemCapability;
use qubit_fs::path::Path;

/// Checks all structured fields required by one filesystem contract.
///
/// # Parameters
///
/// * `error` - Actual provider error.
/// * `kind` - Required error classification.
/// * `operation` - Required public operation.
/// * `path` - Required path when the contract is path-scoped.
/// * `provider` - Expected provider identifier when the error reports provider
///   context.
/// * `capability` - Required capability when the error reports one.
///
/// # Panics
///
/// Panics when any expected field differs from the actual error.
#[track_caller]
#[allow(dead_code)]
pub(crate) fn assert_error(
    error: &FsError,
    kind: FsErrorKind,
    operation: FsOperation,
    path: Option<&Path>,
    provider: Option<&str>,
    capability: Option<FileSystemCapability>,
) {
    assert_eq!(kind, error.kind(), "filesystem error kind must match");
    assert_eq!(operation, error.operation(), "filesystem error operation must match",);
    assert_eq!(path, error.path(), "filesystem error path must match");
    assert!(
        error.provider().is_none() || error.provider() == provider,
        "filesystem error provider must be absent or match the configured provider",
    );
    assert_eq!(
        capability,
        error.required_capability(),
        "filesystem error required capability must match",
    );
}

/// Checks all structured fields for an error that includes a destination path.
///
/// # Parameters
///
/// * `error` - Actual provider error.
/// * `kind` - Required error classification.
/// * `operation` - Required public operation.
/// * `path` - Required source path.
/// * `target` - Required destination path.
/// * `provider` - Required provider identifier.
/// * `capability` - Required capability when the error reports one.
///
/// # Panics
///
/// Panics when any expected field differs from the actual error.
#[track_caller]
#[allow(dead_code)]
pub(crate) fn assert_error_with_target(
    error: &FsError,
    kind: FsErrorKind,
    operation: FsOperation,
    path: Option<&Path>,
    target: Option<&Path>,
    provider: Option<&str>,
    capability: Option<FileSystemCapability>,
) {
    assert_error(error, kind, operation, path, provider, capability);
    assert_eq!(target, error.target(), "filesystem error target must match");
}

/// Checks a two-path operation error whose primary path is the concrete
/// failure location.
///
/// Providers may detect a source-side or destination-side conflict first. The
/// public error therefore preserves either request path as its primary path
/// and always retains the destination in `target`.
#[track_caller]
#[allow(dead_code)]
pub(crate) fn assert_error_with_source_or_target(
    error: &FsError,
    kind: FsErrorKind,
    operation: FsOperation,
    source: &Path,
    target: &Path,
    provider: Option<&str>,
    capability: Option<FileSystemCapability>,
) {
    assert_eq!(kind, error.kind(), "filesystem error kind must match");
    assert_eq!(operation, error.operation(), "filesystem error operation must match");
    assert!(
        matches!(error.path(), Some(path) if path == source || path == target),
        "filesystem error path must identify the source or target failure location",
    );
    assert_eq!(Some(target), error.target(), "filesystem error target must match");
    assert!(
        error.provider().is_none() || error.provider() == provider,
        "filesystem error provider must be absent or match the configured provider",
    );
    assert_eq!(
        capability,
        error.required_capability(),
        "filesystem error required capability must match"
    );
}

/// Checks the required fields of an unsupported-operation error.
///
/// # Parameters
///
/// * `error` - Actual provider error.
/// * `kind` - Required error classification.
/// * `operation` - Required public operation.
/// * `path` - Required source path.
/// * `provider` - Configured provider identifier, when one is available.
/// * `capability` - Required unsupported capability.
///
/// # Panics
///
/// Panics when a required field differs, or when a reported provider does not
/// match the configured provider. Missing provider context remains valid for
/// trait-default errors.
#[track_caller]
#[allow(dead_code)]
pub(crate) fn assert_unsupported_error(
    error: &FsError,
    kind: FsErrorKind,
    operation: FsOperation,
    path: Option<&Path>,
    provider: Option<&str>,
    capability: Option<FileSystemCapability>,
) {
    assert_eq!(kind, error.kind(), "filesystem error kind must match");
    assert_eq!(operation, error.operation(), "filesystem error operation must match",);
    assert_eq!(path, error.path(), "filesystem error path must match");
    assert_eq!(
        capability,
        error.required_capability(),
        "filesystem error required capability must match",
    );
    assert!(
        error.provider().is_none() || error.provider() == provider,
        "filesystem error provider must be absent or match the configured provider",
    );
}

/// Validates a missing-resource error while preserving a mismatched source.
pub(crate) fn verify_missing_error(
    error: FsError,
    path: &Path,
    provider: &str,
    check: crate::ContractCheckId,
) -> Result<(), crate::ContractFailure> {
    let valid = error.kind() == FsErrorKind::NotFound
        && error.operation() == FsOperation::Stat
        && error.path() == Some(path)
        && error.target().is_none()
        && error.required_capability().is_none()
        && error.provider().is_none_or(|actual| actual == provider);
    if valid {
        Ok(())
    } else {
        Err(
            crate::ContractFailure::with_source("missing-resource error context differs from the contract", error)
                .at(check),
        )
    }
}

/// Checks structured fields using an ordinary error return and owned source.
pub(crate) fn verify_fs_error(
    error: FsError,
    kind: FsErrorKind,
    operation: FsOperation,
    path: &Path,
    provider: &str,
    capability: Option<FileSystemCapability>,
    check: crate::ContractCheckId,
) -> Result<(), crate::ContractFailure> {
    let valid = error.kind() == kind
        && error.operation() == operation
        && error.path() == Some(path)
        && error.required_capability() == capability
        && error.provider().is_none_or(|actual| actual == provider);
    if valid {
        Ok(())
    } else {
        Err(crate::ContractFailure::with_source(format!("{check}: filesystem error context mismatch"), error).at(check))
    }
}

/// Returns a check-attributed failure without formatting observed provider
/// data.
pub(crate) fn verify_condition(
    condition: bool,
    check: crate::ContractCheckId,
    message: &str,
) -> Result<(), crate::ContractFailure> {
    if condition {
        Ok(())
    } else {
        Err(crate::ContractFailure::message_only(format!("{check}: {message}")).at(check))
    }
}