Skip to main content
Version: v6

Should-ContainCollection

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS​

Checks that the expected collection is present in the actual collection as an ordered subsequence. It does not compare the types of the input collections.

SYNTAX​

Should-ContainCollection [-Expected] <Object> [[-Actual] <Object>] [-IgnoreOrder]
 [-Because <string>]

DESCRIPTION​

The items of the expected collection must appear in the actual collection in the same order. Gaps between the matched items are allowed, but each actual item is used at most once, so repeated expected items need at least as many matching items in the actual collection. A single value is treated as a one-item collection. Items are compared using PowerShell equality, the same as the -contains operator.

Use -IgnoreOrder to check that the expected items are present in any order. Each actual item is still used at most once, so repeated expected items need at least as many matching items in the actual collection.

EXAMPLES​

EXAMPLE 1​

1, 2, 3 | Should-ContainCollection @(1, 2)
1, 2, 3 | Should-ContainCollection @(1, 3)
@(1) | Should-ContainCollection @(1)
1, 2, 3 | Should-ContainCollection 2

These assertions pass, because the expected items are present in the same order. Gaps between them, as in @(1, 3), are allowed, and a single value is treated as a one-item collection.

EXAMPLE 2​

'b', 3, 2, 'a' | Should-ContainCollection @('a', 2) -IgnoreOrder
1, 2, 3 | Should-ContainCollection @(3, 2, 1) -IgnoreOrder

These assertions pass, because with -IgnoreOrder the expected items only need to be present, not in any particular order.

EXAMPLE 3​

1, 2, 3 | Should-ContainCollection @(3, 4)
1, 2, 3 | Should-ContainCollection @(3, 2, 1)
1, 2 | Should-ContainCollection @(1, 1)
@(1) | Should-ContainCollection @(2)

These assertions fail, because an expected item is missing (@(3, 4)), the items are not in the right order (@(3, 2, 1)), or the actual collection does not have enough matching items (@(1, 1) needs two 1s).

PARAMETERS​

-Actual​

The collection to search in.

Type: System.Object
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: true
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Because​

The reason why the input should be the expected value.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Expected​

One or more items to look for. By default they must appear as an ordered subsequence; with -IgnoreOrder the order does not matter. A single value is treated as a one-item collection.

Type: System.Object
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-IgnoreOrder​

Ignores the order of the items, so the expected items only need to be present in the actual collection, in any order.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters​

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS​

System.Object​

OUTPUTS​

NOTES​

Use the -ErrorAction parameter to control soft-assertion behavior for this assertion. -ErrorAction Continue records the failure and lets the rest of the test run (a soft assertion), while -ErrorAction Stop fails the test immediately, for example to guard a precondition before continuing.

When -ErrorAction is not specified, the behavior comes from Should.ErrorAction in the configuration, which defaults to Stop. See https://pester.dev/docs/assertions/soft-assertions for more about soft assertions.

VERSION​

This page was generated using comment-based help in Pester 6.1.0.