Coreex Test Relay

---
name: coreex-test-relay
description: "Understand, verify, or (rarely) extend an Outbox Relay host integration test in a CoreEx *.Test.Relay project. USE FOR: understanding the templated RelayTests.cs shape, verifying the relay forwards outbox events to the broker, hosted-service pause/resume endpoint checks, diagnosing Service Bus emulator entity-not-found failures. DO NOT USE FOR: API host tests (use coreex-test-api), Subscribe host tests (use coreex-test-subscribe), the relay host's Program.cs/hosted-service setup (see coreex-host-setup.instructions.md)."
argument-hint: "Optional: what you're trying to verify (relay forwarding, hosted-service pause/resume) or a specific failure to diagnose"
tags: ["testing", "integration-tests", "relay", "outbox", "service-bus", "unittestex", "coreex"]
---

<!--
  AI workflow asset — dual-audience notice:
  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
-->

# CoreEx: Outbox Relay Host Integration Test

Guides you through the `*.Test.Relay` project — the most templated and least-extended of the three
integration test projects. Unlike API/Subscribe tests, which grow one file per entity/subscriber as a
domain evolves, relay tests are largely **generic plumbing checks** generated by `CoreEx.Template` and
rarely need new scenarios per domain.

## When to Use

- Understanding what `RelayTests.cs` already verifies before assuming it needs extending
- Verifying the relay forwards outbox-written events to the broker end-to-end
- Adding a hosted-service pause/resume/status check
- Diagnosing a Service Bus emulator "entity not found" test failure
- The rare case where a domain has relay behavior beyond the generic forward-and-verify flow (e.g. a
  custom hosted-service management endpoint)

## When Not to Use

- API host integration tests — use `coreex-test-api`
- Subscribe host integration tests — use `coreex-test-subscribe`
- Relay host `Program.cs` / hosted-service registration — see [`/.github/instructions/coreex-host-setup.instructions.md`](/.github/instructions/coreex-host-setup.instructions.md)

> **Resolve project-wide choices from state before asking.** Read the solution-root `AGENTS.md`
> **Feature Configuration**: `messaging-provider` gates this skill (a Relay host exists only when a
> messaging provider is configured) and `data-provider` (PostgreSQL vs SQL Server) selects the outbox
> publisher family (`PostgresOutboxPublisher`/`SqlServerOutboxPublisher`) — never mix them. Only prompt
> for what is unrecorded; re-state resolved values for confirmation.

## Quick Reference

- **Base class**: `WithApiTester<{Domain}.Relay.Program>` — relay hosts have **no** FusionCache; do not call `ClearFusionCacheAsync()` here
- **No DB/cache seeding needed for the core forwarding test** — it writes directly to the outbox via `Test.ScopedType<ExecutionContext>` and a provider-specific outbox publisher (`PostgresOutboxPublisher`/`SqlServerOutboxPublisher`), then waits for the background relay service to forward it
- **Assert delivery** via `Test.GetAndClearAzureServiceBusAsync(...)` against the expected topic/subscription
- **Hosted-service management endpoints** are also testable over plain HTTP — `/hosted-services/{name}/pause`, `/resume`, etc.
- **A domain rarely needs more than the templated `RelayTests.cs` + `OtherTests.Health.cs` + `OtherTests.HostedServices.cs`** — check what already exists before writing something new

```csharp
public class RelayTests : WithApiTester<YourDomain.Relay.Program>
{
    [Test]
    public async Task Outbox_Relay()
    {
        Test.ScopedType<ExecutionContext>(test =>
        {
            test.Run(async _ =>
            {
                var pub = ActivatorUtilities.GetServiceOrCreateInstance<PostgresOutboxPublisher>(test.Services);   // or SqlServerOutboxPublisher — provider-specific
                pub.Add("{solution}", [ce1, ce2]);
                await pub.PublishAsync();

                for (int i = 0; i < 5; i++)
                    await Task.Delay(TimeSpan.FromSeconds(1));

                var list = await Test.GetAndClearAzureServiceBusAsync(
                    ServiceBusSessionReceiverOptions.CreateForTopicSubscription("{solution}", "{domain}"));

                list.Should().HaveCount(2);
            }).AssertSuccess();
        });
    }
}
```

```csharp
Test.Http()
    .Run(HttpMethod.Post, "/hosted-services/postgres-outbox-relay-03/pause")
    .Response.StatusCode.Should().Be(HttpStatusCode.Accepted);
```

## Troubleshooting — Service Bus Emulator "Entity Not Found"

If a Relay (or any Service Bus) test fails with:

```
The messaging entity 'sb://sbemulatorns.servicebus.onebox.windows-int.net/<topic>/subscriptions/<subscription>' could not be found.
```

the test host reached the emulator but the topic/subscription doesn't exist in it. **This is an
environment problem, not a test-code defect** — check that the Service Bus emulator container is
running with the correct `/servicebus/Config.json` (the emulator provisions topics/subscriptions from
that config at startup). Do not "fix" it by editing the test, subject names, or emulator entity names.

## Key References

- [`/.github/instructions/coreex-tests.instructions.md`](/.github/instructions/coreex-tests.instructions.md) — full, authoritative test conventions, "Outbox Relay Host Tests" section
- `coreex-test-api` / `coreex-test-subscribe` — the other two integration test skills, both more likely to need per-domain extension than this one
- Illustrative examples (CoreEx sample — not present in your project):
  - [RelayTests.cs](https://github.com/Avanade/CoreEx/blob/main/samples/tests/Contoso.Products.Test.Relay/RelayTests.cs) — canonical outbox-forwarding test
  - [OtherTests.Health.cs](https://github.com/Avanade/CoreEx/blob/main/samples/tests/Contoso.Products.Test.Relay/OtherTests.Health.cs), [OtherTests.HostedServices.cs](https://github.com/Avanade/CoreEx/blob/main/samples/tests/Contoso.Products.Test.Relay/OtherTests.HostedServices.cs) — health and hosted-service management checks