From 8a0ff21f726c902015ea43c4b5fba44e29ed670d Mon Sep 17 00:00:00 2001
From: "aspire-repo-bot[bot]"
 <268009190+aspire-repo-bot[bot]@users.noreply.github.com>
Date: Thu, 1 Oct 2026 15:33:43 +0000
Subject: [PATCH] docs: document recursive MTP test runner invocation guard

Adds a troubleshooting section to the advanced testing scenarios page
explaining why Aspire.AppHost.Sdk test projects can recursively invoke
the test runner via DistributedApplicationTestingBuilder.CreateAsync,
and how to fix it (Microsoft.NET.Sdk + ProjectReference, dynamic
assembly loading, or DistributedApplicationTestingBuilder.Create()).

Documents microsoft/aspire#20573

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../docs/testing/advanced-scenarios.mdx       | 20 +++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/src/frontend/src/content/docs/testing/advanced-scenarios.mdx b/src/frontend/src/content/docs/testing/advanced-scenarios.mdx
index d3d8f3374..a419039c5 100644
--- a/src/frontend/src/content/docs/testing/advanced-scenarios.mdx
+++ b/src/frontend/src/content/docs/testing/advanced-scenarios.mdx
@@ -185,6 +185,26 @@ var appHost = await DistributedApplicationTestingBuilder
 
 The `Projects` namespace entries are only generated for `<ProjectReference>` entries in your test project. A file-based `apphost.cs` produces no such entry.
 
+## Avoid building test projects with `Aspire.AppHost.Sdk`
+
+Test projects should use `Microsoft.NET.Sdk` and reference the AppHost project with a `<ProjectReference>`. Don't build the test project itself with `Aspire.AppHost.Sdk`.
+
+<Aside type="caution">
+If a Microsoft.Testing.Platform test project (such as an `aspire-xunit` project) is built with `Aspire.AppHost.Sdk`, the generated `Projects.*` type can belong to the test application instead of the AppHost. Passing that type to `CreateAsync<T>()` invokes the test application's own entry point, which recursively starts the test runner, reruns the entire test suite without the original filter, and can leave many AppHost and DCP processes running.
+</Aside>
+
+`DistributedApplicationTestingBuilder.CreateAsync` detects this condition before invoking the entry point and throws `InvalidOperationException` with a message that explains the problem and the fix:
+
+```text
+The assembly 'MyTests' is a Microsoft.Testing.Platform test application. Invoking its entry point from DistributedApplicationFactory would recursively run the test application. Test projects should use Microsoft.NET.Sdk instead of Aspire.AppHost.Sdk and reference the AppHost project so the entry point type belongs to the AppHost executable assembly. Alternatively, use DistributedApplicationTestingBuilder.Create to construct the application without invoking an entry point.
+```
+
+To resolve this:
+
+- Make sure the test project's SDK is `Microsoft.NET.Sdk`, and that it has a `<ProjectReference>` to the AppHost project so `Projects.MyAppHost` resolves to the AppHost's assembly, not the test assembly.
+- If the AppHost is discovered dynamically at runtime, load its assembly directly and pass a type from that assembly to `CreateAsync(Type)` instead of relying on the generated `Projects` type.
+- If you don't need the entry point invoked at all, use [`DistributedApplicationTestingBuilder.Create()`](/testing/manage-app-host/#use-the-distributedapplicationfactory-class) to construct the application without invoking an entry point.
+
 ## See also
 
 - [Manage the AppHost in tests](/testing/manage-app-host/)