Make Should-ContainCollection match a real sub-collection

[nohwnd]

Problem

Should-ContainCollection / Should-NotContainCollection were implemented with PowerShell's -contains operator, which only tests whether a collection contains a single scalar value. When the right-hand side is itself a collection, -contains compares it by object identity and essentially never matches.

The comment-based help (which generates the pester.dev pages), and the assertion's name, told a different story — they documented multi-item examples and claimed they pass:

1, 2, 3 | Should-ContainCollection @(1, 2)   # help said "pass", actually FAILED
@(1)    | Should-ContainCollection @(1)       # help said "pass", actually FAILED

So the docs and the behaviour disagreed, and the promised sub-collection containment was never actually implemented. Should-NotContainCollection's help also had a copy-paste error referencing Should-ContainCollection in its examples.

Change

Implement true ordered-subsequence containment:

• the expected items must appear in the actual collection in the same order,
• gaps are allowed between matched items,
• each actual item is consumed at most once, so repeated expected items need at least as many matching actual items,
• a single value is still treated as a one-item collection, so existing single-item usage is unchanged.

The matching logic lives in a new shared Is-CollectionSubsequence helper (greedy two-pointer). The comment-based help for both assertions is rewritten to describe the real semantics, and the copy-paste error in Should-NotContainCollection is fixed.

Behaviour now

Expression	Result
1, 2, 3 | Should-ContainCollection @(1, 2)	✅ pass (contiguous)
1, 2, 3 | Should-ContainCollection @(1, 3)	✅ pass (gap allowed)
1, 2, 3 | Should-ContainCollection @(3, 2, 1)	❌ fail (wrong order)
1, 2, 3 | Should-ContainCollection @(3, 4)	❌ fail (missing item)
1, 1, 2 | Should-ContainCollection @(1, 1)	✅ pass (two 1s available)
1, 2 | Should-ContainCollection @(1, 1)	❌ fail (no reuse)
@('a','b','c') | Should-ContainCollection 'b'	✅ pass (single value, unchanged)

Tests

Added contiguous, gapped, out-of-order and duplicate cases to both test files. All 868 assert tests pass, and PSScriptAnalyzer is clean on the changed files.

Note

This changes the runtime behaviour of these two assertions to match what their name and documentation always described. Single-item containment — the only thing that actually worked before — is preserved.