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>;