Add simulated network failures ThrowsException/TimesOut (closes #116)

[dennisdoomen]

Closes #116

Stacking

This is the top of a 3-PR stack and targets dennisdoomen/response-latency-after:

• Stacks on Add simulated response latency .After(TimeSpan) (closes #117) #134 (issue Add simulated response latency (.After(TimeSpan)) for timeout/cancellation/resilience testing #117 — response latency / After())
• Which stacks on Add async responder overloads and CancellationToken flow #132 (issue Add async responder overloads and flow CancellationToken into responders #120 — async responder pipeline / CancellationToken threading)

It builds on the async responder path (TrackRequestAsync, CancellationToken flowing from SendAsync → HandleRequest → RequestMock) introduced in those PRs and does not re-implement them.

Summary

Adds first-class support for simulating network-level failures so tests can exercise retry, circuit-breaker and error-handling code.

Previously the pipeline swallowed every responder exception and turned it into a 500 response, so there was no way to simulate a thrown transport error. This change introduces a dedicated simulated-failure responder that the async pipeline propagates to the HttpClient caller instead of catching:

• A new internal SimulatedFailureResponder type represents an intentionally simulated failure.
• RequestMock.TrackRequestAsync records the request (incrementing the invocation count and adding it to any request collection) and returns the captured request carrying the exception, rather than throwing inline. This guarantees the failed call is recorded in HttpMock.Requests (as expected/handled) before the exception reaches the caller.
• HttpMock.HandleRequest rethrows the captured exception via ExceptionDispatchInfo after recording it.
• The existing try/catch that converts responder exceptions into a 500 is carefully scoped so genuine bugs in user RespondsWith responders keep the current 500 behavior, while intentionally-simulated failures propagate.
• Once() / Times(n) and After() continue to apply to simulated failures.

New public API

RequestMockResponseBuilder ThrowsException(Exception exception);
RequestMockResponseBuilder ThrowsException<TException>() where TException : Exception, new();
RequestMockResponseBuilder TimesOut(); // throws TaskCanceledException, mimicking an HttpClient timeout

Plus CapturedRequest.SimulatedFailure (Exception?) so a captured entry can be inspected to tell a simulated throw apart from an unexpected 500.

Usage:

mock.ForGet().WithPath("/flaky").ThrowsException<HttpRequestException>();
mock.ForGet().WithPath("/slow").TimesOut();

This is additive and backward-compatible. The API verification baselines (net8.0, net472) were regenerated via AcceptApiChanges.ps1.

Tests

New WhenSimulatingNetworkFailures spec class (xUnit + FluentAssertions, AAA) covering:

• HttpRequestException surfaces to the HttpClient caller (generic and specific-instance overloads)
• TimesOut() throws TaskCanceledException
• the failed call is captured in HttpMock.Requests and in a CollectingRequestsIn collection
• Once() / Times(n) still apply
• a genuinely buggy responder still results in a 500
• null exception is rejected

All 108 specs pass on both net8.0 and net472; Release build (warnings-as-errors, all analyzers) is clean.

Follow-up

Issue #116 also describes a companion CapturedRequestAssertions.BeASimulatedFailure() assertion in the separate dennisdoomen/fluentassertions.mockly repo (v7/v8 via Shared/). That is not part of this repo/workspace and needs its own PR; the new public CapturedRequest.SimulatedFailure property is exposed here so that assertion can be built on top of it.

[github-actions]

Test Results

  3 files  ± 0    3 suites  ±0   13s ⏱️ +5s
110 tests + 9  110 ✅ + 9  0 💤 ±0  0 ❌ ±0 
217 runs  +18  217 ✅ +18  0 💤 ±0  0 ❌ ±0 

Results for commit 2ca9d81. ± Comparison against base commit a2b689e.

♻️ This comment has been updated with latest results.

[coveralls]

Coverage Report for CI Build 26678769048

Coverage increased (+0.2%) to 82.82%

Details

• Coverage increased (+0.2%) from the base build.
• Patch coverage: 5 uncovered changes across 1 file (50 of 55 lines covered, 90.91%).
• No coverage regressions found.

Uncovered Changes

File	Changed	Covered	%
Mockly/RequestMock.cs	19	14	73.68%
Total (5 files)	55	50	90.91%

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1124
Covered Lines:	985
Line Coverage:	87.63%
Relevant Branches:	337
Covered Branches:	225
Branch Coverage:	66.77%
Branches in Coverage %:	Yes
Coverage Strength:	338.44 hits per line

---

💛 - Coveralls