Skip to main content
Version: v6

Should-BeHashtable

This page was generated

Contributions are welcome in Pester-repo.

SYNOPSIS​

Asserts that the input is a hashtable or dictionary, and optionally checks the number of entries, whether it is ordered, and that it contains specific keys.

SYNTAX​

Should-BeHashtable [[-Actual] <Object>] [-Count <int>] [-Key <string[]>] [-Ordered]
 [-Because <string>]

DESCRIPTION​

Should-BeHashtable is a shape assertion. It verifies that $Actual is a hashtable or dictionary (anything implementing System.Collections.IDictionary, such as @{}, [ordered]@{} or a generic Dictionary[,]).

It does not compare the contents of the dictionary. Use the optional parameters to assert on the shape of the dictionary:

  • -Count checks the number of entries.
  • -Ordered checks that the value is an ordered dictionary ([ordered]@{}).
  • -Key checks that the given keys are present, ignoring their values. When combined with -Ordered, the keys must also appear in the given relative order.

To compare the keys and values of a dictionary against an expected dictionary use Should-BeEquivalent instead, which performs a deep, order-insensitive comparison.

EXAMPLES​

EXAMPLE 1​

@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable
[ordered]@{ a = 1; b = 2 } | Should-BeHashtable

These assertions pass, because the actual value is a hashtable or dictionary.

EXAMPLE 2​

@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable -Count 2
@{ Name = 'Jakub'; Age = 30 } | Should-BeHashtable -Key Name, Age
[ordered]@{ a = 1; b = 2 } | Should-BeHashtable -Ordered -Key a, b

These assertions pass. The dictionary has two entries, it contains the keys Name and Age, and the ordered dictionary contains the keys a and b in that order.

EXAMPLE 3​

@{ Name = 'Jakub' } | Should-BeHashtable -Ordered
@(1, 2, 3) | Should-BeHashtable

These assertions fail. The first value is a plain (unordered) hashtable, and the second value is a collection, not a hashtable.

PARAMETERS​

-Actual​

The value to test. It is expected to be a hashtable or dictionary.

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 a hashtable with the expected shape.

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

-Count​

Checks that the dictionary has the expected number of entries.

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

-Key​

Checks that the dictionary contains the given keys. Only the presence of the keys is checked, not their values. When -Ordered is also specified, the keys must appear in the dictionary in the same relative order as they are listed here.

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

-Ordered​

Checks that the dictionary is an ordered dictionary (System.Collections.Specialized.OrderedDictionary), as produced by [ordered]@{}. A plain [hashtable] is unordered and fails this check.

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​

Should-BeHashtable only asserts on the shape of the dictionary. To compare its keys and values against an expected dictionary, use Should-BeEquivalent.

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.