Skip to main content

vortex_array/test_harness/execution_paths/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Assertions for batch, row, and constant execution of the same operation.
5//!
6//! Each path uses a fresh operation and an explicit expected result, so agreement alone cannot
7//! conceal a shared mistake. Empty arrays have no rows to probe and only exercise batch execution.
8
9use std::fmt::Display;
10
11use vortex_error::VortexExpect;
12use vortex_error::VortexResult;
13use vortex_error::vortex_panic;
14
15use crate::ArrayRef;
16use crate::ExecutionCtx;
17use crate::IntoArray;
18use crate::RecursiveCanonical;
19use crate::arrays::ConstantArray;
20use crate::assert_arrays_eq;
21
22/// The result that every applicable execution path must produce.
23#[derive(Debug)]
24pub enum ExpectedOutcome {
25    /// The expected dtype, length, nulls, and values.
26    Array(ArrayRef),
27    /// An error from construction or execution, including each individual row.
28    Error,
29}
30
31impl ExpectedOutcome {
32    fn row(&self, index: usize) -> Self {
33        match self {
34            Self::Array(array) => Self::Array(
35                array
36                    .slice(index..index + 1)
37                    .vortex_expect("expected output length matches the input length"),
38            ),
39            Self::Error => Self::Error,
40        }
41    }
42}
43
44/// Assert that an operation matches `expected` on batch, row, and constant inputs.
45///
46/// `inputs` must contain at least one array, and every input must have the same length. The
47/// operation must preserve that length. Input rows must be readable independently of the operation.
48///
49/// Batch execution recursively materializes the result before comparison. Row execution reads a
50/// fresh lazy result with [`ArrayRef::execute_scalar`]. Constant execution builds another operation
51/// for each row, with all inputs replaced by one-row [`ConstantArray`]s, then materializes it.
52/// [`ExpectedOutcome::Error`] requires every observed row to fail, even when batch execution fails.
53/// For empty arrays, only the batch path is checked because no row or constant input exists.
54///
55/// # Panics
56///
57/// Panics if the input requirements do not hold or an execution path differs from `expected`.
58#[track_caller]
59pub fn assert_execution_paths(
60    inputs: &[ArrayRef],
61    operation: impl Fn(&[ArrayRef]) -> VortexResult<ArrayRef>,
62    expected: ExpectedOutcome,
63    ctx: &mut ExecutionCtx,
64) {
65    let first = inputs
66        .first()
67        .vortex_expect("execution path assertions require at least one input");
68    let len = first.len();
69    assert!(
70        inputs.iter().all(|input| input.len() == len),
71        "input arrays must have equal lengths"
72    );
73
74    if let ExpectedOutcome::Array(expected) = &expected {
75        assert_eq!(
76            expected.len(),
77            len,
78            "expected output length must match the inputs"
79        );
80    }
81
82    let batch = operation(inputs).and_then(|array| execute_batch(array, ctx));
83    assert_outcome(batch, &expected, "batch", ctx);
84
85    if len == 0 {
86        return;
87    }
88
89    match operation(inputs) {
90        Ok(array) => {
91            assert_eq!(array.len(), len, "row output length must match the inputs");
92            if let ExpectedOutcome::Array(expected) = &expected {
93                assert_eq!(array.dtype(), expected.dtype());
94            }
95
96            for index in 0..len {
97                let row = array
98                    .execute_scalar(index, ctx)
99                    .map(|scalar| ConstantArray::new(scalar, 1).into_array());
100                assert_outcome(row, &expected.row(index), format_args!("row {index}"), ctx);
101            }
102        }
103        Err(error) => assert_outcome(Err(error), &expected, "row construction", ctx),
104    }
105
106    for index in 0..len {
107        let constants = inputs
108            .iter()
109            .map(|input| {
110                let scalar = input.execute_scalar(index, ctx).vortex_expect(
111                    "test input rows must be readable before applying the operation",
112                );
113                ConstantArray::new(scalar, 1).into_array()
114            })
115            .collect::<Vec<_>>();
116        let constant = operation(&constants).and_then(|array| execute_batch(array, ctx));
117        assert_outcome(
118            constant,
119            &expected.row(index),
120            format_args!("constant row {index}"),
121            ctx,
122        );
123    }
124}
125
126fn execute_batch(array: ArrayRef, ctx: &mut ExecutionCtx) -> VortexResult<ArrayRef> {
127    Ok(array.execute::<RecursiveCanonical>(ctx)?.0.into_array())
128}
129
130#[track_caller]
131fn assert_outcome(
132    actual: VortexResult<ArrayRef>,
133    expected: &ExpectedOutcome,
134    path: impl Display,
135    ctx: &mut ExecutionCtx,
136) {
137    match (actual, expected) {
138        (Ok(actual), ExpectedOutcome::Array(expected)) => assert_arrays_eq!(actual, expected, ctx),
139        (Err(_), ExpectedOutcome::Error) => {}
140        (Err(error), ExpectedOutcome::Array(_)) => vortex_panic!("{path} path failed: {error}"),
141        (Ok(actual), ExpectedOutcome::Error) => {
142            vortex_panic!(
143                "{path} path must return an error, got {} rows",
144                actual.len()
145            );
146        }
147    }
148}
149
150#[cfg(test)]
151mod tests;