Skip to main content

rustcmdpev_core/
testing.rs

1//! Shared test utilities for the workspace.
2//!
3//! Available unconditionally to keep the surface usable from binary crates,
4//! integration tests, and benches. Helpers fall in two buckets:
5//!
6//! 1. **Builders**: `LeafBuilder`, `with_children` — build [`Plan`] values
7//!    without repeating boilerplate `..Default::default()` blocks.
8//! 2. **Assertions**: `assert_contains_all`, `strip_ansi`, `node_count` —
9//!    encapsulate the multi-line patterns that `#[test]` files in
10//!    `tests/` keep re-implementing.
11//!
12//! These are intended for testing only but are exposed publicly so the
13//! `rustcmdpev` binary's integration tests can reuse them via the workspace
14//! dependency.
15
16use crate::structure::data::actuals::PlanActuals;
17use crate::structure::data::estimates::PlanEstimates;
18use crate::structure::data::explain::Explain;
19use crate::structure::data::plan::Plan;
20
21/// Builder for a leaf [`Plan`] with the most common fields populated.
22#[derive(Debug, Clone)]
23pub struct LeafBuilder {
24    node_type: String,
25    plan_rows: u64,
26    actual_rows: u64,
27    total_cost: f64,
28    actual_total_time: f64,
29    actual_loops: u64,
30    relation: Option<(String, String)>,
31    index: Option<String>,
32}
33
34impl LeafBuilder {
35    pub fn new(node_type: impl Into<String>) -> Self {
36        Self {
37            node_type: node_type.into(),
38            plan_rows: 1,
39            actual_rows: 1,
40            total_cost: 1.0,
41            actual_total_time: 1.0,
42            actual_loops: 1,
43            relation: None,
44            index: None,
45        }
46    }
47
48    pub fn rows(mut self, plan_rows: u64, actual_rows: u64) -> Self {
49        self.plan_rows = plan_rows;
50        self.actual_rows = actual_rows;
51        self
52    }
53
54    pub fn cost(mut self, total_cost: f64) -> Self {
55        self.total_cost = total_cost;
56        self
57    }
58
59    pub fn time(mut self, actual_total_time: f64) -> Self {
60        self.actual_total_time = actual_total_time;
61        self
62    }
63
64    pub fn loops(mut self, actual_loops: u64) -> Self {
65        self.actual_loops = actual_loops;
66        self
67    }
68
69    pub fn relation(mut self, schema: impl Into<String>, name: impl Into<String>) -> Self {
70        self.relation = Some((schema.into(), name.into()));
71        self
72    }
73
74    pub fn index(mut self, index_name: impl Into<String>) -> Self {
75        self.index = Some(index_name.into());
76        self
77    }
78
79    pub fn build(self) -> Plan {
80        let mut plan = Plan::default();
81        plan.identity.node_type = self.node_type;
82        if let Some((schema, name)) = self.relation {
83            plan.identity.schema = schema;
84            plan.identity.relation_name = name;
85        }
86        if let Some(index_name) = self.index {
87            plan.identity.index_name = index_name;
88        }
89        plan.estimates = PlanEstimates {
90            plan_rows: self.plan_rows,
91            total_cost: self.total_cost,
92            ..PlanEstimates::default()
93        };
94        plan.actuals = PlanActuals {
95            actual_total_time: self.actual_total_time,
96            actual_rows: self.actual_rows,
97            actual_loops: self.actual_loops,
98            ..PlanActuals::default()
99        };
100        plan
101    }
102}
103
104/// Wrap `parent` so it has `children` attached.
105pub fn with_children(mut parent: Plan, children: impl IntoIterator<Item = Plan>) -> Plan {
106    parent.plans = children.into_iter().collect();
107    parent
108}
109
110/// Build a single-plan [`Explain`] with optional execution/total cost.
111pub fn explain_for(plan: Plan, execution_time: f64, total_cost: f64) -> Explain {
112    Explain {
113        plan,
114        execution_time,
115        total_cost,
116        ..Explain::default()
117    }
118}
119
120/// Strip ANSI escape sequences from `input` for resilient text assertions.
121pub fn strip_ansi(input: &str) -> String {
122    let mut out = String::with_capacity(input.len());
123    let mut chars = input.chars().peekable();
124    while let Some(ch) = chars.next() {
125        if ch == '\u{1b}' && chars.peek() == Some(&'[') {
126            let _ = chars.next();
127            for next in chars.by_ref() {
128                if ('@'..='~').contains(&next) {
129                    break;
130                }
131            }
132            continue;
133        }
134        out.push(ch);
135    }
136    out
137}
138
139/// Assert that `text` contains every needle in `needles`. Reports the *first*
140/// missing needle with a snippet of the surrounding text so failures point at
141/// the exact missing token instead of a wall of text.
142#[track_caller]
143pub fn assert_contains_all(text: &str, needles: &[&str]) {
144    for needle in needles {
145        assert!(
146            text.contains(needle),
147            "expected output to contain {needle:?}\n--- output ---\n{text}\n--- end ---"
148        );
149    }
150}
151
152/// Assert that `text` contains *none* of the substrings in `needles`.
153#[track_caller]
154pub fn assert_contains_none(text: &str, needles: &[&str]) {
155    for needle in needles {
156        assert!(
157            !text.contains(needle),
158            "expected output to NOT contain {needle:?}\n--- output ---\n{text}\n--- end ---"
159        );
160    }
161}
162
163/// Recursively count nodes in a plan tree.
164pub fn node_count(plan: &Plan) -> usize {
165    1 + plan.plans.iter().map(node_count).sum::<usize>()
166}
167
168/// Recursively collect every node in a plan tree (depth-first, parent-first).
169pub fn collect_nodes(plan: &Plan) -> Vec<&Plan> {
170    let mut out = Vec::new();
171    collect(plan, &mut out);
172    out
173}
174
175fn collect<'a>(plan: &'a Plan, out: &mut Vec<&'a Plan>) {
176    out.push(plan);
177    for child in &plan.plans {
178        collect(child, out);
179    }
180}
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185
186    #[test]
187    fn leaf_builder_populates_typical_fields() {
188        let plan = LeafBuilder::new("Seq Scan")
189            .rows(100, 95)
190            .cost(12.5)
191            .time(0.75)
192            .loops(2)
193            .relation("public", "users")
194            .build();
195        assert_eq!(plan.identity.node_type, "Seq Scan");
196        assert_eq!(plan.identity.schema, "public");
197        assert_eq!(plan.identity.relation_name, "users");
198        assert_eq!(plan.estimates.plan_rows, 100);
199        assert_eq!(plan.actuals.actual_rows, 95);
200        assert_eq!(plan.actuals.actual_loops, 2);
201        assert!((plan.estimates.total_cost - 12.5).abs() < 1e-9);
202    }
203
204    #[test]
205    fn with_children_attaches_subplans() {
206        let parent = with_children(
207            LeafBuilder::new("Hash Join").build(),
208            [
209                LeafBuilder::new("Seq Scan").build(),
210                LeafBuilder::new("Index Scan").build(),
211            ],
212        );
213        assert_eq!(parent.plans.len(), 2);
214        assert_eq!(parent.plans[0].identity.node_type, "Seq Scan");
215    }
216
217    #[test]
218    fn strip_ansi_removes_escape_sequences() {
219        let input = "\u{1b}[31mhello\u{1b}[0m world";
220        assert_eq!(strip_ansi(input), "hello world");
221    }
222
223    #[test]
224    fn assert_contains_all_passes_when_all_present() {
225        assert_contains_all("alpha bravo charlie", &["alpha", "charlie"]);
226    }
227
228    #[test]
229    #[should_panic(expected = "delta")]
230    fn assert_contains_all_panics_with_missing_needle() {
231        assert_contains_all("alpha bravo", &["alpha", "delta"]);
232    }
233
234    #[test]
235    fn node_count_walks_full_tree() {
236        let plan = with_children(
237            LeafBuilder::new("Hash Join").build(),
238            [
239                with_children(
240                    LeafBuilder::new("Sort").build(),
241                    [LeafBuilder::new("Seq Scan").build()],
242                ),
243                LeafBuilder::new("Index Scan").build(),
244            ],
245        );
246        assert_eq!(node_count(&plan), 4);
247        assert_eq!(collect_nodes(&plan).len(), 4);
248    }
249}