Add testing overview doc

docs/testing/manage-app-host.md

@@ -1,7 +1,7 @@
 ---
 title: Manage the app host in .NET Aspire tests
 description: Learn how to manage the app host in .NET Aspire tests.
-ms.date: 10/21/2024
+ms.date: 2/24/2025
 zone_pivot_groups: unit-testing-framework
 ---
 
@@ -114,6 +114,46 @@ public class WebTests
 
 By capturing the app host in a field when the test run is started, you can access it in each test without the need to recreate it, decreasing the time it takes to run the tests. Then, when the test run has completed, the app host is disposed, which will clean up any resources that were created during the test run, such as containers.
 
+## Pass arguments to your app host
+
+You can access the arguments from your app host with the `args` parameter. Arguments are also passed to [.NET's configuration system](/dotnet/core/extensions/configuration), so you can override many configuration settings this way. In the following example, you override the [environment](/aspnet/core/fundamentals/environments) by specifying it as a command line option:
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.MyAppHost>(
+    [
+        "--environment=Testing"
+    ]);
+```
+
+Other arguments can be passed to your app host `Program` and made available in your app host. In the next example, you pass an argument to the app host and use it to control whether you add data volumes to a Postgres instance.
+
+In the app host `Program`, you use configuration to support enabling or disabling volumes:
+
+```csharp
+var postgres = builder.AddPostgres("postgres1");
+if (builder.Configuration.GetValue("UseVolumes", true))
+{
+    postgres.WithDataVolume();
+}
+```
+
+In test code, you pass `"UseVolumes=false"` in the `args` to the app host:
+
+```csharp
+public async Task DisableVolumesFromTest()
+{
+    // Disable volumes in the test builder via arguments:
+    using var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.TestingAppHost1_AppHost>(
+        [
+            "UseVolumes=false"
+        ]);
+
+    // The container will have no volume annotation since we disabled volumes by passing UseVolumes=false
+    var postgres = builder.Resources.Single(r => r.Name == "postgres1");
+    Assert.Empty(postgres.Annotations.OfType<ContainerMountAnnotation>());
+}
+```
+
 ## Use the `DistributedApplicationFactory` class
 
 While the `DistributedApplicationTestingBuilder` class is useful for many scenarios, there might be situations where you want more control over starting the app host, such as executing code before the builder is created or after the app host is built. In these cases, you implement your own version of the <xref:Aspire.Hosting.Testing.DistributedApplicationFactory> class. This is what the `DistributedApplicationTestingBuilder` uses internally.

docs/testing/overview.md

@@ -0,0 +1,42 @@
+---
+title: .NET Aspire testing overview
+description: Learn how .NET Aspire helps you to test your applications.
+ms.date: 2/24/2025
+zone_pivot_groups: unit-testing-framework
+---
+
+# .NET Aspire testing overview
+
+.NET Aspire includes support for automated testing of your application through the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package exposes the <xref:Aspire.Hosting.Testing.DistributedApplicationTestingBuilder> class, which is used to create a test host for your application. The testing builder launches your app host project in a background thread and instruments its lifecycle to pass control back to your <xref:Aspire.Hosting.Testing.DistributedApplicationTestingBuilder> or <xref:Aspire.Hosting.DistributedApplication> instances, allowing you to access and manipulate the application and its resources. Aside from instrumentation, the testing builder disables the dashboard by default and randomizes the ports of proxied resources so that multiple instances of your application can run concurrently. Once your test has completed, disposing the application or testing builder will clean up your app resources.
+
+To get started writing your first integration test with .NET Aspire, see the [Write your first .NET Aspire test](./write-your-first-test.md) article.
+
+## Disable port randomization
+
+By default, during testing, the builder randomizes port assignments for proxied endpoints. This allows multiple instances of your application to run concurrently without interference. It leverages [.NET Aspire's service discovery](../service-discovery/overview.md) mechanism to ensure that applications can locate each other's endpoints. To disable port randomization, pass `"DcpPublisher:RandomizePorts=false"` as an argument when constructing your testing builder, as shown in the following snippet:
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.MyAppHost>(
+    [
+        "DcpPublisher:RandomizePorts=false"
+    ]);
+```
+
+## Enable the dashboard
+
+The testing builder disables the [.NET Aspire dashboard](../fundamentals/dashboard) by default. To enable it, you can set the `DisableDashboard` property to `false`, when creating your testing builder as shown in the following snippet:
+
+```csharp
+var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.MyAppHost>(
+    args: [],
+    configureBuilder: (appOptions, hostSettings) =>
+    {
+        appOptions.DisableDashboard = false;
+    });
+```
+
+## See also
+
+- [Write your first .NET Aspire test](./write-your-first-test.md)
+- [Managing the app host in .NET Aspire tests](./manage-app-host.md)
+- [Access resources in .NET Aspire tests](./accessing-resources.md)

docs/testing/write-your-first-test.md

@@ -1,15 +1,15 @@
 ---
 title: Write your first .NET Aspire test
 description: Learn how to test your .NET Aspire solutions using the xUnit, NUnit, and MSTest testing frameworks.
-ms.date: 11/11/2024
+ms.date: 2/24/2025
 zone_pivot_groups: unit-testing-framework
 ---
 
 # Write your first .NET Aspire test
 
 In this article, you learn how to create a test project, write tests, and run them for your .NET Aspire solutions. The tests in this article aren't unit tests, but rather functional or integration tests. .NET Aspire includes several variations of [testing project templates](../fundamentals/setup-tooling.md#net-aspire-templates) that you can use to test your .NET Aspire resource dependencies—and their communications. The testing project templates are available for MSTest, NUnit, and xUnit testing frameworks and include a sample test that you can use as a starting point for your tests.
 
-The .NET Aspire test project templates rely on the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package exposes the <xref:Aspire.Hosting.Testing.DistributedApplicationTestingBuilder> class, which is used to create a test host for your distributed application. The distributed application testing builder relies on the <xref:Aspire.Hosting.DistributedApplication> class to create and start the [app host](../fundamentals/app-host-overview.md).
+The .NET Aspire test project templates rely on the [📦 Aspire.Hosting.Testing](https://www.nuget.org/packages/Aspire.Hosting.Testing) NuGet package. This package exposes the <xref:Aspire.Hosting.Testing.DistributedApplicationTestingBuilder> class, which is used to create a test host for your distributed application. The distributed application testing builder launches your app host project with instrumentation hooks so that you can access and manipulate the host at various stages of its lifecyle. In particular, <xref:Aspire.Hosting.Testing.DistributedApplicationTestingBuilder> provides you access to <xref:Aspire.Hosting.IDistributedApplicationBuilder> and <xref:Aspire.Hosting.DistributedApplication> class to create and start the [app host](../fundamentals/app-host-overview.md).
 
 ## Create a test project
 

docs/toc.yml

@@ -84,6 +84,9 @@ items:
 
 - name: Testing
   items:
+  - name: Overview
+    displayName: aspire testing,testing
+    href: testing/overview.md
   - name: Write your first .NET Aspire test
     href: testing/write-your-first-test.md
   - name: Managing the app host