Skip to main content

qubit_fs_testkit/
cleanup_report.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//! Cleanup evidence retained across explicit retries.
9
10use crate::ContractFailure;
11
12/// Cleanup attempts and their historical failures.
13///
14/// A later successful teardown does not erase a failed facade deletion.
15///
16/// # Examples
17///
18/// ```
19/// # mod support { include!(concat!(env!("CARGO_MANIFEST_DIR"), "/tests/common/rustdoc_support.rs")); }
20/// # use support::RustdocSyncFixture;
21/// use qubit_fs_testkit::{FileSystemContract, FileSystemContractSuite};
22///
23/// let fixture = RustdocSyncFixture::new();
24/// let mut suite = FileSystemContractSuite::new(&fixture);
25/// suite.run_contract(FileSystemContract::Properties);
26/// assert!(suite.run().cleanup().completed());
27/// ```
28#[must_use]
29pub struct CleanupReport {
30    /// Number of cleanup attempts that started, including cancelled attempts.
31    pub(crate) attempts: usize,
32    /// Whether the latest cleanup attempt returned successfully.
33    pub(crate) completed: bool,
34    /// Failures observed across all cleanup attempts, in observation order.
35    pub(crate) failures: Vec<ContractFailure>,
36}
37
38impl CleanupReport {
39    /// Creates an empty cleanup history.
40    pub(crate) const fn new() -> Self {
41        Self {
42            attempts: 0,
43            completed: false,
44            failures: Vec::new(),
45        }
46    }
47
48    /// Returns the number of cleanup attempts started, including cancelled
49    /// ones.
50    ///
51    /// # Returns
52    /// The number of attempts that began before this report was observed.
53    #[must_use = "inspect the retained cleanup failures"]
54    #[inline]
55    pub const fn attempts(&self) -> usize {
56        self.attempts
57    }
58
59    /// Returns whether the latest cleanup attempt returned successfully.
60    ///
61    /// # Returns
62    /// `true` when the latest attempt returned successfully, and `false` when
63    /// it failed or was cancelled.
64    #[must_use = "inspect the retained cleanup failures"]
65    #[inline]
66    pub const fn completed(&self) -> bool {
67        self.completed
68    }
69
70    /// Returns every observed failure, including failures before a retry.
71    ///
72    /// # Returns
73    /// The failures from all attempts in the order they were observed.
74    #[must_use = "inspect the retained cleanup failures"]
75    #[inline]
76    pub fn failures(&self) -> &[ContractFailure] {
77        &self.failures
78    }
79}