Crate turso_macros

Expand description

§============================================================================= Antithesis Assertion Macros

These macros define correctness properties for Antithesis autonomous testing. They wrap the Antithesis SDK assertion macros and double as standard Rust assertions, giving us a single assertion layer that works both in normal builds and under Antithesis fuzzing.

§The `antithesis` feature flag

All macros compile to different code depending on whether --features antithesis is enabled:

Without the feature: macros behave like their std counterparts (assert!, debug_assert!, unreachable!, etc.), or are no-ops for observational macros.
With the feature: macros additionally report to the Antithesis SDK. On failure, “always” assertions print an error to stderr and call std::process::exit(0) instead of panicking. This clean exit lets Antithesis properly process the property violation.

§Five categories of assertions

Condition assertions (turso_assert!, turso_debug_assert!) Drop-in replacements for assert!/debug_assert! that also report to Antithesis.
Sometimes assertions (turso_assert_sometimes!, turso_assert_sometimes_greater_than!, turso_assert_sometimes_less_than!, turso_assert_sometimes_greater_than_or_equal!, turso_assert_sometimes_less_than_or_equal!) Observational only — never panic. Tell Antithesis “this condition should be true at least once across all test runs.” Useful for verifying the fuzzer explores both sides of a branch.
Boolean guidance (turso_assert_some!, turso_assert_all!) Multi-condition assertions that provide better guidance to the Antithesis fuzzer. some = at least one condition must be true (OR), all = every condition must be true (AND). Panics on failure (or exit(0) with antithesis feature).
Reachability assertions (turso_assert_reachable!, turso_assert_unreachable!, turso_soft_unreachable!) Verify whether code paths are or aren’t hit during testing.
Comparison assertions (turso_assert_eq!, turso_assert_ne!, turso_assert_greater_than!, turso_assert_greater_than_or_equal!, turso_assert_less_than!, turso_assert_less_than_or_equal!) Typed comparison assertions that provide richer information to Antithesis than a plain turso_assert!(a > b).

§Note: fuzzer guidance temporarily disabled

The Antithesis SDK provides specialized numeric_guidance_helper! and boolean_guidance_helper! macros that give the fuzzer detailed numeric/boolean values to guide exploration. These were previously used by comparison and boolean macros but are currently disabled (replaced with plain assert_always_or_unreachable! / assert_sometimes!) while Antithesis investigates an issue.

The macros still work correctly as assertions — they just don’t give the fuzzer as much detail to work with. Guidance will be restored when the issue is resolved.

§Quick reference

Macro	Antithesis SDK	Panics?	Notes
`turso_assert!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	Drop-in for `assert!`
`turso_debug_assert!`	`assert_always_or_unreachable!`	Debug only (exit(0) w/ feature)	Drop-in for `debug_assert!`
`turso_assert_sometimes!`	`assert_sometimes!`	Never	Observational only
`turso_assert_some!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	OR of named conditions
`turso_assert_all!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	AND of named conditions
`turso_assert_reachable!`	(no-op)	Never	Pending better SQL generation
`turso_assert_unreachable!`	`assert_unreachable!`	Yes (exit(0) w/ feature)	Hard unreachable
`turso_soft_unreachable!`	`assert_unreachable!`	Never	Soft signal, no-op w/o feature
`turso_assert_eq!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	Drop-in for `assert_eq!`
`turso_assert_ne!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	Drop-in for `assert_ne!`
`turso_assert_greater_than!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	`left > right`
`turso_assert_greater_than_or_equal!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	`left >= right`
`turso_assert_less_than!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	`left < right`
`turso_assert_less_than_or_equal!`	`assert_always_or_unreachable!`	Yes (exit(0) w/ feature)	`left <= right`
`turso_assert_sometimes_greater_than!`	`assert_sometimes!`	Never	Observational `left > right`
`turso_assert_sometimes_less_than!`	`assert_sometimes!`	Never	Observational `left < right`
`turso_assert_sometimes_greater_than_or_equal!`	`assert_sometimes!`	Never	Observational `left >= right`
`turso_assert_sometimes_less_than_or_equal!`	`assert_sometimes!`	Never	Observational `left <= right`

Macros§

match_ignore_ascii_case: match_ignore_ascii_case will generate trie-like tree matching from normal match expression. example:
register_extension: Register your extension with ‘core’ by providing the relevant functions
turso_assert: Drop-in replacement for assert! that additionally reports to the Antithesis SDK when compiled with --features antithesis.
turso_assert_all: Asserts that all named conditions are true whenever this line is reached (logical AND).
turso_assert_eq: Drop-in replacement for assert_eq! that additionally reports to the Antithesis SDK in Antithesis builds (--cfg=antithesis).
turso_assert_greater_than: Asserts that left > right, providing richer comparison information to Antithesis than a plain turso_assert!(a > b).
turso_assert_greater_than_or_equal: Asserts that left >= right, providing richer comparison information to Antithesis than a plain turso_assert!(a >= b).
turso_assert_less_than: Asserts that left < right, providing richer comparison information to Antithesis than a plain turso_assert!(a < b).
turso_assert_less_than_or_equal: Asserts that left <= right, providing richer comparison information to Antithesis than a plain turso_assert!(a <= b).
turso_assert_ne: Drop-in replacement for assert_ne! that additionally reports to the Antithesis SDK in Antithesis builds (--cfg=antithesis).
turso_assert_reachable: Asserts that a code path is reached at least once during Antithesis testing. No-op in non-antithesis builds.
turso_assert_some: Asserts that at least one of multiple named conditions is true whenever this line is reached (logical OR). All conditions are evaluated.
turso_assert_sometimes: Observational assertion: tells Antithesis that a condition should be true at least once across all test runs. Never panics.
turso_assert_sometimes_greater_than: Observational assertion: tells Antithesis that left > right should be true at least once across all test runs. Never panics.
turso_assert_sometimes_greater_than_or_equal: Observational assertion: tells Antithesis that left >= right should be true at least once across all test runs. Never panics.
turso_assert_sometimes_less_than: Observational assertion: tells Antithesis that left < right should be true at least once across all test runs. Never panics.
turso_assert_sometimes_less_than_or_equal: Observational assertion: tells Antithesis that left <= right should be true at least once across all test runs. Never panics.
turso_assert_unreachable: Asserts that a code path is never reached. This is a hard assertion — it will terminate the program if the path is executed.
turso_debug_assert: Drop-in replacement for debug_assert! that additionally reports to the Antithesis SDK when compiled with --features antithesis.
turso_soft_unreachable: Soft unreachable: signals to Antithesis that this code path should never be reached, but does not panic or exit. Without the antithesis feature, this is a no-op.

Attribute Macros§

allocation_site: Wrap a function body in an allocation-site scope.
codspeed_criterion_benchmark
divan_bench
scalar: Declare a scalar function for your extension. This requires the name: #[scalar(name = “example”)] of what you wish to call your function with.
test: Test macro for core_tester crate
trace_stack: Wrap a function body in a stack trace guard and a turso_stack tracing span.

Derive Macros§

AggregateDerive: Define an aggregate function for your extension by deriving AggregateDerive on a struct that implements the AggFunc trait.
AtomicEnum: Derive macro for creating atomic wrappers for enums
Description: A procedural macro that derives a Description trait for enums. This macro extracts documentation comments (specified with /// Description...) for enum variants and generates an implementation for get_description, which returns the associated description.
ScalarDerive: Derive a context-aware scalar function for your extension by deriving ScalarDerive on a struct that implements the ScalarFunc trait.
VTabModuleDerive: Macro to derive a VTabModule for your extension. This macro will generate the necessary functions to register your module with core. You must implement the VTabModule, VTable, and VTabCursor traits.
VfsDerive