Add-MtTestResultDetail

SYNOPSIS

Add detailed information about a test so that it can be displayed in the test results report.

SYNTAX

Add-MtTestResultDetail [[-Description] <String>] [[-Result] <String>] [[-GraphObjects] <Object[]>]
 [[-GraphObjectType] <String>] [[-TestName] <String>] [[-TestTitle] <String>] [[-SkippedBecause] <String>]
 [[-SkippedCustomReason] <String>] [-Investigate] [[-SkippedError] <Object>] [[-Severity] <String>]
 [-ProgressAction <ActionPreference>] [<CommonParameters>]

DESCRIPTION

This function is used to add detailed information about a test so that it can be displayed in the test results report.

The description and result support markdown format.

If the calling script/cmdlet has a markdown file with the same name as the script/cmdlet, it will be used to populate the description and result fields.

A good example is the markdown for the Test-MtCaEmergencyAccessExists cmdlet:

The markdown file can include a separator  to split the description and result sections. This allows for the overview and detailed information to be displayed separately in the Test results.

EXAMPLES

EXAMPLE 1

Add-MtTestResultDetail -Description 'Test description' -Result 'Test result'

This example adds detailed information about a test with a brief description and the result of the test.

$policiesWithoutEmergency = $policies | Where-Object { $CheckId -notin $_.conditions.users.excludeUsers -and $CheckId -notin $_.conditions.users.excludeGroups }

Add-MtTestResultDetail -GraphObjects $policiesWithoutEmergency -GraphObjectType ConditionalAccess

This example shows how to use the Add-MtTestResultDetail function to add rich markdown content to the test results with deep links to the admin portal.

EXAMPLE 2

Add-MtTestResultDetail -Description 'Check for stale credentials' -Result 'Found 3 service principals with unused credentials' -Investigate

This example marks a test as requiring investigation. The test passed but needs manual review to confirm all scenarios were considered.

PARAMETERS

-Description

Brief description of what this test is checking. Markdown is supported.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Result

Detailed information of the test result to provide additional context to the user. This can be a summary of the items that caused the test to fail (e.g. list of user names, Conditional Access policies, etc.). Markdown is supported. If the test result contains a placeholder %TestResult%, it will be replaced with the values from the $GraphResult

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-GraphObjects

Collection of Graph objects to display in the test results report. This will be inserted into the contents of Result parameter if the result contains a placeholder %TestResult%.

Type: Object[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-GraphObjectType

The type of graph object, this will be used to show the right deep-link to the test results report.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-TestName

Pester test name Use the test name from the Pester context by default

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: $____Pester.CurrentTest.ExpandedName
Accept pipeline input: False
Accept wildcard characters: False

-TestTitle

A custom title for the test in the format of “MT.XXXX: <TestName>. Used in data driven tests like Entra recommendations 1024”

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SkippedBecause

Common reasons for why the test was skipped.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-SkippedCustomReason

A custom reason for why the test was skipped. Requires -SkippedBecause Custom.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Investigate

Marks the test as requiring investigation. The test passed but needs manual review to confirm all scenarios were considered. This is different from skipped - the test ran and collected data, but the result needs human interpretation.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

-SkippedError

The error object that caused the test to be skipped.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Severity

Severity level of the test result. Leave empty if no Severity is defined yet.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 10
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ProgressAction

Determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider, such as the progress bars generated by Write-Progress.

Type: ActionPreference
Parameter Sets: (All)
Aliases: proga

Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

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

INPUTS

OUTPUTS

NOTES

https://maester.dev/docs/commands/Add-MtTestResultDetail