Stratara.Testing.Orleans
4.3.0
Prefix Reserved
dotnet add package Stratara.Testing.Orleans --version 4.3.0
NuGet\Install-Package Stratara.Testing.Orleans -Version 4.3.0
<PackageReference Include="Stratara.Testing.Orleans" Version="4.3.0" />
<PackageVersion Include="Stratara.Testing.Orleans" Version="4.3.0" />
<PackageReference Include="Stratara.Testing.Orleans" />
paket add Stratara.Testing.Orleans --version 4.3.0
#r "nuget: Stratara.Testing.Orleans, 4.3.0"
#:package Stratara.Testing.Orleans@4.3.0
#addin nuget:?package=Stratara.Testing.Orleans&version=4.3.0
#tool nuget:?package=Stratara.Testing.Orleans&version=4.3.0
Stratara.Testing.Orleans
Derived. The behaviour described here is specified under
openspec/specs/. Those specifications are the source; this page explains and illustrates them.
Run the Orleans execution model in a test's own process. ExecutionModelTestHost starts one
silo clustered with itself, with reminders and the grain directory in memory, and the framework's
real write stack, portable commit-order reader, checkpoint store and intent store on an in-memory
SQLite database. Every period the model keeps as a reminder or a poll is shortened to seconds, so a
projection applies and a timer fires within a test. No cluster, no broker, no database server, no
Docker.
Builds on Stratara.Testing.EntityFrameworkCore.
Why run the real grains?
Because the registration is what a test should prove. Your handlers, projections, sagas, processes
and timer ports are registered with the calls production uses — AddStrataraAggregateGrains,
AddStrataraProjectionGrains, AddStrataraSagaGrains, AddStrataraDurableTimers,
AddStrataraOrleansCommandDispatcher — and run in the same grains, through the same mediator
pipeline, reading the store in commit order from a checkpoint.
Example
await using var host = await ExecutionModelTestHost.CreateAsync(services => services
.AddAggregatesFromAssemblyContaining<Account>()
.AddCommandHandlersFromAssemblyContaining<OpenAccountHandler>()
.AddProjectionsFromAssemblyContaining<BalanceProjection>()
.AddStrataraAggregateGrains()
.AddStrataraProjectionGrains());
await host.DispatchAsync(new OpenAccount(accountId, 100m)); // runs in the account's activation
await host.WaitForReadersAsync(); // every reader is at the store's head
Assert.Equal(100m, balances[accountId]);
Contents
ExecutionModelTestHost—CreateAsync(configure, options),DispatchAsync,WaitForReadersAsync,Timers,SeedAtHeadAsync,ResetAsync, the presetSessionandServices.IAsyncDisposable.ExecutionModelTestHostOptions— the periods (PollInterval250 ms,ReminderPeriod1 s,IntentGrace2 s,DrainPollingInterval1 s), the partition count (4), the start timeout, andBeforeStart, which runs before the silo starts — where a test appends history and seeds the readers at its head, as a deployment does while no silo runs. A value a test sets through a registration's own settings wins over the host's.StrataraTestReadDbContext— the read context that holds the checkpoints.
Share a host across a test class
Creating a host takes a few seconds. Share one through a class fixture and reset it between tests where one must not see another's state:
public sealed class ExecutionModelFixture : IAsyncLifetime
{
public ExecutionModelTestHost Host { get; private set; } = null!;
public async ValueTask InitializeAsync() =>
Host = await ExecutionModelTestHost.CreateAsync(services => services /* the roles */);
public ValueTask DisposeAsync() => Host.DisposeAsync();
}
ResetAsync runs the execution model's reset port on this host, where the silo keeps running: the timers
and the grain directory's entries go, and every registered reader is put at the store's head. The next
test's facts are applied, the last test's are not applied a second time, and WaitForReadersAsync returns
at once. The read models themselves are not emptied — empty or rebuild them in the fixture where a test
needs them clean.
Where the host stops
- One silo. Membership, reminders and the directory are in memory and not shared. What happens across silos — a kill, a role split, a takeover — is an integration test against real infrastructure.
- Test projects only. Referencing the package from a project that is not a test project fails
the build with
STRATARA1001;StrataraAllowTestSupportOutsideTests=trueopts out, as the sample does.CreateAsyncrefuses to run whereDOTNET_ENVIRONMENTorASPNETCORE_ENVIRONMENTstates an environment other thanDevelopment.
Dependencies
Stratara.Orleans,Stratara.Orleans.EntityFrameworkCore,Stratara.Testing.EntityFrameworkCoreMicrosoft.Orleans.Server,Microsoft.Extensions.Hosting
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.Hosting (>= 10.0.11)
- Microsoft.Orleans.Server (>= 10.3.1 && < 11.0.0)
- Stratara.Orleans (>= 4.3.0)
- Stratara.Orleans.EntityFrameworkCore (>= 4.3.0)
- Stratara.Testing.EntityFrameworkCore (>= 4.3.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
A correctness release for the Orleans execution model's store readers, and the release that makes
Stratara say who acted. The native PostgreSQL commit-order reader could be switched off entirely by a
convention this framework's own API reference recommends — silently, in a deployment that reported
healthy. Beyond that, an actor acting on a tenant it holds no membership in can now hold a role the
host names, and work the platform starts for a tenant has a session shape of its own.
**Upgrading:**
- **If you read the store in commit order on PostgreSQL, upgrade.** A write context that applies
`ApplyRowVersionConvention(RowVersionMode.Uint)` made every projection catch-up fail with
`42703: column s.xmin does not exist`, for ever, without the host reporting unhealthy. A consumer
who worked around it by unmapping `EventStreamEntry.RowVersion` can drop the workaround.
- **Check what your `CrossTenantRoles` names mean on both role levels.** The cross-tenant authorizer
now also recognises a configured role held through the actor's own membership, so it permits
operations it refused before.
- **A host whose handlers append events needs `AddCommandAuditing()`.** It always did; now it is
refused before the commit instead of failing in the database.
- No schema change, no migration.
### Added
- **`SessionContext.ForPlatform(tenantId)`**: the session for work the platform starts on a tenant's
behalf — a durable timer, a saga step, a sweep. It carries the reserved system actor identities, a
fresh correlation id and a causation id of its own, so the work can append without a command having
preceded it. Strict tenant isolation recognises the shape and permits it without consulting the
cross-tenant authorizer, recorded under its own log event (`114_104`): the platform acting *for* a
tenant is not one tenant acting *on* another. The data-owner check applies unchanged. A host that
wants to decide for itself sets `TenantIsolationOptions.AuthorizePlatformActor`. Until now the
sentinels existed, the documentation named them, and nothing in the framework acted on them — the
honest session was refused by strict mode, and the session that passed claimed the tenant had acted.
- **`MembershipAuthorizationOptions.HomeTenantRoles`**: roles that resolve in the tenant the actor is a
member of rather than in the tenant the request concerns. For an actor acting on a tenant it holds no
membership in and never can: a machine key, which materialises one membership in the tenant it was
issued for and serves many, or an operator administering a tenant they never joined — both were
refused every role check. Configure it with `AddMembershipAuthorization(o => o.HomeTenantRoles.Add("Service"))`.
Empty by default, consulted only when the actor's tenant differs from the data owner's, and only the
named roles cross.
### Fixed
- **The native PostgreSQL commit-order reader reads a store under any column mapping.** It selected the
event table with a wildcard, which returns no system column. A write context that applies the
framework's own row-version convention maps the entry's row version onto PostgreSQL's `xmin`, so every
catch-up of every projection grain failed with `42703: column s.xmin does not exist` and retried for
ever — no checkpoint written, nothing dead-lettered, the host reporting healthy and every write
succeeding. The reader now names the columns the model maps. A consumer who worked around this by
unmapping `EventStreamEntry.RowVersion` can drop the workaround.
- **Entries committed together reach a store-reading projection in stream order.** The native reader
returned the entries of one commit in the order the database inserted the rows, which is not the order
they were appended in: a stream created and appended to in one save could hand a projection version 2
before version 1, and no retry could help, because the beginning was behind it in the same partition
rather than late. Each stream's entries are now returned in version order, which is what the portable
counter already did. Entries of different streams in one commit may still be interleaved in any order.
### Changed
- **The cross-tenant authorizer now recognises a configured platform role held through the actor's own
membership.** `MembershipCrossTenantAuthorizerOptions.CrossTenantRoles` is documented as the path for
an operator who holds no membership in the tenant they administer, but the role was looked up through
a role check that reads the subject tenant — the very tenant the option says the actor is not a member
of. On the membership level it could therefore never pass, and a machine actor has no global role
level at all, so for a machine actor the option did nothing. The actor's own membership is now
consulted as well.
**This permits cross-tenant operations that were refused before.** Before upgrading, check what the
names in your `CrossTenantRoles` mean on both role levels: a host that configured `"Admin"` intending
the global Identity role now also admits an actor holding a tenant-scoped membership role of the same
name in its own tenant. `"Admin"`, `"Owner"` and `"TenantAdmin"` collide between the two levels
routinely. The widening is in the direction the requirement has always stated, and it reaches only
actors holding a role the host itself named.
- **Appending without a causation identity is refused before the commit.** The session context carries a
nullable causation id, but the store requires one of every entry, and only `AddCommandAuditing()`
supplies it. A host that had not registered it met a `23502` not-null violation from the database that
read like a schema fault. `SaveChangesAsync` now refuses the append before the transaction opens, with a
message naming the registration. `AddCommandServices()` still does not register the auditing behaviours
— where they sit in the pipeline is a consumer's decision.