Update Docs

Author: cwinland

.github/copilot-instructions.md

@@ -18,7 +18,9 @@ It wraps and extends mocking providers (currently Moq, with planned provider‑a
 - `Mocker.cs` – Core mock registry and creation logic.
 - `MockerTestBase<T>` – Generic base for public types.
 - `MockerTestBase` – Non‑generic base for internal/protected types.
+- `MockerTestBase_Constructors.cs` – Default component creation flow, `ComponentCreationFlags`, and `ComponentConstructorParameterTypes`.
 - `MockerConstructionHelper` – Shared constructor resolution logic.
+- `ServiceProviderTestExtensions.cs` – Typed `IServiceProvider` helpers such as `CreateTypedServiceProvider(...)` and `AddServiceProvider(...)`.
 - `TestClassExtensions.cs` – Current verification helpers (e.g., `VerifyLogger`).
 - `ScenarioBuilder<T>` – Fluent scenario API (Milestone 2).
 - `IMockingProvider` – Provider abstraction (Milestone 1).
@@ -30,6 +32,8 @@ When generating code:
    - Only use Moq APIs inside `MoqProvider` or Moq‑specific test code.
 2. **Reuse shared helpers**  
    - For component creation, always call `MockerConstructionHelper.CreateInstance`.
+    - When a test must choose a constructor, prefer `MockerTestBase<TComponent>.ComponentConstructorParameterTypes` first. For direct `Mocker` usage, prefer `CreateInstanceByType(...)`. Use `CreateComponentAction` only when constructor selection cannot be expressed as a signature.
+    - When framework code needs a real `IServiceProvider` or `IServiceScopeFactory`, prefer `CreateTypedServiceProvider(...)` or `AddServiceProvider(...)` over mocked `IServiceProvider` shims or registering only `IServiceScopeFactory` from a manually built provider.
    - For verification, follow the `VerifyLogger` pattern.
 3. **Follow naming conventions**  
    - Public API methods: PascalCase.

docs/README.md

@@ -25,6 +25,8 @@ Perfect for developers new to FastMoq. Learn the basics and write your first tes
 - [Provider selection and setup](./getting-started/provider-selection.md)
 - [Provider capabilities matrix](./getting-started/provider-capabilities.md)
 - [Repo-native testing guide](./getting-started/testing-guide.md)
+- [Typed `IServiceProvider` helpers](./getting-started/testing-guide.md#typed-iserviceprovider-helpers)
+- [Explicit constructor selection in tests](./getting-started/testing-guide.md#explicit-constructor-selection-in-tests)
 - [Web helper guidance for controller and request tests](./getting-started/testing-guide.md#controller-testing)
 - [Executable testing examples](./samples/testing-examples.md)
 - Understanding the architecture

docs/getting-started/README.md

@@ -92,6 +92,7 @@ Use this table when you are deciding which package line your test project should
 Important package boundaries in the current v4 line:
 
 `FastMoq` already includes the common end-user surface, including shared Azure SDK helpers, web, database, and Azure Functions helpers
+
 - `FastMoq` also includes the FastMoq analyzer assets by default so most test projects get migration guidance without extra setup
 - `FastMoq.Core` stays lighter on purpose, so shared Azure SDK helpers, EF helpers, Azure Functions helpers, and web helpers are separate package decisions when you consume core directly
 - `FastMoq.Core` does not include analyzer assets; add `FastMoq.Analyzers` explicitly if you want analyzer guidance in a core-only package graph
@@ -379,6 +380,36 @@ public class OrderServiceTests : MockerTestBase<OrderService>
 }
 ```
 
+When a test needs a specific constructor, prefer the explicit constructor-selection hooks instead of relying on `GetObject<T>()` to land on the right overload.
+
+- For `MockerTestBase<TComponent>`, override `ComponentConstructorParameterTypes`.
+- For direct `Mocker` usage, call `CreateInstanceByType<T>(...)`.
+- If the chosen constructor depends on `IServiceProvider` or `IServiceScopeFactory`, build and register a typed provider with `AddServiceProvider(...)` instead of extracting only `IServiceScopeFactory` from a manual `BuildServiceProvider()` call.
+
+```csharp
+internal sealed class ArchiveInvokerTests : MockerTestBase<ArchiveInvoker>
+{
+    private readonly MockFileSystem fileSystem = new();
+
+    protected override Action<Mocker>? SetupMocksAction => mocker =>
+    {
+        mocker.AddType<IFileSystem>(fileSystem, replace: true);
+        mocker.AddServiceProvider(services =>
+        {
+            services.AddLogging();
+            services.AddOptions();
+            services.AddSingleton<IFileSystem>(fileSystem);
+            services.AddSingleton<ArchiveService>();
+        }, replace: true);
+    };
+
+    protected override Type?[]? ComponentConstructorParameterTypes =>
+        new Type?[] { typeof(IFileSystem), typeof(IServiceScopeFactory) };
+}
+```
+
+See the [Testing Guide](./testing-guide.md#explicit-constructor-selection-in-tests) for the full constructor-selection rules and the [typed `IServiceProvider` helper guidance](./testing-guide.md#typed-iserviceprovider-helpers) for framework-heavy ServiceCollection patterns.
+
 ## Common Patterns
 
 ### Testing Constructor Parameters

docs/getting-started/testing-guide.md

@@ -7,12 +7,14 @@ This guide documents the testing patterns that match FastMoq's current behavior
 Use these rules first:
 
 1. Use [MockerTestBase<TComponent>](xref:FastMoq.MockerTestBase`1) when you want FastMoq to create the component under test and manage its dependencies.
-2. Use [Mocks.GetOrCreateMock<T>()](xref:FastMoq.Mocker.GetOrCreateMock``1(FastMoq.MockRequestOptions)) when you want the normal FastMoq tracked mock path for a dependency.
-3. Use [AddType(...)](xref:FastMoq.Mocker.AddType``1(System.Func{FastMoq.Mocker,``0},System.Boolean,System.Object[])) when you need to replace FastMoq's default resolution with a specific concrete type, factory, or fixed instance.
-4. Use `CreateTypedServiceProvider(...)` and `AddServiceProvider(...)` when framework code expects a typed `IServiceProvider` rather than a one-object-for-all-types shim.
-5. If the constructor uses the same abstraction more than once under different DI service keys, use keyed mocks, keyed registrations, or explicit constructor injection for tests where dependency selection matters.
-6. Use [AddKnownType(...)](xref:FastMoq.Mocker.AddKnownType(FastMoq.KnownTypeRegistration,System.Boolean)) when a framework-style type needs special resolution or post-processing behavior.
-7. Use [GetMockDbContext<TContext>()](xref:FastMoq.DbContextMockerExtensions.GetMockDbContext``1(FastMoq.Mocker)) when testing EF Core contexts. Do not hand-roll DbContext setup unless you need behavior outside FastMoq's helper.
+2. If a `MockerTestBase<TComponent>` test must force a specific constructor, override `ComponentConstructorParameterTypes` first. Use `CreateComponentAction` only when the test needs custom creation logic beyond selecting a signature.
+3. Use [Mocks.GetOrCreateMock&lt;T&gt;()](xref:FastMoq.Mocker.GetOrCreateMock``1(FastMoq.MockRequestOptions)) when you want the normal FastMoq tracked mock path for a dependency.
+4. Use [AddType(...)](xref:FastMoq.Mocker.AddType``1(System.Func{FastMoq.Mocker,``0},System.Boolean,System.Object[])) when you need to replace FastMoq's default resolution with a specific concrete type, factory, or fixed instance.
+5. Use `CreateInstanceByType(...)` when direct `Mocker` usage must pick an exact constructor signature. Do not treat `GetObject<T>()` as the explicit constructor-selection API.
+6. Use `CreateTypedServiceProvider(...)` and `AddServiceProvider(...)` when framework code expects a typed `IServiceProvider` rather than a one-object-for-all-types shim.
+7. If the constructor uses the same abstraction more than once under different DI service keys, use keyed mocks, keyed registrations, or explicit constructor injection for tests where dependency selection matters.
+8. Use [AddKnownType(...)](xref:FastMoq.Mocker.AddKnownType(FastMoq.KnownTypeRegistration,System.Boolean)) when a framework-style type needs special resolution or post-processing behavior.
+9. Use [GetMockDbContext&lt;TContext&gt;()](xref:FastMoq.DbContextMockerExtensions.GetMockDbContext``1(FastMoq.Mocker)) when testing EF Core contexts. Do not hand-roll DbContext setup unless you need behavior outside FastMoq's helper.
 
 ## Core Mental Model
 
@@ -83,6 +85,29 @@ Mocks.AddServiceProvider(services =>
 });
 ```
 
+`AddServiceProvider(...)` registers the typed provider itself and, when the built container exposes them, also registers `IServiceScopeFactory` and `IServiceProviderIsService` for the current `Mocker`.
+
+If a constructor takes `IServiceScopeFactory`, prefer this shape:
+
+```csharp
+var fileSystem = new MockFileSystem();
+
+Mocks.AddType<IFileSystem>(fileSystem, replace: true);
+Mocks.AddServiceProvider(services =>
+{
+    services.AddLogging();
+    services.AddOptions();
+    services.AddSingleton<IFileSystem>(fileSystem);
+    services.AddSingleton<ArchiveService>();
+}, replace: true);
+
+var scopeFactory = Mocks.GetRequiredObject<IServiceScopeFactory>();
+```
+
+instead of building a provider manually and registering only `provider.GetRequiredService<IServiceScopeFactory>()`. Keeping the full typed provider registered makes constructor injection, nested framework resolution, and service-scope behavior stay aligned.
+
+For Azure-oriented tests that also need configuration defaults, prefer `CreateAzureServiceProvider(...)` or `AddAzureServiceProvider(...)` from `FastMoq.Azure.DependencyInjection` instead of repeating `AddLogging()`, `AddOptions()`, and `IConfiguration` setup in every test.
+
 Use `CreateFunctionContextInstanceServices(...)` and `AddFunctionContextInstanceServices(...)` for Azure Functions worker tests instead of hand-writing `FunctionContext.InstanceServices` plumbing:
 
 ```csharp
@@ -206,6 +231,7 @@ FastMoq handles constructor resolution and injection at runtime; it does not byp
 
 When a test needs a specific constructor, prefer a test-side override first.
 That keeps constructor choice inside the test harness and avoids changing production code only to satisfy test setup.
+If the selected constructor depends on `IServiceProvider` or `IServiceScopeFactory`, pair the constructor-selection hook with `AddServiceProvider(...)` from the earlier typed-provider section instead of registering only a manually extracted scope factory.
 
 For `MockerTestBase<TComponent>`, override `ComponentConstructorParameterTypes` when you want a specific signature but still want the default FastMoq creation path: