waterui-testing 0.3.0

Headless testing helpers for WaterUI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

use std::path::{Path, PathBuf};

use crate::Snapshot;

/// Snapshot captured to `WaterUI`'s canonical test artifact layout.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CapturedSnapshot {
    snapshot: Snapshot,
    path: PathBuf,
}

impl CapturedSnapshot {
    /// Creates a captured snapshot record from pixels and output path.
    #[must_use]
    pub const fn new(snapshot: Snapshot, path: PathBuf) -> Self {
        Self { snapshot, path }
    }

    /// Returns the captured pixels.
    #[must_use]
    pub const fn snapshot(&self) -> &Snapshot {
        &self.snapshot
    }

    /// Returns the path where the snapshot was written.
    #[must_use]
    pub fn path(&self) -> &Path {
        &self.path
    }

    /// Splits the captured snapshot into pixels and output path.
    #[must_use]
    pub fn into_parts(self) -> (Snapshot, PathBuf) {
        (self.snapshot, self.path)
    }
}

/// Centralized artifact output helper for `WaterUI` tests.
#[derive(Debug, Clone)]
pub struct TestArtifacts {
    root: PathBuf,
}

impl TestArtifacts {
    /// Creates an artifact store rooted under the given suite name.
    #[must_use]
    pub fn new(suite: impl AsRef<str>) -> Self {
        let root = artifact_root().join(suite.as_ref());
        Self { root }
    }

    /// Returns the root directory used by this suite.
    #[must_use]
    pub fn root(&self) -> &Path {
        &self.root
    }

    /// Returns the directory for one logical test case.
    #[must_use]
    pub fn case_dir(&self, case: impl AsRef<str>) -> PathBuf {
        self.root.join(case.as_ref())
    }

    /// Builds the canonical PNG path for a named snapshot stage.
    #[must_use]
    pub fn snapshot_path(&self, case: impl AsRef<str>, stage: impl AsRef<str>) -> PathBuf {
        self.case_dir(case).join(format!("{}.png", stage.as_ref()))
    }

    /// Saves one snapshot and returns both the pixels and canonical artifact path.
    ///
    /// # Panics
    ///
    /// Panics if the PNG cannot be written to the artifact directory.
    pub fn capture_snapshot(
        &self,
        case: impl AsRef<str>,
        stage: impl AsRef<str>,
        snapshot: Snapshot,
    ) -> CapturedSnapshot {
        let path = self.snapshot_path(case, stage);
        snapshot
            .save_png(&path)
            .expect("TestArtifacts::capture_snapshot: snapshot PNG should be writable");
        CapturedSnapshot::new(snapshot, path)
    }

    /// Saves one snapshot using `WaterUI`'s canonical artifact layout.
    pub fn save_snapshot(
        &self,
        case: impl AsRef<str>,
        stage: impl AsRef<str>,
        snapshot: &Snapshot,
    ) -> PathBuf {
        self.capture_snapshot(case, stage, snapshot.clone())
            .into_parts()
            .1
    }
}

/// Returns the global artifact root used by `WaterUI` tests.
#[must_use]
pub fn artifact_root() -> PathBuf {
    std::env::var_os("WATERUI_TEST_ARTIFACTS_DIR").map_or_else(
        || std::env::temp_dir().join("waterui-testing-artifacts"),
        PathBuf::from,
    )
}