Skip to main content

qubit_fs_testkit/
fixture_error.rs

1// =============================================================================
2//    Copyright (c) 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Errors raised while a fixture prepares or observes a contract resource.
9
10use std::error::Error;
11use std::fmt::Debug;
12use std::fmt::Display;
13use std::fmt::Formatter;
14use std::fmt::Result as FmtResult;
15
16/// Failure raised by fixture setup or out-of-band observation.
17///
18/// # Examples
19///
20/// ```
21/// use qubit_fs_testkit::FixtureError;
22///
23/// let error = FixtureError::new("independent read setup unavailable");
24/// assert_eq!(error.to_string(), "independent read setup unavailable");
25/// ```
26#[must_use]
27pub struct FixtureError {
28    /// Human-readable context safe to expose through `Display` and `Debug`.
29    message: String,
30    /// Optional underlying failure retained for error-chain inspection.
31    source: Option<Box<dyn Error + Send + Sync + 'static>>,
32}
33
34impl FixtureError {
35    /// Creates an error with a human-readable fixture failure message.
36    ///
37    /// # Parameters
38    ///
39    /// * `message` - Safe diagnostic context for the fixture failure.
40    ///
41    /// # Returns
42    ///
43    /// A fixture error without an underlying source.
44    #[inline]
45    pub fn new(message: impl Into<String>) -> Self {
46        Self {
47            message: message.into(),
48            source: None,
49        }
50    }
51
52    /// Creates an error that preserves an underlying fixture failure as its
53    /// source.
54    ///
55    /// # Parameters
56    ///
57    /// * `message` - Safe diagnostic context for the fixture failure.
58    /// * `source` - Underlying error retained in the standard error chain.
59    ///
60    /// # Returns
61    ///
62    /// A fixture error wrapping the supplied source.
63    #[inline]
64    pub fn with_source(message: impl Into<String>, source: impl Error + Send + Sync + 'static) -> Self {
65        Self {
66            message: message.into(),
67            source: Some(Box::new(source)),
68        }
69    }
70}
71
72impl Debug for FixtureError {
73    /// Formats the error without requiring its source to implement `Debug`.
74    ///
75    /// # Parameters
76    ///
77    /// * `formatter` - Destination formatter receiving the safe debug view.
78    ///
79    /// # Returns
80    ///
81    /// The formatter result.
82    #[inline]
83    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
84        formatter
85            .debug_struct("FixtureError")
86            .field("message", &self.message)
87            .finish()
88    }
89}
90
91impl Display for FixtureError {
92    /// Displays the fixture failure message.
93    ///
94    /// # Parameters
95    ///
96    /// * `formatter` - Destination formatter receiving the safe message.
97    ///
98    /// # Returns
99    ///
100    /// The formatter result.
101    #[inline]
102    fn fmt(&self, formatter: &mut Formatter<'_>) -> FmtResult {
103        formatter.write_str(&self.message)
104    }
105}
106
107impl Error for FixtureError {
108    /// Returns the preserved fixture failure, when one was supplied.
109    ///
110    /// # Returns
111    ///
112    /// `Some(source)` when created by [`Self::with_source`], or `None` when
113    /// created by [`Self::new`].
114    #[inline]
115    fn source(&self) -> Option<&(dyn Error + 'static)> {
116        self.source.as_deref().map(|error| error as &(dyn Error + 'static))
117    }
118}
119
120/// Result returned by fixture setup and out-of-band observation hooks.
121///
122/// # Type Parameters
123///
124/// * `T` - Successful value produced by the fixture hook.
125///
126/// # Examples
127///
128/// ```
129/// use qubit_fs_testkit::{FixtureError, FixtureResult};
130///
131/// let ok: FixtureResult<u32> = Ok(9);
132/// let err: FixtureResult<u32> = Err(FixtureError::new("setup failed"));
133/// assert_eq!(ok.unwrap(), 9);
134/// assert!(err.is_err());
135/// ```
136pub type FixtureResult<T> = Result<T, FixtureError>;