[API Proposal]: Make HttpMock disposable with an opt-in Strict mode (README's `using var mock` does not compile)

[dennisdoomen]

Bug

The README's headline sample and the "Power in Simplicity" section both start with:

using var mock = new HttpMock();

HttpMock does not implement IDisposable (see Mockly.ApiVerificationTests/ApprovedApi/net8.0.verified.txt), so that snippet does not compile. Anyone copying the first sample off the README hits a compiler error immediately.

Proposal

Rather than just dropping using from the docs, make HttpMock disposable and give disposal a purpose:

using var mock = new HttpMock { Strict = true };
// ... test body ...
// on Dispose: throws if any configured mock was never invoked,
//             or if unexpected calls were recorded

Strict would default to false, so nothing changes for existing users. With it on, you no longer have to remember HaveAllRequestsCalled() at the end of every test, and a test that forgets its assertions still fails.

Notes

• Dispose must not throw while an exception is already in flight, or it will mask the real failure. Needs care around Marshal.GetExceptionPointers() / a "did the test already fail" heuristic, or a documented caveat.
• Also lets HttpMock dispose the HttpClient instances it hands out.
• Either way, the README needs fixing — if Strict is rejected, drop using from the samples.

[dennisdoomen]

While reviewing the assertions repo I found a second non-compiling sample in the same README. The "Power in Simplicity" section ends with:

creations.Should().ContainRequestFor("/api/users")
    .Which.HasHeader("X-Trace-Id");

.Which yields a CapturedRequest, which has no HasHeader method. The correct call is the assertion on ContainedRequestAssertions:

creations.Should().ContainRequestFor("/api/users")
    .WithHeader("X-Trace-Id");

Same class of problem as the using var mock sample, so worth fixing in the same pass.