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>] [-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.

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​

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 as an ordered subsequence. 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: ''

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.0.0.