update

Author: KSemenenko

.codex/skills/dotnet-xunit/references/anti-patterns.md

@@ -65,9 +65,9 @@ public class UserServiceTests
 }
 ```
 
-## Excessive Mocking
+## Test Doubles Instead of Behavior
 
-Over-mocking creates brittle tests that verify implementation rather than behavior.
+Stub, Fake, and Mock doubles are forbidden by default. They create brittle tests when they replace behavior that should be proven through real implementations, Aspire-managed resources, or observable state.
 
 Bad:
 
@@ -114,9 +114,9 @@ public class OrderServiceTests
     [Fact]
     public void PlaceOrder_ValidOrder_ReturnsOrderId()
     {
-        // Arrange - use real implementations where cheap, mock only external boundaries
+        // Arrange - use real implementations and observable state
         var repository = new InMemoryOrderRepository();
-        var notificationService = Substitute.For<INotificationService>();
+        var notificationService = new RecordingNotificationService();
         var service = new OrderService(repository, notificationService);
         var order = new Order { CustomerId = 1, Items = [new OrderItem { ProductId = 1, Quantity = 1 }] };
 
@@ -128,6 +128,7 @@ public class OrderServiceTests
         var savedOrder = repository.GetById(orderId);
         Assert.NotNull(savedOrder);
         Assert.Equal(OrderStatus.Placed, savedOrder.Status);
+        Assert.Contains(notificationService.SentOrderIds, id => id == orderId);
     }
 }
 ```
@@ -188,7 +189,7 @@ public class CacheTests
         // Arrange
         var store = new InMemoryDataStore();
         store.Set("key", "original");
-        var timeProvider = new FakeTimeProvider();
+        var timeProvider = new ControlledTimeProvider();
         var cache = new Cache(store, timeProvider, ttl: TimeSpan.FromMinutes(5));
 
         // Act
@@ -320,7 +321,7 @@ public class TimestampTests
     {
         // Arrange
         var fixedTime = new DateTimeOffset(2024, 1, 15, 10, 30, 0, TimeSpan.Zero);
-        var timeProvider = new FakeTimeProvider(fixedTime);
+        var timeProvider = new ControlledTimeProvider(fixedTime);
         var service = new RecordService(timeProvider);
 
         // Act
@@ -536,14 +537,14 @@ public class UserRegistrationTests
     public void RegisterUser_ValidData_SendsWelcomeEmail()
     {
         // Arrange
-        var emailService = Substitute.For<IEmailService>();
+        var emailService = new RecordingEmailService();
         var service = new UserService(emailService);
 
         // Act
         service.Register("test@example.com", "password123");
 
         // Assert
-        emailService.Received(1).SendWelcomeEmail("test@example.com");
+        Assert.Contains("test@example.com", emailService.WelcomeRecipients);
     }
 
     [Fact]

.codex/skills/dotnet-xunit/references/patterns.md

@@ -214,75 +214,33 @@ public class StringUtilityTests
 }
 ```
 
-## Mocking with NSubstitute
+## Aspire-First Boundary Tests
 
-Prefer NSubstitute for readable substitute configuration:
+For hosted, integration, browser, or infrastructure-backed behavior, prefer an Aspire-managed AppHost and real resources. Stub, Fake, and Mock doubles are forbidden by default; use them only with a documented exception and removal plan.
 
 ```csharp
-public class OrderServiceTests(ITestOutputHelper output)
+public class CheckoutFlowTests
 {
     [Fact]
-    public async Task PlaceOrder_ValidOrder_SendsNotification()
+    public async Task Checkout_ValidCart_ReturnsReceipt()
     {
-        // Arrange
-        var notificationService = Substitute.For<INotificationService>();
-        var orderRepository = Substitute.For<IOrderRepository>();
-        orderRepository.SaveAsync(Arg.Any<Order>()).Returns(Task.FromResult(true));
+        // Arrange - resolve a client from the Aspire-managed test host
+        await using var app = await DistributedApplicationTestingBuilder
+            .CreateAsync<Projects.MyApp_AppHost>();
+        await using var host = await app.BuildAsync();
+        await host.StartAsync();
 
-        var service = new OrderService(orderRepository, notificationService);
-        var order = new Order { CustomerId = 1, Items = [new OrderItem { ProductId = 1, Quantity = 2 }] };
+        var client = host.CreateHttpClient("api");
+        await host.ResourceNotifications.WaitForResourceHealthyAsync("api");
 
         // Act
-        await service.PlaceOrderAsync(order);
-
-        // Assert
-        await notificationService.Received(1).SendOrderConfirmationAsync(Arg.Is<Order>(o => o.CustomerId == 1));
-        output.WriteLine("Order placed and notification sent");
-    }
-
-    [Fact]
-    public async Task PlaceOrder_RepositoryFails_ThrowsException()
-    {
-        // Arrange
-        var notificationService = Substitute.For<INotificationService>();
-        var orderRepository = Substitute.For<IOrderRepository>();
-        orderRepository.SaveAsync(Arg.Any<Order>()).ThrowsAsync(new DataException("Connection failed"));
-
-        var service = new OrderService(orderRepository, notificationService);
-        var order = new Order { CustomerId = 1 };
-
-        // Act & Assert
-        await Assert.ThrowsAsync<DataException>(() => service.PlaceOrderAsync(order));
-        await notificationService.DidNotReceive().SendOrderConfirmationAsync(Arg.Any<Order>());
-    }
-}
-```
+        using var response = await client.PostAsJsonAsync("/checkout", new { Sku = "starter", Quantity = 1 });
+        var receipt = await response.Content.ReadFromJsonAsync<Receipt>();
 
-## Mocking with Moq
-
-Use Moq when the project already depends on it:
-
-```csharp
-public class PaymentProcessorTests
-{
-    [Fact]
-    public async Task ProcessPayment_ValidCard_ReturnsSuccess()
-    {
-        // Arrange
-        var gatewayMock = new Mock<IPaymentGateway>();
-        gatewayMock
-            .Setup(g => g.ChargeAsync(It.IsAny<string>(), It.Is<decimal>(d => d > 0)))
-            .ReturnsAsync(new PaymentResult { Success = true, TransactionId = "TX123" });
-
-        var processor = new PaymentProcessor(gatewayMock.Object);
-
-        // Act
-        var result = await processor.ProcessPaymentAsync("4111111111111111", 99.99m);
-
-        // Assert
-        Assert.True(result.Success);
-        Assert.Equal("TX123", result.TransactionId);
-        gatewayMock.Verify(g => g.ChargeAsync("4111111111111111", 99.99m), Times.Once);
+        // Assert - verify observable behavior, not implementation calls
+        response.EnsureSuccessStatusCode();
+        Assert.NotNull(receipt);
+        Assert.NotEqual(Guid.Empty, receipt.Id);
     }
 }
 ```
@@ -389,4 +347,3 @@ dotnet test --filter "Category!=Integration"
 
 - [xUnit.net Theory Data](https://xunit.net/docs/getting-started/v3/theory-data)
 - [xUnit.net Shared Context](https://xunit.net/docs/shared-context)
-- [NSubstitute Documentation](https://nsubstitute.github.io/help/getting-started/)

.codex/skills/dotnet-xunit/references/xunit.md

@@ -19,6 +19,15 @@ VSTest compatibility package when the repo intentionally uses that runner:
 dotnet add package xunit.runner.visualstudio
 ```
 
+Aspire CLI is mandatory alongside MCAF/.NET test setup when the repo has integration, browser, hosted, or infrastructure-backed tests:
+
+```bash
+curl -sSL https://aspire.dev/install.sh | bash
+aspire --version
+```
+
+Do not add mocking libraries as part of default xUnit setup. Stub, Fake, and Mock doubles are forbidden by default and require a documented exception with a removal plan.
+
 ## Verify First
 
 Before adding packages, check what the repo already references:

.codex/skills/mcaf-solution-governance/references/dotnet-agents-pattern.md

@@ -3,6 +3,13 @@
 Use this reference when the solution stack is .NET and the root or local `AGENTS.md` needs concrete command and tooling guidance.
 The `.NET` skill bundle itself lives in the [Managed Code Skills catalog](https://skills.managed-code.com/), not in this repository.
 
+When installing or documenting MCAF for a .NET repository, also install Aspire CLI whenever the repo has integration, browser, hosted, or infrastructure-backed tests:
+
+```bash
+curl -sSL https://aspire.dev/install.sh | bash
+aspire --version
+```
+
 ## Root AGENTS.md Expectations
 
 Record the real commands, not placeholders:
@@ -76,6 +83,8 @@ For each .NET project or module, record:
 - the active test framework
 - the active runner model
 - the coverage driver if the module runs coverage in isolation
+- the Aspire command when the module owns integration, browser, hosted, or infrastructure-backed tests
+- the local rule that Stub, Fake, and Mock doubles are forbidden by default and require a documented exception
 
 Good `Applicable Skills` examples:
 

.codex/skills/mcaf-solution-governance/references/project-agents-template.md

@@ -29,6 +29,7 @@ Parent: `../AGENTS.md`
 - `test`: `...`
 - `format`: `...`
 - `analyze`: `...` (delete if not used)
+- `aspire`: `aspire run ...` (required when this project owns integration tests, browser tests, or infrastructure-backed tests)
 
 For .NET projects also document:
 
@@ -42,6 +43,13 @@ For .NET projects also document:
 - `...`
 
 For .NET projects, install the needed `.NET` skills from the [Managed Code Skills catalog](https://skills.managed-code.com/).
+Aspire CLI is mandatory with MCAF/.NET setup when the repo has integration, browser, hosted, or infrastructure-backed tests. Install and validate it:
+
+```bash
+curl -sSL https://aspire.dev/install.sh | bash
+aspire --version
+```
+
 The local skill list usually includes:
 
 - `mcaf-testing`
@@ -63,3 +71,7 @@ The local skill list usually includes:
 
 - Project-specific rules go here.
 - Local rules may tighten root rules, but must not weaken them silently.
+- Stub, Fake, and Mock doubles are forbidden by default; avoid them and use real implementations, Aspire-managed resources, public APIs, or user-visible flows.
+- If a Stub, Fake, or Mock is unavoidable, document why in the nearest test or durable doc and include a removal plan.
+- Integration tests and browser tests must run only through Aspire-managed AppHost orchestration.
+- Keep infrastructure required by integration or browser coverage in Aspire projects/resources instead of ad hoc test startup code.

.codex/skills/mcaf-testing/SKILL.md

@@ -47,11 +47,14 @@ compatibility: "Requires the repository’s build and test tooling; uses command
    - `mcaf-dotnet-xunit`
    - `mcaf-dotnet-tunit`
    - `mcaf-dotnet-mstest`
-5. Prefer integration, API, or UI coverage when behaviour crosses boundaries.
-6. Prove the user flow or caller-visible system flow, not just internal details.
-7. Add a regression test for every bug that can be captured reliably.
-8. If the stack is .NET and production code changed, do not stop at tests only. Finish with the repo-defined format and analyzer pass as well.
-9. Use deeper testing references only when the repo’s current strategy is unclear.
+5. When installing or validating MCAF/.NET test setup, require Aspire CLI for integration, browser, hosted, or infrastructure-backed tests. Install with `curl -sSL https://aspire.dev/install.sh | bash` on macOS/Linux and validate with `aspire --version`.
+6. Prefer Aspire-backed integration, API, or UI coverage when behaviour crosses boundaries.
+7. Treat Stub, Fake, and Mock doubles as forbidden by default. Use real implementations, Aspire-managed resources, public APIs, or user-visible flows instead.
+8. Allow a Stub, Fake, or Mock only when the real dependency cannot practically run through Aspire or when an interaction has no observable state or output. Document the reason and removal plan.
+9. Prove the user flow or caller-visible system flow, not just internal details.
+10. Add a regression test for every bug that can be captured reliably.
+11. If the stack is .NET and production code changed, do not stop at tests only. Finish with the repo-defined format and analyzer pass as well.
+12. Use deeper testing references only when the repo’s current strategy is unclear.
 
 ## Deliver
 
@@ -63,6 +66,8 @@ compatibility: "Requires the repository’s build and test tooling; uses command
 - the new behaviour is covered at the right level
 - the main user flow or caller-visible system flow is proven
 - tests assert meaningful outcomes, not implementation trivia
+- Stub, Fake, and Mock doubles are absent, or every exception has a documented reason and removal plan
+- infrastructure-backed tests run through Aspire instead of ad hoc startup code
 - coverage expectations from `AGENTS.md` are met, or the exception is documented
 - the verification sequence matches `AGENTS.md`
 - for .NET changes, tests were not treated as a substitute for formatting or analyzer gates

.codex/skills/mcaf-testing/references/automated-testing.md

@@ -8,6 +8,8 @@ Automated testing in MCAF is evidence, not ceremony.
 - default to TDD: write the failing test first, make it pass, then refactor
 - pick the highest-value test level that proves the change
 - tests prove user-visible or caller-visible flow, not just internal implementation
+- Stub, Fake, and Mock doubles are forbidden by default; avoid them unless an exception is explicitly documented with the reason and removal plan
+- use Aspire-managed resources for integration, browser, hosted, and infrastructure-backed tests
 - start small, then widen verification only when necessary
 - flaky tests are bugs
 
@@ -20,15 +22,16 @@ Automated testing in MCAF is evidence, not ceremony.
 ## Test-Level Selection
 
 - unit tests for isolated logic
-- integration tests for real boundary interaction
+- integration tests for real boundary interaction through Aspire-managed orchestration when infrastructure or hosting is involved
 - API tests for public contracts
-- UI or end-to-end tests for user-visible flows
+- UI or end-to-end tests for user-visible flows through Aspire-managed application hosting
 
 ## User-Flow Coverage
 
 - tests must prove the main user flow or caller-visible system flow changed by the work
 - for user-visible behaviour, cover the happy path and the most important failure or edge path at integration, API, or UI level
 - for cross-boundary changes, prefer tests that exercise the real contract between components over isolated implementation checks
+- prefer moving verification into Aspire whenever the behavior needs hosted services, browsers, containers, databases, queues, caches, or emulators
 - if the change is not directly user-facing, prove the system flow at the boundary that another module, job, or API caller actually uses
 
 ## Coverage Norms
@@ -48,7 +51,8 @@ Automated testing in MCAF is evidence, not ceremony.
 
 ## Common Smells
 
-- mocks, fakes, or stubs hiding broken integration paths
+- any Stub, Fake, or Mock without a documented exception and removal plan
+- ad hoc infrastructure startup outside Aspire for integration or browser tests
 - huge suites run before any focused verification
 - tests that only prove implementation detail
 - tests nobody trusts enough to keep

AGENTS.md

@@ -171,6 +171,12 @@ List only the skills this repository should actively use.
 - Bug fixes start with a failing regression test when practical.
 - Test user-visible behavior and boundary contracts, not only internal implementation details.
 - Prefer realistic verification over mock-heavy tests.
+- Stub, Fake, and Mock test doubles are forbidden by default. Avoid them and prove behavior through real implementations, Aspire-managed resources, public APIs, or user-visible flows.
+- A Stub may only supply deterministic indirect input, a Fake may only replace a dependency that cannot practically run in Aspire, and a Mock may only verify an interaction that has no observable state or output. Every exception must be documented in the nearest test or durable doc with the reason and removal plan.
+- Aspire CLI is a required local prerequisite alongside the MCAF skill setup. Install it with `curl -sSL https://aspire.dev/install.sh | bash` on macOS/Linux and verify with `aspire --version`.
+- All repository tests must be able to run under Aspire orchestration when the test surface depends on application hosting, services, browsers, or external infrastructure.
+- Integration tests and browser tests must run only through Aspire-managed AppHost orchestration; do not create parallel ad hoc service startup, browser host, container, database, queue, cache, or emulator infrastructure outside Aspire for those tests.
+- Test infrastructure that supports integration or browser coverage belongs in Aspire projects and Aspire resources so local, CI, and future runtime verification use the same orchestration path. Prefer moving more verification into Aspire whenever infrastructure, hosting, or end-to-end behavior is involved.
 - Flaky tests are failures and must be fixed, not ignored.
 - Active runtime CI coverage gates must stay at or above 90% unless an ADR explicitly changes that policy.
 - Repository or module coverage must not go down without an explicit written exception.

SDK/dotnet/tests/ManagedCode.Tps.Tests/AGENTS.md

@@ -65,3 +65,6 @@ For this .NET project:
 - Keep test project namespaces under `ManagedCode.Tps.Tests`.
 - Do not move production logic into test helpers.
 - Prefer behavior-oriented tests over implementation-detail assertions.
+- Stub, Fake, and Mock doubles are forbidden by default; use real implementations and Aspire-managed resources unless an exception is documented with a reason and removal plan.
+- Keep integration and browser tests Aspire-owned: they must use the repository AppHost and Aspire-managed resources instead of starting local infrastructure directly from tests.
+- Keep any infrastructure required by integration or browser coverage in Aspire projects/resources so `aspire run` remains the canonical orchestration path.