Should-BeEquivalent

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS

Compares two objects for equivalency, by recursively comparing their properties for equivalency.

SYNTAX

Should-BeEquivalent [-Expected] <Object> [[-Actual] <Object>] [-Because <string>]
 [-ExcludePath <string[]>] [-ExcludePathsNotOnExpected] [-Comparator <string>]

DESCRIPTION

This assertion performs a deep comparison of the actual and expected objects, recursing through nested properties and collections. Use -ExcludePath, -ExcludePathsNotOnExpected, or -Comparator Equality to narrow what counts as equivalent.

EXAMPLES

EXAMPLE 1

Should-BeEquivalent ...  -ExcludePath 'Id', 'Timestamp' -Comparator 'Equality'

This example generates an equivalency option object that excludes the 'Id' and 'Timestamp' properties from the comparison and uses a simple equality comparison strategy.

EXAMPLE 2

Should-BeEquivalent ... -ExcludePathsNotOnExpected

This example generates an equivalency option object that excludes any paths not present on the expected object from the comparison, using the default deep comparison strategy.

EXAMPLE 3

$expected = [PSCustomObject] @{
    Name = "Thomas"
}

$actual = [PSCustomObject] @{
    Name = "Jakub"
    Age = 30
}

$actual | Should-BeEquivalent $expected

This will throw an error because the actual object has an additional property Age and the Name values are not equivalent.

EXAMPLE 4

$expected = [PSCustomObject] @{
    Name = "Thomas"
}

$actual = [PSCustomObject] @{
    Name = "Thomas"
}

$actual | Should-BeEquivalent $expected

This will pass because the actual object has the same properties as the expected object and the Name values are equivalent.

PARAMETERS

-Actual

The actual object to compare.

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: ''

-Comparator

Specifies the comparison strategy to use. The options are 'Equivalency' for a deep comparison that considers the structure and values of objects, and 'Equality' for a simple equality comparison. The default is 'Equivalency'.

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

-ExcludePath

An array of strings specifying the paths to exclude from the comparison. Each path should correspond to a property name or a chain of property names separated by dots for nested properties. The paths use dot notation to navigate to a child property, such as "user.name".

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

-ExcludePathsNotOnExpected

A switch parameter that, when set, excludes any paths from the comparison that are not present on the expected object. This is useful for ignoring extra properties on the actual object that are not relevant to the comparison.

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: ''

-Expected

The expected object to compare.

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.

RELATED LINKS

• https://pester.dev/docs/commands/Should-BeEquivalent
• https://pester.dev/docs/assertions

VERSION

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