Intropy.Framework.Testing 2.1.0-beta.5

Intropy.Framework.Testing

Hand-rolled fakes and delivery helpers for component integration tests against the Intropy framework. No mocking-framework dependency, no Dapr sidecar required. It depends on Intropy.Framework.Hosting (for the loader delivery helpers).

The package fakes the four edges every component integration test fakes, plus helpers for delivering CloudEvents to loaders exactly as a Dapr sidecar does:

The canonical pattern

1. Build the component's pipeline/host exactly as production composition does — same steps, same builder calls.
2. Fake the edges:
   • Extractors: ExtractorBuilder<...>.WithSender(fakeTopic) in place of WithDaprTopicPublisher(...).
   • Loaders: override the keyed IFileAdapter registration with an InMemoryFileAdapter, and the two service clients with their fakes (plain DI override — last registration wins). A pipeline without WithIdempotency never resolves IIdempotencyServiceClient, so its fake is only needed when the pipeline configures idempotency.
3. Assert on fake state: topic count/events, adapter files, recorded incidents/resolutions and commits, delivery acks.

// Extractor test shape
var topic = new FakeTopic<MyContext>();
var pipeline = MyExtractorComposition.BuildPipeline(
    extractorBuilder => extractorBuilder.WithSender(topic));

await RunSweep(pipeline, fileAdapter); // component's own orchestration

Assert.Equal(2, topic.Count);
Assert.Equal("order.created", topic.Events[0].Type);

// Loader test shape: the loader serves the Dapr gRPC app callback on a port, and the
// delivery plays the sidecar over it.
var port = AppCallbackDelivery.AvailablePort();
builder.Services.AddLoader(options =>
{
    options.PubSubName = "pubsub";
    options.TopicName = "orders";
    options.CallbackPort = port;
}, routes => /* the component's routes */);                          // plus the edge fakes
using var host = builder.Build();
await host.StartAsync();
using var delivery = new AppCallbackDelivery(port, "pubsub", "orders");

var ack = await delivery.DeliverAsync(cloudEvent);                  // redelivery: true marks a retry

Assert.Equal(DeliveryAck.Success, ack);
Assert.Equal(expectedJson, destinationFiles.GetString("out/order-42.json"));

A transactional integration serves the same callback for the length of a run (TransactionalIntegrationOptions.CallbackPort): deliver to it while the run's sweep is still going, and it consumes until its queue goes idle.

AppCallbackDelivery encodes events the way the sidecar hands them over — the payload as the envelope's data member (an object payload as a camelCase JSON object, as the framework's blocks publish it; a string payload arrives quoted, as it does for real), every other attribute as an extension — and returns the block's ack as a DeliveryAck. A block never answers DROP: what it cannot process it leaves for redelivery (RETRY), so the broker dead-letters it.

A subscribing block announces no subscription (a declarative Dapr Subscription resource owns it), so AppCallbackDelivery is told the pub/sub and topic it delivers on, as the resource tells the sidecar. An overload of DeliverAsync delivers from another pub/sub or topic, to test a resource that disagrees with the block. DaprDelivery is for ASP.NET components that still receive over HTTP delivery.

Fake semantics (fail like production)

• InMemoryFileAdapter — missing reads throw FileNotFoundException (the Dapr binding throws; it never returns null); deletes of missing files no-op (binding delete is idempotent); files are keyed on the effective path (basePath/fileName when a write passes an override). Pass a basePath to the constructor to make ListAsync mirror LocalFileAdapter: only files under that path, listed by file name. ReadException / WriteException / DeleteException simulate a dead source/destination. Per-file faults: AddUnreadableFile(name) seeds a file that is listed but throws on read (corrupt source file), and SetDeleteException(name, ex) makes deletes fail for one file while others succeed — the publish-succeeds-but-delete-fails path, where the file is re-processed next run and idempotency must catch it.

• FakeTopic<TCtx> — captures the exact CloudEvent instances the real publisher would have encoded. SendException surfaces as a technical failure through the framework's normal exception handling, matching a dead broker.

• FakeEnqueueStep<TCtx> — the transactional receive pipeline's enqueue seam, plugged in via ReceivePipelineBuilder<TCtx>.WithEnqueuer(fake). Captures each SourceItem and its already-encoded structured-mode CloudEvents envelope (defensive byte[] copies — the formatter's buffer is recycled); decode via CapturedEnqueue.DecodeCloudEvent(). Register it as the EnqueueStep<TCtx> to replace the built-in DaprTopicEnqueuer: the receive pipeline AddTransactionalIntegration registers publishes through it. SendException is thrown before capture, surfaces as a technical failure, and — because the sweep completes a file only after it is enqueued — leaves the source file undeleted, matching a dead broker in production.

• Service fakes — faults throw the typed IdempotencyServiceException / BusinessIncidentServiceException. Typing matters: the framework's incident router has a dedicated catch for BusinessIncidentServiceException; any other exception type takes a different code path than production.

• DaprDelivery.DeliverAsync — POSTs the structured-mode envelope as application/cloudevents+json and parses the {"status": "..."} ack. Unknown, missing, or malformed statuses map to DeliveryAck.Retry, matching the sidecar's fail-safe redelivery. DeliveryAck members map to wire values as Success ↔ SUCCESS, Retry ↔ RETRY, Drop ↔ DROP.

• PublishedMessageCapture — records publish calls made through a DaprClient substitute configured by your test project (works with any mocking framework; one wiring line per fake). Assert on the captured PublishedMessages and decode envelopes via DecodeCloudEvent():

  var daprClient = Substitute.For<DaprClient>();
  var capture = new PublishedMessageCapture();
  daprClient
      .PublishByteEventAsync(
          Arg.Any<string>(), Arg.Any<string>(), Arg.Any<ReadOnlyMemory<byte>>(),
          Arg.Any<string?>(), Arg.Any<Dictionary<string, string>?>(), Arg.Any<CancellationToken>())
      .Returns(Task.CompletedTask)
      .AndDoes(ci => capture.Capture(
          ci.Arg<string>(), ci.ArgAt<string>(1), ci.ArgAt<ReadOnlyMemory<byte>>(2),
          ci.ArgAt<string?>(3)));
  
  // ... run the pipeline ...
  
  var message = capture.Messages.Single();
  Assert.Equal("orders", message.TopicName);
  Assert.Equal("order-42", message.DecodeCloudEvent().Subject);
  

Loader ack/consumption matrix

This matrix describes the behavior of framework-composed loader and transactional pipelines (which acks their endpoints/handlers produce), not of this package. The delivery helpers only deliver the event and report the ack.

Business failures are consumed. When a business step fails, the framework's incident-router finalizer triggers the incident and returns Success(defaultValueFactory()) — for framework-wired extractors an empty CloudEvent, never null. Do not assert on null result values; assert on Incidents instead.

Extractor sweep matrix

Transactional receive side matrix

Per source file, swept by FileSweep around the receive pipeline:

The last row is the most valuable one: the enqueue is captured, completion fails, and the file is re-processed next run.

Transactional send pipeline matrix

Per delivered message:

² Transactional SendStep is a BusinessStep, so an uncaught exception routes an incident rather than becoming a technical failure — but it is retriable, so the message is left for redelivery rather than acknowledged. A send step that wants the message consumed says so: Failure(incident, Retriable: false).

This package still ships no FakeSendStep for the send pipeline. Assert through the component's real sender + InMemoryFileAdapter instead — it tests more, including the file-naming convention.

Notes

• Thread-safe: all recorded state is lock-guarded and exposed as snapshots, so parallel extractor sweeps cannot corrupt assertions. Fault knobs (ReadException, SendException, ...) are volatile — safe to toggle between runs, not a coordination primitive for mid-run assertions.
• Versioned in lockstep with the framework packages.