Assertion macros: values, fields, arrays, numerics, errors

charles commented

2026-04-11 10:55:38 +00:00

Owner

User story

As a test author, I want assertion macros that produce structured failure messages with file/line context, so that test failures are immediately actionable without printf-debugging.

Acceptance criteria

Mechanics

All assertions are #[macro_export] macros invoked from functions that return TestResult. On failure they return Err(TestError::Assertion { expected, got, context, location }).
Each macro captures concat!(file!(), ":", line!()) into location.
Failure messages render expected and got as pretty JSON for readable diffs.
Macros support an optional trailing , "context message" argument that populates context.

Value & field assertions (spec §3.1)

assert_ok!(value) — fails if value is a JSON-RPC error envelope ({"error": {...}}).
assert_field!(value, field, expected) — single-key equality.
assert_field!(value, path1, path2, ..., expected) — variadic for nested path traversal, resolving the spec inconsistency between §3.1 (3 args) and §9 (4 args). (Resolves spec review §3.)
assert_field_exists!(value, field) / assert_field_absent!(value, field).
assert_field_type!(value, field, "string"|"number"|"bool"|"array"|"object"|"null").

Array assertions (spec §3.2)

assert_array!(value, range) — accepts any RangeBounds<usize>: 1.., ..=5, 3..=3, etc. Fails with a clear "expected length in {range}, got {n}" message.
assert_array_contains!(value, |item| ...) — at least one item matches the closure.
assert_array_all!(value, |item| ...) — all items match.

Numeric assertions (spec §3.3)

assert_in_range!(value, range) — works for both integers and floats via RangeBounds<f64>.
assert_greater_than!(value, n), assert_less_than!(value, n).

Error assertions (spec §3.4)

assert_error!(value, code) — fails if value is not an error or has a different code.
assert_error_contains!(value, substring).

Tests

Each macro has at least one passing and one failing unit test in tests/assert.rs.
Macro hygiene: invoking from a different crate works.

References

Spec §3, §8 (macro implementation example); spec review §3

## User story As a **test author**, I want assertion macros that produce structured failure messages with file/line context, so that test failures are immediately actionable without printf-debugging. ## Acceptance criteria ### Mechanics - [ ] All assertions are `#[macro_export]` macros invoked from functions that return `TestResult`. On failure they return `Err(TestError::Assertion { expected, got, context, location })`. - [ ] Each macro captures `concat!(file!(), ":", line!())` into `location`. - [ ] Failure messages render `expected` and `got` as **pretty JSON** for readable diffs. - [ ] Macros support an optional trailing `, "context message"` argument that populates `context`. ### Value & field assertions (spec §3.1) - [ ] `assert_ok!(value)` — fails if value is a JSON-RPC error envelope (`{"error": {...}}`). - [ ] `assert_field!(value, field, expected)` — single-key equality. - [ ] `assert_field!(value, path1, path2, ..., expected)` — **variadic for nested path traversal**, resolving the spec inconsistency between §3.1 (3 args) and §9 (4 args). *(Resolves spec review §3.)* - [ ] `assert_field_exists!(value, field)` / `assert_field_absent!(value, field)`. - [ ] `assert_field_type!(value, field, "string"|"number"|"bool"|"array"|"object"|"null")`. ### Array assertions (spec §3.2) - [ ] `assert_array!(value, range)` — accepts any `RangeBounds<usize>`: `1..`, `..=5`, `3..=3`, etc. Fails with a clear "expected length in {range}, got {n}" message. - [ ] `assert_array_contains!(value, |item| ...)` — at least one item matches the closure. - [ ] `assert_array_all!(value, |item| ...)` — all items match. ### Numeric assertions (spec §3.3) - [ ] `assert_in_range!(value, range)` — works for both integers and floats via `RangeBounds<f64>`. - [ ] `assert_greater_than!(value, n)`, `assert_less_than!(value, n)`. ### Error assertions (spec §3.4) - [ ] `assert_error!(value, code)` — fails if value is not an error or has a different code. - [ ] `assert_error_contains!(value, substring)`. ### Tests - [ ] Each macro has at least one passing and one failing unit test in `tests/assert.rs`. - [ ] Macro hygiene: invoking from a different crate works. ## References - Spec §3, §8 (macro implementation example); spec review §3

charles added this to the v0.1.0 milestone

2026-04-11 10:55:38 +00:00

charles added the

area:assertions

type:user-story

labels

2026-04-11 10:55:38 +00:00

charles referenced this issue from a commit

2026-04-11 12:37:50 +00:00

feat(assert): add assertion macros for JSON-RPC test bodies (closes #8)

charles referenced this issue from a pull request that will close it,

2026-04-11 12:38:18 +00:00