Skip to main content

qubit_fs_testkit/
contract_run.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//! Results owned by a single filesystem contract execution session.
9
10use crate::ContractFailure;
11use crate::ContractReport;
12
13/// Retains contract evidence and execution diagnostics in the borrowing suite.
14///
15/// A completed run may fail its requirements. Completion means only that
16/// execution and its automatic cleanup attempt returned.
17///
18/// # Examples
19///
20/// ```
21/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
22/// # use support::RustdocSyncFixture;
23/// use qubit_fs_testkit::{FileSystemContract, FileSystemContractSuite};
24///
25/// let fixture = RustdocSyncFixture::new();
26/// let mut suite = FileSystemContractSuite::new(&fixture);
27/// suite.run_contract(FileSystemContract::Properties);
28/// let run = suite.run();
29/// assert!(!run.was_interrupted());
30/// assert!(!run.report().checks().is_empty());
31/// ```
32#[must_use]
33pub struct ContractRun {
34    /// Checks and evidence recorded during the contract execution.
35    pub(crate) report: ContractReport,
36    /// Cleanup completion and failures retained for this run.
37    pub(crate) cleanup: crate::CleanupReport,
38    /// Execution failures retained in observation order.
39    pub(crate) failures: Vec<ContractFailure>,
40    /// Whether execution started and may have been interrupted.
41    pub(crate) started: bool,
42    /// Whether execution returned and completed its cleanup attempt.
43    pub(crate) completed: bool,
44}
45
46impl ContractRun {
47    /// Creates the evidence container before any provider operation runs.
48    pub(crate) const fn new() -> Self {
49        Self {
50            report: ContractReport::new(),
51            cleanup: crate::CleanupReport::new(),
52            failures: Vec::new(),
53            started: false,
54            completed: false,
55        }
56    }
57
58    /// Returns the registered checks and their evidence.
59    ///
60    /// # Returns
61    ///
62    /// The report containing every check and its evidence.
63    #[must_use = "inspect the contract report"]
64    #[inline]
65    pub const fn report(&self) -> &ContractReport {
66        &self.report
67    }
68
69    /// Returns cleanup evidence and the history of all attempts.
70    ///
71    /// # Returns
72    ///
73    /// The cleanup report retained by this run.
74    #[must_use = "inspect the cleanup report"]
75    #[inline]
76    pub const fn cleanup(&self) -> &crate::CleanupReport {
77        &self.cleanup
78    }
79
80    /// Returns preserved failures in observation order.
81    ///
82    /// # Returns
83    ///
84    /// The failures recorded while executing the contract.
85    #[inline]
86    pub fn failures(&self) -> &[ContractFailure] {
87        &self.failures
88    }
89
90    /// Reports that a started session was dropped before returning its result.
91    ///
92    /// The runner exclusively borrows the suite while active. Callers can
93    /// inspect this retained state only after that borrow ends, including when
94    /// a pending execution or cleanup future is cancelled.
95    ///
96    /// # Returns
97    ///
98    /// `true` when the session started but did not complete.
99    #[must_use]
100    #[inline]
101    pub const fn was_interrupted(&self) -> bool {
102        self.started && !self.completed
103    }
104
105    /// Returns whether execution ended and every required check has evidence.
106    ///
107    /// # Returns
108    ///
109    /// `true` when execution, required evidence, and cleanup all succeeded.
110    #[must_use]
111    pub fn requirements_satisfied(&self) -> bool {
112        self.requirements_satisfied_with(&[])
113    }
114
115    /// Also requires evidence for caller-selected optional probes.
116    ///
117    /// Missing selections outside this run fail rather than being ignored.
118    ///
119    /// # Parameters
120    ///
121    /// * `required` - Optional check identities that must have evidence.
122    ///
123    /// # Returns
124    ///
125    /// `true` when execution and cleanup succeeded and every selected check
126    /// has evidence.
127    #[must_use]
128    pub fn requirements_satisfied_with(&self, required: &[crate::ContractCheckId]) -> bool {
129        self.execution_satisfied() && self.report.requirements_satisfied_with(required)
130    }
131
132    /// Includes every applicable optional probe in the evidence requirement.
133    ///
134    /// # Returns
135    ///
136    /// `true` when execution and cleanup succeeded and all applicable checks
137    /// have evidence.
138    #[must_use]
139    pub fn all_applicable_checks_verified(&self) -> bool {
140        self.execution_satisfied() && self.report.all_applicable_checks_verified()
141    }
142
143    /// Asserts the run's requirements and prints retained safe diagnostics.
144    ///
145    /// # Panics
146    /// Panics if execution, contract evidence, or cleanup did not succeed.
147    #[track_caller]
148    pub fn assert_satisfied(&self) {
149        self.assert_satisfied_with(&[]);
150    }
151
152    /// Asserts the run including caller-selected optional probes.
153    ///
154    /// # Panics
155    /// Panics for execution or cleanup failures and missing required evidence.
156    ///
157    /// # Parameters
158    ///
159    /// * `required` - Optional check identities that must have evidence.
160    #[track_caller]
161    pub fn assert_satisfied_with(&self, required: &[crate::ContractCheckId]) {
162        let diagnostics = self
163            .failures
164            .iter()
165            .chain(self.cleanup.failures().iter())
166            .map(ToString::to_string)
167            .collect::<Vec<_>>()
168            .join("; ");
169        assert!(
170            self.execution_satisfied(),
171            "[fs-testkit:run] completed={} cleanup_completed={}: {diagnostics}",
172            self.completed,
173            self.cleanup.completed()
174        );
175        self.report.assert_satisfied_with(required);
176    }
177
178    /// Keeps cleanup and lifecycle requirements identical for every policy.
179    #[must_use]
180    fn execution_satisfied(&self) -> bool {
181        self.completed && self.failures.is_empty() && self.cleanup.completed() && self.cleanup.failures().is_empty()
182    }
183}