Lift the ProjectionScenario test harness into JasperFx.Events

[jeremydmiller]

Cross-store lift of Marten's EventProjectionScenario test support, following the ergonomics/quality pass in JasperFx/marten#5127 (merged as marten#5132). Fixing the shape first was deliberate — the shared surface starts from the corrected API rather than inheriting the throwaway StreamAction returns and the copy-pasted assertion overloads.

This also closes the intent of JasperFx/polecat#404 without anyone hand-porting 15 overloads: Polecat subclasses the shared type instead of maintaining a parallel implementation.

What's here

New JasperFx.Events.TestSupport namespace in the main library (it ships in the product assembly because users reach it through their store's Advanced surface):

• ProjectionScenario<TOperations, TQuerySession> — scripts a sequence of event appends (through the shared IEventOperations surface) and document assertions, then executes them in order. Consecutive appends batch into one commit; pending work is saved before each assertion and once more at the end, which is the marten#5126 trailing-append rule. A failed action stops the scenario and reports how many steps were skipped; failed assertions accumulate and report together. Scenarios are single-use — re-execution throws rather than silently doing nothing. When the store has any async projections the scenario stands up an IProjectionDaemon for the duration and waits for non-stale data after each batch, with a configurable Timeout (default 30s) that honors the caller's CancellationToken.
• Seven abstract seam members — DeleteExistingDataAsync, HasAnyAsyncProjections, BuildDaemonAsync, OpenSession, SaveChangesAsync, EventsFor, LoadDocumentAsync<T>(session, object id, ct). Deliberately the same shape EventStoreComplianceFixture<TOperations, TQuerySession> already asks of each store, including the object id load dispatch — so a store that already has a compliance fixture has already written every one of these.
• DocumentShouldExist / DocumentShouldNotExist take object ids and dispatch through LoadDocumentAsync. That collapses what were four typed overloads per assertion into one, and typed call sites keep compiling since everything converts to object.
• StartStream overloads that generate their own stream id return that Guid; the rest of the append surface returns void, since these operations only queue closures and there is no meaningful result until execution.
• ProjectionScenarioException (aggregate, carries the step-by-step report) and ProjectionScenarioAssertionException (typed assertion failures, distinguishable from infrastructure errors inside the aggregate).

The generic closure mirrors IEventStore<TOperations, TQuerySession> and the compliance fixture — the products close the pair differently and convergence stays a non-goal.

Tests

15 new unit tests in EventTests/TestSupport drive the harness against a fake store closure via NSubstitute, so the sequencing logic is covered with no database: deferred execution and step ordering, flush points (before each assertion, once at the end, including the arrange-only case), typed assertion failures and accumulation, action fail-fast with skip reporting and no final flush, the re-execution guard, daemon start/wait/stop plus the timeout value, tenant id flowing to both session and daemon, and session disposal. EventTests is 672/672 on net9.0.

Consumer status

Marten's adoption branch (feat/5127-scenario-lift) is built and green against a local pack of this branch — Marten.slnx compiles clean and the full scenario suite is 15/15 on net9.0. Marten's ProjectionScenario becomes a ~70-line subclass; seven files and roughly 400 lines of duplicated harness delete. That PR opens once this is merged and published.

🤖 Generated with Claude Code