Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions by dennisdoomen · Pull Request #3271 · fluentassertions/fluentassertions · GitHub

Ports the work originally submitted in #2432 by @Meir017 ( Meir017:feature/api-subset-and-superset), which added BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions.

That PR could not be reopened because its base branch (develop) has since been deleted/renamed to main, so this PR recreates the same feature against current main.

What's included

BeSupersetOf / BeProperSubsetOf / BeProperSupersetOf assertions on GenericCollectionAssertions
ConvertOrCastToSet extension in EnumerableExtensions
Extracted AssertSubsetOf / AssertContainment helpers so BeSubsetOf / Contain share logic with the new assertions
Ported and adjusted spec tests from the original PR (adapted to the current AssertionChain API; fixed a couple of tests that relied on .And.-chaining the same assertions instance, which no longer replays a second failing assertion once the chain has already failed)
Updated docs/_pages/collections.md and docs/_pages/releases.md
Regenerated API approval baselines (AcceptApiChanges.ps1)

Closes #2432
Resolves #2363

All credit for the original design and implementation goes to @Meir017.

Empty-collection behavior

Following up on review feedback, here's how each assertion behaves when the expected collection is empty:

Assertion	Expectation	Subject	Result
BeSubsetOf	empty	empty	Passes
BeSubsetOf	empty	non-empty	Fails (subject has extra items)
BeProperSubsetOf	empty	empty	Fails (two empty collections are identical, so it's not a proper subset)
BeSupersetOf	empty	empty or non-empty	Passes (there's nothing left to find in an empty expectation, so it's always satisfied)
BeProperSupersetOf	empty	empty	Fails (identical collections aren't a proper superset)
BeProperSupersetOf	empty	non-empty	Passes (any non-empty collection is a proper superset of an empty one)
any of the four	null	any	Throws ArgumentNullException

BeSupersetOf and BeProperSupersetOf previously threw ArgumentException for an empty expectation instead of evaluating normally - that's now fixed so they behave consistently with BeSubsetOf/BeProperSubsetOf.

Pull request overview

Adds new set-containment style collection assertions to FluentAssertions (BeSupersetOf, BeProperSubsetOf, BeProperSupersetOf) and factors shared subset/containment logic to reduce duplication, along with tests, docs, and updated API approval baselines.

Changes:

Added BeSupersetOf, BeProperSubsetOf, and BeProperSupersetOf to GenericCollectionAssertions.
Extracted shared helpers (AssertSubsetOf, AssertContainment) and introduced ConvertOrCastToSet for set-based checks.
Added/ported specs and updated collection docs + release notes + API approval baselines.

Reviewed changes

Copilot reviewed 11 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeSupersetOf.cs	New specs covering BeSupersetOf success/failure and scope behavior.
Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeProperSupersetOf.cs	New specs covering BeProperSupersetOf, including equivalence and duplicates scenarios.
Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeProperSubsetOf.cs	New specs covering BeProperSubsetOf, including equivalence and null/empty scenarios.
Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.1.verified.txt	API baseline updated for new assertions.
Tests/Approval.Tests/ApprovedApi/FluentAssertions/netstandard2.0.verified.txt	API baseline updated for new assertions.
Tests/Approval.Tests/ApprovedApi/FluentAssertions/net6.0.verified.txt	API baseline updated for new assertions.
Tests/Approval.Tests/ApprovedApi/FluentAssertions/net47.verified.txt	API baseline updated for new assertions.
Src/FluentAssertions/Common/EnumerableExtensions.cs	Adds internal ConvertOrCastToSet helper for set-based operations.
Src/FluentAssertions/Collections/GenericCollectionAssertions.cs	Implements the new assertions and refactors subset/containment logic into helpers.
docs/_pages/releases.md	Adds an “Unreleased” note about the new collection assertions.
docs/_pages/collections.md	Documents usage examples for the new assertions.
.gitignore	Fixes .junie/memory/ ignore entry and adds .nuke/temp.

Suppressed comments (1)

Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeProperSupersetOf.cs:68

Test name says "proper subset" but this spec is for BeProperSupersetOf. Rename to "proper superset" to match the behavior under test.

        public void A_collection_with_duplicates_is_not_a_proper_subset_of_another_with_duplicates()

…assertions Ports the work originally submitted in PR fluentassertions#2432 by @Meir017, adapted to the current AssertionChain-based assertion API. The original PR could not be reopened because its base branch (develop) no longer exists. - Add ConvertOrCastToSet extension to EnumerableExtensions - Extract AssertSubsetOf and AssertContainment helpers in GenericCollectionAssertions to share logic with the new assertions - Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf methods - Add spec tests ported from the original PR - Update collections.md docs and releases.md Co-authored-by: Meir017 <Meir017@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Pull request overview

Copilot reviewed 11 out of 12 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeProperSubsetOf.cs:54

This test name says the collection "has extra items", but the Arrange section is asserting that duplicates do not make a collection a proper subset when the distinct items are equivalent to the superset. Rename the test to describe equivalence rather than extra elements.

        public void A_collection_with_all_items_and_duplicates_of_a_superset_but_has_extra_items_is_not_a_proper_subset()

Tests/FluentAssertions.Specs/Collections/CollectionAssertionSpecs.BeProperSubsetOf.cs:38

This test name says the collection "has extra items", but the Arrange section uses two collections with the same distinct items (they're equivalent as sets). Rename the test to reflect that the failure is due to equivalence (not extra elements).

This issue also appears on line 54 of the same file.

        public void A_collection_with_all_items_of_a_superset_but_has_extra_items_is_not_a_proper_subset()

We have an inconsistency in whether we allow the expectation to be empty.
E.g. when both subject and expectation are empty we get the following outcomes.

BeSubsetOf: passes
BeProperSubsetOf: Expected subset to be a proper subset of {empty}, but items {empty} are equivalent to the superset {empty}
BeSupersetOf: ArgumentException : Cannot verify containment against an empty collection (Parameter 'expected')
BeProperSupersetOf: ArgumentException : Cannot verify containment against an empty collection (Parameter 'expected')

I think the superset APIs should allow the expectation to be empty.
See e.g. the discussion in #2143

Addresses jnyrup's review feedback on fluentassertions#3271: BeSupersetOf and BeProperSupersetOf previously threw ArgumentException when the expected collection was empty, which was inconsistent with BeSubsetOf/BeProperSubsetOf (an empty set is trivially a subset of everything, so a superset check against an empty expectation should never throw). - Split the empty-argument guard out of AssertContainment behind an allowEmptyExpectation flag so Contain keeps its existing behavior while BeSupersetOf/BeProperSupersetOf now evaluate normally instead of throwing. - BeSupersetOf(empty) now always passes. - BeProperSupersetOf(empty) now passes when the subject is non-empty and fails (not throws) when the subject is also empty, since two empty collections are identical rather than a proper superset. - Rewrote the XML doc comments for BeSubsetOf/BeSupersetOf/ BeProperSubsetOf/BeProperSupersetOf in plain language, removing set notation and math jargon, and dropped the now-inaccurate ArgumentException doc entries for the superset methods. - Wrapped single-element expectations in curly braces in the new superset failure messages, matching how multi-element collections are already rendered. - Added missing spec coverage: null expectation, both empty, and equal-non-empty collections for BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf. - Updated docs/_pages/collections.md and releases.md. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

We have an inconsistency in whether we allow the expectation to be empty. E.g. when both subject and expectation are empty we get the following outcomes.

BeSubsetOf: passes

BeProperSubsetOf: Expected subset to be a proper subset of {empty}, but items {empty} are equivalent to the superset {empty}

BeSupersetOf: ArgumentException : Cannot verify containment against an empty collection (Parameter 'expected')

BeProperSupersetOf: ArgumentException : Cannot verify containment against an empty collection (Parameter 'expected')

I think the superset APIs should allow the expectation to be empty. See e.g. the discussion in #2143

Good points indeed. I think I have all scenarios covered now.

…ainment Fixes a CI failure (StackTraceHiddenSpecs.Non_public_methods_in_annotable_classes_are_hidden) surfaced after modifying these private helper methods. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

dennisdoomen had a problem deploying to qodana-pr July 18, 2026 09:02 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr July 18, 2026 09:03 — with GitHub Actions Failure

dennisdoomen mentioned this pull request Jul 18, 2026

Feature: Add collections methods BeProperSubsetOf / BeProperSupersetOf / BeSupersetOf #2432

Closed

6 of 7 tasks

Copilot AI review requested due to automatic review settings August 1, 2026 08:02

dennisdoomen force-pushed the feature/subset-superset-collections branch from e5c70c6 to f6d8d37 Compare August 1, 2026 08:02

dennisdoomen had a problem deploying to qodana-pr August 1, 2026 08:02 — with GitHub Actions Failure

Copilot started reviewing on behalf of dennisdoomen August 1, 2026 08:02 View session

Copilot AI reviewed Aug 1, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings August 1, 2026 08:24

dennisdoomen force-pushed the feature/subset-superset-collections branch from f6d8d37 to eb4bd82 Compare August 1, 2026 08:24

dennisdoomen had a problem deploying to qodana-pr August 1, 2026 08:24 — with GitHub Actions Failure

Copilot started reviewing on behalf of dennisdoomen August 1, 2026 08:24 View session

Copilot AI reviewed Aug 1, 2026

View reviewed changes

dennisdoomen requested a review from jnyrup August 1, 2026 08:27

dennisdoomen had a problem deploying to qodana-pr August 1, 2026 14:05 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr August 1, 2026 15:28 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr August 2, 2026 05:20 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr August 2, 2026 05:31 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr August 2, 2026 05:36 — with GitHub Actions Failure

jnyrup requested changes Aug 8, 2026

View reviewed changes

dennisdoomen had a problem deploying to qodana-pr August 8, 2026 17:21 — with GitHub Actions Failure

dennisdoomen had a problem deploying to qodana-pr August 8, 2026 17:29 — with GitHub Actions Failure

jnyrup approved these changes Aug 8, 2026

View reviewed changes

Comment thread docs/_pages/releases.md Outdated

Merge release note into a single line for PR 3271

14c2294

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

dennisdoomen had a problem deploying to qodana-pr August 8, 2026 20:14 — with GitHub Actions Failure

dennisdoomen added the enhancement label Aug 8, 2026

Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions by dennisdoomen · Pull Request #3271 · fluentassertions/fluentassertions · GitHub

Repository navigation

Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions - #3271

Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions#3271
dennisdoomen merged 4 commits into
fluentassertions:mainfrom
dennisdoomen:feature/subset-superset-collections

dennisdoomen commented Jul 18, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

jnyrup left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dennisdoomen commented Aug 8, 2026

Uh oh!

Uh oh!

This branch had an error being deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions by dennisdoomen · Pull Request #3271 · fluentassertions/fluentassertions · GitHub

Repository navigation

Add BeSupersetOf, BeProperSubsetOf and BeProperSupersetOf collection assertions - #3271

Conversation

dennisdoomen commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's included

Empty-collection behavior

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

jnyrup left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dennisdoomen commented Aug 8, 2026

Uh oh!

Uh oh!

This branch had an error being deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dennisdoomen commented Jul 18, 2026 •
edited
Loading