Structured Logging & Diagnostics

[cwinland]

Description:
Add structured logging and diagnostics to improve observability. Deliverables:

• JSON/key-value logs for setups, executions, and verifications
• Dependency graph dumps and call traces
• Integration with ILogger<T> and test framework outputs
• Optional verbosity levels and filtering

[cwinland]

Context

We want to add structured logging and diagnostics to FastMoq to improve observability during test execution.
This will help developers:

• Understand what FastMoq is doing under the hood.
• Debug constructor resolution, mock creation, and verification steps.
• Capture detailed traces for troubleshooting intermittent or complex test failures.

The design should be provider‑agnostic (works regardless of Moq, NSubstitute, etc.) and integrate cleanly with ILogger<T> and test framework outputs.

---

High‑Level Goals

• Structured logs: JSON or key‑value format for setups, executions, and verifications.
• Dependency graph dumps: Show how mocks and real instances are wired together.
• Call traces: Record method calls and verification steps.
• Integration points:
  • ILogger<T> for runtime logging.
  • Test framework outputs (e.g., xUnit ITestOutputHelper).
• Configurable verbosity: Minimal by default, with opt‑in for detailed traces.
• Filtering: Include/exclude categories, providers, or event types.

---

Proposed Structure

1. Logging Abstraction

public interface IFastMoqLogger
{
    void Log(LogLevel level, string message, object? data = null);
    void LogStructured(LogLevel level, string message, IDictionary<string, object> properties);
}

• Allows swapping between console, ILogger<T>, or in‑memory log sinks.
• Keeps logging provider‑agnostic.

---

2. Integration with Mocker

• Mocker accepts an optional IFastMoqLogger in its constructor.
• All key lifecycle events (mock creation, constructor selection, verification) log structured entries.
• Example:

{
  "event": "MockCreated",
  "type": "IMyService",
  "provider": "Moq",
  "timestamp": "2025-09-18T17:45:00Z"
}

---

3. Dependency Graph & Call Trace

• Dependency Graph: Generated after component creation, showing resolved dependencies and their sources (mock vs real).
• Call Trace: Captured during .When() and .Verify() phases in the Scenario Builder.
• Output can be:
  • JSON for machine parsing.
  • ASCII/Markdown for human‑readable test logs.

---

4. Verbosity & Filtering

public class LoggingOptions
{
    public LogLevel MinimumLevel { get; set; } = LogLevel.Information;
    public bool IncludeDependencyGraph { get; set; } = false;
    public bool IncludeCallTrace { get; set; } = false;
    public Func<string, bool>? CategoryFilter { get; set; }
}

• Passed into Mocker or Scenario to control output.

---

Example Usage

var logger = new TestOutputLogger(outputHelper); // wraps ITestOutputHelper
var mocker = new Mocker(logger, new LoggingOptions
{
    MinimumLevel = LogLevel.Debug,
    IncludeDependencyGraph = true,
    IncludeCallTrace = true
});

Scenario
    .With(Component)
    .When(svc => svc.ProcessOrder(orderId))
    .Then(svc => svc.LastProcessedOrder.ShouldBe(orderId))
    .Verify(() => mocker.VerifyCalledOnce<IOrderRepository>(r => r.Save(orderId)))
    .Execute();

• Logs:
  • Constructor chosen and why.
  • Mocks created and injected.
  • Method calls and arguments.
  • Verification results.

---

Benefits

• Debuggable: Clear insight into what FastMoq is doing.
• Provider‑agnostic: Works with any mocking backend.
• Configurable: Developers choose the level of detail.
• Actionable: Dependency graphs and call traces help pinpoint root causes.

---

Next Steps:

1. Define IFastMoqLogger and LoggingOptions.
2. Add structured logging calls in Mocker and constructor resolution logic.
3. Implement dependency graph and call trace generation.
4. Integrate with Scenario Builder for .LogScenario() in Milestone 2.
5. Add cookbook examples in Milestone 5.