Repository navigation
Add the Testing with xUnit chapter to the book - #1024
FreeApophis wants to merge 2 commits into
Conversation
Documents Funcky.Xunit (xUnit.net 2.x) and Funcky.Xunit.v3 (3.x): the Assert.Some/None/Ok/Error/Left/Right members with their expected-value and returning overloads, the exact-type Error<TException, T> overload, the failure message format, why there is no Assert.True(option.IsSome), the analyzer rules λ1101 and λ1203, ToTheoryData and the v3 serializers with their Register*Serializer assembly attributes. Closes #1017 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
The documentation still misstates None assertion failures, stack-trace behavior on older frameworks, and xUnit 3 theory-data serialization requirements.
3 open issues
What changed in this PR
Adds a “Testing with xUnit” chapter to the book, addressing #1017 with guidance for testing Funcky’s monadic types.
Changes:
- Documents package selection, assertion overloads, failure messages, and related analyzer rules.
- Explains xUnit 2.x theory-data helpers and xUnit 3.x serializers.
- Adds the chapter to the book’s navigation.
| File | Description |
|---|---|
Documentation/src/xunit.md |
Adds guidance and examples for testing with Funcky’s xUnit integrations. |
Documentation/src/SUMMARY.md |
Links the new chapter before Analyzer Rules. |
Review effort: Balanced
| [λ1101](./analyzer-rules/λ1101.md) flags the first form and rewrites it to the second. The single call is not only | ||
| shorter: the assertion knows the monad it unwrapped, so a failing test reports `Expected: Some(42)` and | ||
| `Actual: None` instead of a `NullReferenceException` or a generic `Assert.Equal` failure. |
There was a problem hiding this comment.
Confirmed and fixed in 7118009: the paragraph now says both forms fail None as an assertion failure and describes the real gain, the expected content in the message and the monad context when the values differ.
| The assertion's own frames are hidden from the stack trace (`[StackTraceHidden]` on .NET 6 and later, a rethrow that | ||
| erases the frames elsewhere), so the first line of the trace is the test that failed. |
There was a problem hiding this comment.
Confirmed and fixed in 7118009: the first-frame guarantee is limited to .NET 6 and later, and the text describes the rethrow on older frameworks leaving the assertion method as the first frame.
| xunit 3.x only accepts theory-data values it can serialize, so that each row shows up as its own test in the | ||
| runner and can be rerun on its own. Funcky.Xunit.v3 ships serializers for `Option<T>`, `Either<L, R>` and `Unit`, | ||
| so these types can be theory parameters directly: |
There was a problem hiding this comment.
Confirmed and fixed in 7118009: the paragraph now says xunit 3 runs theories with any data and that serialization buys per-row discovery and reruns, with non-serializable rows collapsing the theory into a single test case.
Assert.Some(option) fails None with an assertion failure of its own, so the gain of the expected-value overload is the expected content in the message and the monad context when the values differ. Only .NET 6 and later hide the assertion frame; the rethrow on older frameworks leaves the assertion method as the first frame. xunit 3 runs theories with non-serializable data too, serialization buys per-row discovery. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Closes #1017
Adds
Documentation/src/xunit.md("Testing with xUnit", listed inSUMMARY.mdafter Nullable Member Extensions, before Analyzer Rules). The chapter covers:Assert(Some,None,Ok,Error,Left,Right), the expected-value and returning overloads, and the exact-typeError<TException, T>overload.FunctionalAssertis described as the form for compilers older than C# 14, with theAssertmembers as the implementation, i.e. the state after Make the Assert members the implementation of the xunit assertions #1011.FunctionalAssert.X() Failure: Values differ/Expected:/Actual:), and the hidden stack frames.Assert.True(option.IsSome), tied to the introduction's "noHasValue" idea.ToTheoryData(2.x only) and the v3 serializers forOption,EitherandUnit, including the automatic registration through the build targets (IsTestProject,FunckyRegisterXunitSerializers) and theFuncky.Xunit.Register*SerializerAttributeassembly attributes.Every member name, overload and attribute was checked against
Funcky.Xunit/Extensions/AssertExtensions.cs,Funcky.Xunit/FunctionalAssert/*.cs,Funcky.Xunit/Extensions/ToTheoryDataExtension.cs,Funcky.Xunit.v3/and the tests. mdbook and typos run in CI.🤖 Generated with Claude Code