Skip to main content

quack_rs/testing/
mod.rs

1// SPDX-License-Identifier: MIT
2// Copyright 2026 Tom F. <https://github.com/tomtom215/>
3// My way of giving something small back to the open source community
4// and encouraging more Rust development!
5
6//! Test utilities for `DuckDB` extension development.
7//!
8//! This module provides several complementary tools for testing extension code
9//! without spinning up a live `DuckDB` process:
10//!
11//! | Type | Purpose |
12//! |------|---------|
13//! | [`AggregateTestHarness`] | Test aggregate state update/combine/finalize logic |
14//! | [`MockVectorWriter`] | Write values to an in-memory buffer (replaces real output vector) |
15//! | [`MockVectorReader`] | Read values from an in-memory buffer (replaces real input vector) |
16//! | [`MockRegistrar`] | Verify which functions are registered, without a `DuckDB` connection |
17//! | `InMemoryDb` | Open a real bundled `DuckDB` for SQL-level tests (`bundled-test` feature) |
18//!
19//! # Architectural limitation: `loadable-extension` dispatch
20//!
21//! `DuckDB` loadable extensions use `libduckdb-sys` with
22//! `features = ["loadable-extension"]`. This routes every `DuckDB` C API call
23//! through a lazy dispatch table (a global `AtomicPtr` per function). The table
24//! is normally populated when `DuckDB` calls `duckdb_rs_extension_api_init` at
25//! extension-load time.
26//!
27//! **In `cargo test`, no `DuckDB` process loads the extension.** However,
28//! `InMemoryDb` works around this automatically: `InMemoryDb::open()` initialises
29//! the dispatch table from the bundled `DuckDB` symbols before opening a connection
30//! (see [Pitfall P9](https://quack-rs.com/reference/pitfalls.html#p9) for the full explanation).
31//!
32//! Without the `bundled-test` feature, the dispatch table is **not** initialised.
33//! Any direct `libduckdb-sys` call will panic with:
34//!
35//! ```text
36//! DuckDB API not initialized
37//! ```
38//!
39//! This affects:
40//!
41//! - `VectorReader::new` and `VectorWriter::new` — both call `duckdb_vector_get_data`
42//! - `Connection::register_*` — calls registration C API functions
43//! - `LogicalType::new` — calls `duckdb_create_logical_type`; `LogicalType::drop` calls
44//!   `duckdb_destroy_logical_type`
45//! - Any other code that touches `libduckdb-sys` symbols directly
46//!
47//! # What CAN be tested with `cargo test`
48//!
49//! - **Aggregate state logic** — use [`AggregateTestHarness`]
50//! - **Callback logic** — keep the per-row computation in plain Rust functions and test them directly; prototype row loops with [`MockVectorWriter`] / [`MockVectorReader`], which mirror a real vector's NULL and capacity behaviour (they are separate types from the real reader and writer)
51//! - **Registration structure** — use [`MockRegistrar`] (builders with only [`TypeId`][crate::types::TypeId] parameters)
52//! - **SQL macro SQL generation** — [`SqlMacro::to_sql()`][crate::sql_macro::SqlMacro::to_sql] is pure Rust
53//! - **Interval conversions** — [`interval_to_micros`][crate::interval::interval_to_micros] is pure Rust
54//! - **Validation / scaffold** — [`validate`][crate::validate] and [`scaffold`][crate::scaffold] are pure Rust
55//! - **SQL-level results** — use `InMemoryDb` (requires `bundled-test` Cargo feature)
56//!
57//! # What requires E2E tests (`SQLLogicTest`)
58//!
59//! - FFI wiring correctness (entry point, callback signatures)
60//! - Function registration success (Pitfall P6: registration can fail silently)
61//! - NULL handling through real `DuckDB` NULL propagation
62//! - Multi-group aggregation results
63//! - Extension loading without crash
64//!
65//! See the [testing guide](https://quack-rs.com/testing.html) and [Pitfall P3](https://quack-rs.com/reference/pitfalls.html#p3-e2e-testing-is-mandatory) for details.
66//!
67//! # Why you need both unit tests AND E2E tests
68//!
69//! **Unit tests (this module)** verify that your `MyState::update` and
70//! `MyState::combine` methods produce correct results. They run fast and
71//! catch logical bugs.
72//!
73//! **E2E tests (`DuckDB` CLI / ``SQLLogicTest``)** verify that the FFI wiring is
74//! correct — that `state_size`, `state_init`, `state_destroy`, and the
75//! callback signatures match what `DuckDB` expects.
76//!
77//! In duckdb-behavioral, 435 unit tests passed while the extension was completely
78//! broken due to three bugs that only E2E tests can catch:
79//! - SEGFAULT on load (wrong entry point)
80//! - 6 of 7 functions failing silently (function set name not set on each member)
81//! - Window funnel returning wrong results (combine not propagating config)
82//!
83//! **Unit tests alone are insufficient. Always run E2E tests.**
84//!
85//! # Example: testing aggregate logic
86//!
87//! ```rust
88//! use quack_rs::testing::AggregateTestHarness;
89//! use quack_rs::aggregate::AggregateState;
90//!
91//! #[derive(Default, Debug, PartialEq)]
92//! struct SumState { total: i64 }
93//! impl AggregateState for SumState {}
94//!
95//! impl SumState {
96//!     fn update(&mut self, value: i64) {
97//!         self.total += value;
98//!     }
99//! }
100//!
101//! let mut harness = AggregateTestHarness::<SumState>::new();
102//! harness.update(|s| s.update(10));
103//! harness.update(|s| s.update(20));
104//! harness.update(|s| s.update(5));
105//!
106//! let state = harness.finalize();
107//! assert_eq!(state.total, 35);
108//! ```
109//!
110//! # Example: testing callback output logic with mocks
111//!
112//! ```rust
113//! use quack_rs::testing::{MockVectorReader, MockVectorWriter};
114//!
115//! // A row loop prototyped against the mocks. The mocks share the real
116//! // reader/writer's method names but are distinct types.
117//! fn double_values(reader: &MockVectorReader, writer: &mut MockVectorWriter) {
118//!     for i in 0..reader.row_count() {
119//!         if reader.is_valid(i) {
120//!             let v = reader.try_get_i64(i).unwrap_or(0);
121//!             writer.write_i64(i, v * 2);
122//!         } else {
123//!             writer.set_null(i);
124//!         }
125//!     }
126//! }
127//!
128//! let reader = MockVectorReader::from_i64s([Some(1), None, Some(5)]);
129//! let mut writer = MockVectorWriter::new(3);
130//! double_values(&reader, &mut writer);
131//!
132//! assert_eq!(writer.try_get_i64(0), Some(2));
133//! assert!(writer.is_null(1));
134//! assert_eq!(writer.try_get_i64(2), Some(10));
135//! ```
136//!
137//! # Example: testing registration with `MockRegistrar`
138//!
139//! ```rust
140//! use quack_rs::connection::Registrar;
141//! use quack_rs::testing::MockRegistrar;
142//! use quack_rs::scalar::ScalarFunctionBuilder;
143//! use quack_rs::types::TypeId;
144//! use quack_rs::error::ExtensionError;
145//! use libduckdb_sys::{duckdb_data_chunk, duckdb_function_info, duckdb_vector};
146//!
147//! unsafe extern "C" fn my_fn(_: duckdb_function_info, _: duckdb_data_chunk, _: duckdb_vector) {}
148//!
149//! fn register_all(reg: &impl Registrar) -> Result<(), ExtensionError> {
150//!     let f = ScalarFunctionBuilder::new("my_fn")
151//!         .param(TypeId::BigInt)
152//!         .returns(TypeId::BigInt)
153//!         .function(my_fn);
154//!     unsafe { reg.register_scalar(f) }
155//! }
156//!
157//! let mock = MockRegistrar::new();
158//! register_all(&mock).unwrap();
159//! assert!(mock.has_scalar("my_fn"));
160//! ```
161
162pub mod harness;
163pub mod mock_registrar;
164pub mod mock_vector;
165
166#[cfg(feature = "_duckdb-testing")]
167pub mod in_memory_db;
168
169pub use harness::AggregateTestHarness;
170pub use mock_registrar::{CastRecord, MockRegistrar};
171pub use mock_vector::{MockDuckValue, MockVectorReader, MockVectorWriter};
172
173#[cfg(feature = "_duckdb-testing")]
174pub use in_memory_db::InMemoryDb;