test: migrate hand-rolled decide/react tests onto AggregateFixture/SagaFixture

[joeldsouzax]

Problem

nexus::testing::AggregateFixture and SagaFixture (added in #126) are the intended way to unit-test aggregate decide-logic and saga react-logic. But because most tests were written before the fixtures existed (fixtures landed 2026-06-17), adoption is low and the same given/when/then logic is hand-rolled several ways.

An API-tightness audit (2026-06-28) found:

• AggregateFixture used in only 2 files; SagaFixture in only 1.
• Pure decide-logic tests elsewhere manually reconstruct AggregateRoot::new → handle → assert (and a manual replay loop for given-state) instead of using the fixture.

Evidence

Fixture-driven (correct):

• crates/nexus/tests/aggregate_fixture_tests.rs
• crates/nexus/tests/saga_fixture_tests.rs

Hand-rolled decide/react tests that the fixture was built to replace:

• crates/nexus/tests/kernel_tests/aggregate_root_tests.rs (~lines 276–309) — new() → handle() + manual asserts
• crates/nexus/tests/kernel_tests/integration_test.rs (~lines 111–192) — new() → handle() → commit_persisted() → assert
• crates/nexus/tests/kernel_tests/newtype_aggregate_tests.rs — same shape
• crates/nexus/tests/kernel_tests/saga_tests.rs (~lines 40–150) — manual AggregateRoot::<OrderSaga>::new() + root.react() instead of SagaFixture

Custom assertion/replay helpers that replicate fixture internals:

• crates/nexus-store/tests/repository_qa_tests.rs replay_events() / apply_events_to() (~lines 106–120)
• crates/nexus/tests/kernel_tests/property_tests.rs replay_events() (~lines 106–113)

Out of scope (do NOT migrate)

These correctly bypass the fixture and must stay manual:

• kernel_tests/replay_tests.rs, aggregate_root_tests.rs version-rejection tests, security_tests.rs — they test the replay() contract itself.
• Repository/store tests that own the load/replay lifecycle.

Add a short comment in crates/nexus/src/testing.rs documenting this boundary (when NOT to use the fixture).

Proposal

Migrate the decide-only and react-only tests above onto AggregateFixture/SagaFixture, consuming the shared test domain (paired card). Target: raise fixture adoption from 3 files to ~8 and collapse the duplicated replay/assert helpers.

Scope

Test-only. No production src/ changes beyond the one doc comment in testing.rs.

Related

• Depends on / pairs with the shared-test-domain card.
• Origin: Add aggregate test fixtures (given/when/then) #126 (closed) created the fixtures; their adoption across existing tests was never tracked.

[joeldsouzax]

Paired with #239 (shared test-domain). Migrated tests should consume that shared domain via the fixtures.

[joeldsouzax]

Consideration: pair the migration with rstest for case tables

rstest (parameterized-test crate, stable Rust, integrates with #[tokio::test]) is a complement to AggregateFixture/SagaFixture, not a replacement — different layers that compose:

• The fixture stays the semantic DSL: given(history) → when(command) → then_expect_events/state/error.
• rstest's #[case(...)] collapses the many near-identical #[test] fns into one parameterized function, each case still failing/reporting independently.

Worth it because the target tests are exactly case tables. E.g. in aggregate_fixture_tests.rs, when_decides_then_expect_events, when_on_empty_history_decides_from_initial, and rejected_command_then_expect_error_exact are the same three fixture lines with different (given, command, expected) tuples → one #[rstest] + #[case] table.

Caveats (decide during implementation, not assumed):

• Coexists with proptest, does not replace it. #[case] is enumerated examples; Rule 8's boundary/range coverage (0 / 1 / MAX-1 / MAX) stays on proptest. rstest only helps the explicit-example tables.
• Verify MSRV against the pinned rust-toolchain.toml / rust-version before adding — docs.rs does not state rstest's minimum Rust version.
• Clippy: test-target lints run by hand via cargo clippy --all-targets (the flake gate is lib-only); confirm rstest's generated code is clean under the god-mode config.
• Add via cargo add --dev per the workspace-deps convention; it's a third test crate (alongside proptest + insta), so justify the surface.

Scope unchanged: this is a refinement of the migration, not a separate task. Relevant to #238 only (irrelevant to #239's type-definition consolidation and to #220).