CoreEx: Subscribe Host Integration Test

Guides you through writing or extending *.Test.Subscribe integration tests — simulating broker
message receipt against the real Subscribe host, real DB, real cache, real outbox, over
WithApiTester<{Domain}.Subscribe.Program>. Subscribe hosts share the same DB/cache/outbox
OneTimeSetUp foundation as API hosts (see coreex-test-api) — the only real difference is how the
test triggers behavior: a simulated message receipt instead of an HTTP call.

When to Use

• Adding a test for a new command subscriber, event-data-sync subscriber, or event-business-process subscriber
• Asserting an ErrorHandler outcome (e.g. CompleteAsInformation on a semantically-expected not-found)
• Asserting state/adapter changes after an event-sync subscriber processes a payload
• Asserting outbox events published as a result of processing a command/business-process message
• Called standalone or as the hand-off step from coreex-subscriber once a subscriber is implemented

When Not to Use

• API host integration tests — use coreex-test-api (owns the shared DB/cache/outbox setup this skill builds on)
• Outbox Relay host tests — use coreex-test-relay
• Implementing the subscriber class itself — use coreex-subscriber

Resolve project-wide choices from state before asking. Read the solution-root AGENTS.md
Feature Configuration: messaging-provider gates this skill (Subscribe host tests exist only when
a messaging provider is configured); data-provider (PostgreSQL vs SQL Server vs Cosmos) selects the
migrate/seed and outbox helper family used throughout — never mix them; outbox-enabled determines
whether outbox-event assertions apply. Only prompt for what is unrecorded; re-state resolved values.

Quick Reference

• Base class: WithApiTester<{Domain}.Subscribe.Program> — same DB/cache/outbox [OneTimeSetUp] shape as API tests (migrate + seed via named-file overload → ClearFusionCacheAsync() → provider-specific UseExpected{Postgres|SqlServer|CosmosDb}OutboxPublisher()); Subscribe hosts do have FusionCache (reference data, idempotency)
• Simulate receipt: build an EventData → Test.CreateCloudEventFrom(ed) → .ToServiceBusReceivedMessage() → resolve ServiceBusSubscribedSubscriber from DI → .ReceiveAsync(sbm)
• Key matters: event subscribers resolve the key "subscriber-events"; command subscribers (dedicated queue receiver) resolve "subscriber-commands" — see coreex-command-subscribe-e2e. Resolving the wrong key throws or hits the wrong receiver
• One partial file per subscriber scenario — SubscriberTests.{Scenario}.cs
• Match the test shape to the subscriber scenario: command → assert outcome + outbox events published as a result; event-data-sync → assert local state/adapter reflects the payload; event-business-process → assert the downstream service ran and published its own events
• ErrorHandler outcomes are assertable — a handled exception surfaces as EventSubscriberHandledException with .ErrorHandling and .InnerException to check
• Always include an "unsubscribed subject" test — confirms unknown subjects are consumed silently (ErrorHandling.CompleteAsSilent), not dead-lettered
• Seed file naming carries over unchanged — read-data.seed.yaml / mutate-data.seed.yaml / a schema-only no-data.seed.yaml for health/plumbing-only tests

For full workflow and code patterns see `references/workflow.md`. For the
shared DB/cache/outbox setup mechanics (seed data authoring, provider-specific outbox helpers), see
`../coreex-test-api/references/workflow.md`.

Key References

• `/.github/instructions/coreex-tests.instructions.md` — full, authoritative test conventions, "Subscribe Host Tests" section
• Related skills: `coreex-subscriber` (the subscriber implementation under test — its command / event-data-sync / event-business-process scenarios map directly to this skill's test shapes), `coreex-test-api` (shared integration-test setup foundations — DB migrate/seed, cache, outbox), `coreex-test-relay` (Outbox Relay host tests)
• Illustrative examples (CoreEx sample — not present in your project):
  • SubscriberTests.ReservationConfirm.cs — command subscriber test (outbox assertion + ErrorHandler)
  • SubscriberTests.ProductModify.cs — event-sync subscriber test (state assertion)