Skip to content

docs: document covariant parameter matching#769

Merged
vbreuss merged 2 commits into
mainfrom
docs/parameter-matching-covariance
May 10, 2026
Merged

docs: document covariant parameter matching#769
vbreuss merged 2 commits into
mainfrom
docs/parameter-matching-covariance

Conversation

@vbreuss
Copy link
Copy Markdown
Member

@vbreuss vbreuss commented May 10, 2026

Parameter matchers are covariant in their type argument, but the parameter-matching page never said so. Add a Covariant Type Matching subsection alongside Custom Equality Comparers (the other meta-feature that spans matcher families) with a chocolate-themed example showing both setup and verify narrowing on a derived type.

@vbreuss
docs: document covariant parameter matching
6d2c638 
Parameter matchers are covariant in their type argument, but the
parameter-matching page never said so. Add a Covariant Type Matching
subsection alongside Custom Equality Comparers (the other meta-feature
that spans matcher families) with a chocolate-themed example showing
both setup and verify narrowing on a derived type.
@vbreuss vbreuss self-assigned this May 10, 2026
Copilot AI review requested due to automatic review settings May 10, 2026 07:49
@vbreuss vbreuss added the documentation Improvements or additions to documentation label May 10, 2026
@vbreuss vbreuss enabled auto-merge (squash) May 10, 2026 07:49
Copilot AI reviewed May 10, 2026
View reviewed changes
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds missing documentation for covariant parameter matcher behavior, clarifying that matchers can narrow a base-type method parameter to a derived runtime type and that the same applies to verification.

Changes:

  • Added a new “Covariant Type Matching” subsection to the parameter-matching docs.
  • Included a setup + verify example demonstrating narrowing from Chocolate to DarkChocolate.

Comment thread Docs/pages/setup/04-parameter-matching.md Outdated
Comment thread Docs/pages/setup/04-parameter-matching.md
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 10, 2026 •
edited
Loading

Test Results

    24 files  ±0      24 suites  ±0   8m 20s ⏱️ - 1m 13s
 4 086 tests ±0   4 084 ✅ ±0  2 💤 ±0  0 ❌ ±0 
26 388 runs  ±0  26 384 ✅ ±0  4 💤 ±0  0 ❌ ±0 

Results for commit ad0357e. ± Comparison against base commit 6e5f766.

♻️ This comment has been updated with latest results.

@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 10, 2026 •
edited
Loading

🚀 Benchmark Results

Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 7763 3.02GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v3


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
CreateMock Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 59.95 ns 0.493 ns 0.461 ns 0.95 440 B 1.00
Mockolate 62.82 ns 1.047 ns 0.980 ns 1.00 440 B 1.00
Imposter 282.05 ns 7.149 ns 6.687 ns 4.49 2248 B 5.11
TUnitMocks 40.88 ns 0.986 ns 0.922 ns 0.65 224 B 0.51
Moq 1,392.79 ns 8.562 ns 7.590 ns 22.18 2096 B 4.76
NSubstitute 2,046.59 ns 28.159 ns 24.962 ns 32.59 5048 B 11.47
FakeItEasy 1,814.51 ns 43.079 ns 40.296 ns 28.89 2763 B 6.28
Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

Intel Xeon Platinum 8370C CPU 2.80GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v4


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
Event Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 293.6 ns 4.84 ns 4.53 ns 0.83 1.78 KB 1.00
Mockolate 353.5 ns 13.57 ns 12.70 ns 1.00 1.78 KB 1.00
Imposter 1,538.9 ns 40.76 ns 38.12 ns 4.36 8.8 KB 4.94
TUnitMocks 227.6 ns 10.35 ns 9.68 ns 0.64 1.37 KB 0.77
Moq 15,097.2 ns 33.75 ns 28.18 ns 42.76 12.51 KB 7.02
NSubstitute 5,732.9 ns 7.01 ns 5.85 ns 16.24 9.05 KB 5.08
FakeItEasy 182,543.1 ns 1,591.51 ns 1,488.70 ns 516.98 15.26 KB 8.57
Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 7763 2.63GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v3


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
Indexer N Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 1 949.1 ns 10.47 ns 8.74 ns 0.99 3.81 KB 1.00
Mockolate 1 957.6 ns 9.65 ns 8.06 ns 1.00 3.81 KB 1.00
Imposter 1 899.7 ns 5.79 ns 5.13 ns 0.94 5.16 KB 1.35
Moq 1 225,578.9 ns 1,199.85 ns 1,063.63 ns 235.59 20.25 KB 5.31
NSubstitute 1 9,352.2 ns 51.82 ns 43.27 ns 9.77 12.84 KB 3.37
FakeItEasy 1 12,034.7 ns 35.63 ns 31.58 ns 12.57 13.63 KB 3.57
baseline* 10 2,642.5 ns 20.71 ns 19.37 ns 1.04 4.87 KB 1.00
Mockolate 10 2,545.5 ns 32.39 ns 30.30 ns 1.00 4.87 KB 1.00
Imposter 10 2,146.9 ns 37.45 ns 35.03 ns 0.84 7.97 KB 1.64
Moq 10 236,356.4 ns 1,496.26 ns 1,399.60 ns 92.86 28.64 KB 5.89
NSubstitute 10 23,212.1 ns 120.11 ns 106.47 ns 9.12 25.63 KB 5.27
FakeItEasy 10 25,450.3 ns 83.41 ns 78.02 ns 10.00 32.97 KB 6.77
Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

Intel Xeon Platinum 8370C CPU 2.80GHz (Max: 3.37GHz), 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v4


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
Method N Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 1 350.6 ns 4.30 ns 4.02 ns 0.94 2.04 KB 1.00
Mockolate 1 372.9 ns 4.67 ns 4.37 ns 1.00 2.04 KB 1.00
Imposter 1 576.5 ns 7.78 ns 7.28 ns 1.55 4.04 KB 1.98
TUnitMocks 1 685.1 ns 4.08 ns 3.62 ns 1.84 2.9 KB 1.42
Moq 1 138,819.6 ns 630.61 ns 589.87 ns 372.27 14.74 KB 7.23
NSubstitute 1 5,608.6 ns 31.47 ns 27.89 ns 15.04 9.12 KB 4.47
FakeItEasy 1 5,886.3 ns 68.07 ns 60.34 ns 15.79 8.06 KB 3.95
baseline* 10 643.9 ns 9.10 ns 8.51 ns 0.82 2.25 KB 1.00
Mockolate 10 783.0 ns 5.18 ns 4.32 ns 1.00 2.25 KB 1.00
Imposter 10 1,116.9 ns 13.43 ns 11.91 ns 1.43 5.52 KB 2.45
TUnitMocks 10 2,017.1 ns 23.16 ns 20.53 ns 2.58 4.49 KB 2.00
Moq 10 144,654.1 ns 642.88 ns 601.35 ns 184.75 18.64 KB 8.29
NSubstitute 10 8,402.5 ns 30.83 ns 27.33 ns 10.73 12.07 KB 5.36
FakeItEasy 10 9,266.8 ns 66.29 ns 62.01 ns 11.84 15.42 KB 6.85
Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

AMD EPYC 7763 2.82GHz, 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v3


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
Property N Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 1 632.8 ns 4.48 ns 4.19 ns 1.13 2.46 KB 1.00
Mockolate 1 557.9 ns 5.45 ns 5.10 ns 1.00 2.46 KB 1.00
Imposter 1 492.7 ns 8.25 ns 7.31 ns 0.88 3.13 KB 1.27
TUnitMocks 1 749.5 ns 4.44 ns 4.16 ns 1.34 2.51 KB 1.02
Moq 1 12,128.8 ns 44.52 ns 37.18 ns 21.74 10.39 KB 4.22
NSubstitute 1 7,598.4 ns 65.14 ns 60.93 ns 13.62 11.45 KB 4.65
FakeItEasy 1 8,698.7 ns 72.53 ns 67.84 ns 15.59 11.24 KB 4.57
baseline* 10 1,351.8 ns 6.61 ns 6.18 ns 1.26 2.95 KB 1.00
Mockolate 10 1,072.9 ns 11.88 ns 11.11 ns 1.00 2.95 KB 1.00
Imposter 10 1,171.2 ns 19.63 ns 18.36 ns 1.09 4.67 KB 1.58
TUnitMocks 10 2,207.9 ns 24.95 ns 23.33 ns 2.06 4.66 KB 1.58
Moq 10 19,854.4 ns 50.92 ns 42.52 ns 18.51 18.28 KB 6.19
NSubstitute 10 17,127.7 ns 59.04 ns 52.34 ns 15.97 21.08 KB 7.14
FakeItEasy 10 20,419.0 ns 138.25 ns 129.32 ns 19.03 30.81 KB 10.43
Details 
BenchmarkDotNet v0.15.8, Linux Ubuntu 24.04.4 LTS (Noble Numbat)

Intel Xeon Platinum 8370C CPU 2.80GHz (Max: 3.39GHz), 1 CPU, 4 logical and 2 physical cores

.NET SDK 10.0.203

[Host] : .NET 10.0.7 (10.0.7, 10.0.726.21808), X64 RyuJIT x86-64-v4


Job=InProcess  Toolchain=InProcessEmitToolchain  IterationCount=15

LaunchCount=1  WarmupCount=10
Callback Mean Error StdDev Ratio Allocated Alloc Ratio
baseline* 322.8 ns 2.20 ns 1.71 ns 0.78 1.68 KB 1.00
Mockolate 415.6 ns 3.12 ns 2.92 ns 1.00 1.68 KB 1.00
Imposter 527.4 ns 2.21 ns 2.07 ns 1.27 2.38 KB 1.42
TUnitMocks 768.8 ns 7.75 ns 7.25 ns 1.85 2.63 KB 1.56
Moq 72,971.9 ns 281.87 ns 249.87 ns 175.60 8.88 KB 5.28
NSubstitute 4,338.9 ns 20.31 ns 19.00 ns 10.44 7.74 KB 4.61
FakeItEasy 4,613.4 ns 12.01 ns 11.23 ns 11.10 6.8 KB 4.05

baseline* rows show the corresponding Mockolate benchmark from the most recent successful main branch build with results, for regression comparison.

@vbreuss @claude
docs: clarify fall-through wording for covariant matchers
ad0357e 
The example uses an abstract base, so there can be no base-typed
instance — only sibling derived types fall through. Reword the
paragraph to refer to "other runtime types" so it matches what the
example actually demonstrates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud Bot commented May 10, 2026

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@vbreuss vbreuss merged commit c447736 into main May 10, 2026
17 checks passed
@vbreuss vbreuss deleted the docs/parameter-matching-covariance branch May 10, 2026 08:22
github-actions Bot added a commit that referenced this pull request May 10, 2026
@github-actions
Update benchmark for c447736: docs: document covariant parameter matc…
ee7f6b4 
…hing (#769) by Valentin Breuß
github-actions Bot added a commit that referenced this pull request May 10, 2026
@github-actions
Update benchmark for c447736: docs: document covariant parameter matc…
be761c7 
…hing (#769) by Valentin Breuß
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 11, 2026

This is addressed in release v3.2.0.

@github-actions github-actions Bot added the state: released The issue is released label May 11, 2026
This was referenced May 18, 2026
Open
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

@vbreuss vbreuss

Labels

documentation Improvements or additions to documentation state: released The issue is released

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@vbreuss