feat: add Args property to AspireFixture for AppHost arguments

TUnit.Aspire/AspireFixture.cs

@@ -106,6 +106,23 @@ protected virtual void LogProgress(string message)
         StdErr.Flush();
     }
 
+    /// <summary>
+    /// Command-line arguments to pass to the AppHost entry point.
+    /// These are forwarded to <see cref="DistributedApplicationTestingBuilder.CreateAsync{TEntryPoint}(string[], CancellationToken)"/>
+    /// and are available in the AppHost's <c>builder.Configuration</c> before the builder is created.
+    /// </summary>
+    /// <remarks>
+    /// Use this to pass configuration values that are consumed during AppHost builder creation:
+    /// <code>
+    /// protected override string[] Args => [
+    ///     "--UseVolumes=false",
+    ///     "--UsePostgresWithSessionLifetime=true"
+    /// ];
+    /// </code>
+    /// For configuration that can be set after builder creation, use <see cref="ConfigureBuilder"/> instead.
+    /// </remarks>
+    protected virtual string[] Args => [];
+
     /// <summary>
     /// Override to customize the builder before building the application.
     /// </summary>
@@ -184,7 +201,7 @@ public virtual async Task InitializeAsync()
         var sw = Stopwatch.StartNew();
 
         LogProgress($"Creating distributed application builder for {typeof(TAppHost).Name}...");
-        var builder = await DistributedApplicationTestingBuilder.CreateAsync<TAppHost>();
+        var builder = await DistributedApplicationTestingBuilder.CreateAsync<TAppHost>(Args);
         ConfigureBuilder(builder);
         LogProgress($"Builder created in {sw.Elapsed.TotalSeconds:0.0}s");
 

docs/docs/examples/aspire.md

@@ -196,6 +196,7 @@ When a timeout occurs, the error includes:
 |--------|---------|-------------|
 | `InitializeAsync()` | Full lifecycle | Override to add post-start logic (migrations, seeding) |
 | `DisposeAsync()` | Stop and dispose app | Override to add custom cleanup |
+| `Args` | Empty | Command-line arguments passed to the AppHost entry point |
 | `ConfigureBuilder(builder)` | No-op | Customize the builder before building |
 | `ResourceTimeout` | 60 seconds | How long to wait for startup and resources |
 | `WaitBehavior` | `AllHealthy` | Which resources to wait for |
@@ -229,6 +230,27 @@ public class AppFixture : AspireFixture<Projects.MyAppHost>
 }
 ```
 
+### Passing Arguments to the AppHost
+
+Use the `Args` property to pass command-line arguments to the AppHost entry point. These are forwarded to `DistributedApplicationTestingBuilder.CreateAsync` and are available in the AppHost's `builder.Configuration` during builder creation — before `ConfigureBuilder` is called:
+
+```csharp
+public class AppFixture : AspireFixture<Projects.MyAppHost>
+{
+    protected override string[] Args =>
+    [
+        "--UseVolumes=false",
+        "--UsePostgresWithPersistentLifetime=false",
+        "--UsePostgresWithSessionLifetime=true"
+    ];
+}
+```
+
+:::tip When to use `Args` vs `ConfigureBuilder`
+- Use **`Args`** for configuration values that the AppHost reads during `CreateBuilder(args)` — these must be set *before* the builder is created.
+- Use **`ConfigureBuilder`** for service registrations, HTTP client defaults, and other configuration that can be applied *after* the builder is created.
+:::
+
 ## Watching Resource Logs
 
 Use `WatchResourceLogs()` inside a test to stream a resource's container logs to the test output. This is invaluable for debugging failures: