Skip to content
MaesterMaester
3.0 preview2.3.0 stable

These docs describe the preview. Pick the version you run and every page marks what it doesn't have yet. Get the preview →
Maester 2.x docs (archived) →

Sponsor

Invoke-Maester

SYNOPSIS

Section titled “SYNOPSIS”

This is the main Maester command that runs the tests and generates a report of the results.

SYNTAX

Section titled “SYNTAX”
Invoke-Maester [[-Path] <String>] [-Tag <String[]>] [-ExcludeTag <String[]>] [-IncludeLongRunning]
 [-IncludePreview] [-OutputHtmlFile <String>] [-IncludeAffectedObjects] [-RedactUserIdentity <String>]
 [-OutputMarkdownFile <String>] [-OutputMarkdownSummaryFile <String>] [-OutputJsonFile <String>]
 [-OutputFolder <String>] [-OutputFolderFileName <String>] [-PesterConfiguration <PesterConfiguration>]
 [-Verbosity <String>] [-NonInteractive] [-PassThru] [-MailRecipient <String[]>] [-MailTestResultsUri <String>]
 [-MailUserId <String>] [-TeamId <String>] [-TeamChannelId <String>] [-TeamChannelWebhookUri <String>]
 [-SkipGraphConnect] [-DisableTelemetry] [-SkipVersionCheck] [-ExportCsv] [-ExportExcel] [-NoLogo]
 [-DriftRoot <String>] [-ProgressAction <ActionPreference>] [<CommonParameters>]

DESCRIPTION

Section titled “DESCRIPTION”

Using Invoke-Maester is the easiest way to run the Pester tests and generate a report of the results.

For more advanced configuration, you can directly use the Pester module and the Get-MtHtmlReport function.

By default, Invoke-Maester runs all *.Tests.ps1 files in the current directory and all subdirectories recursively, except Active Directory tests and tests tagged as LongRunning or Preview. Active Directory tests run only after an explicit Connect-Maester -Service ActiveDirectory call succeeds.

EXAMPLES

Section titled “EXAMPLES”

EXAMPLE 1

Section titled “EXAMPLE 1”
Invoke-Maester

Runs all the test files under the current folder (except for Active Directory tests and those tagged as LongRunning or Preview) and generates a report of the results in the ./test-results folder.

EXAMPLE 2

Section titled “EXAMPLE 2”
Invoke-Maester ./maester-tests

Runs all the tests in the folder ./tests/Maester (except for Active Directory tests and those tagged as LongRunning or Preview) and generates a report of the results in the default ./test-results folder.

EXAMPLE 3

Section titled “EXAMPLE 3”
Invoke-Maester -Tag 'CA' -IncludeLongRunning

Runs the tests with the tag “CA” and includes long-running tests. Generates a report of the results in the default ./test-results folder.

EXAMPLE 4

Section titled “EXAMPLE 4”
Invoke-Maester -Tag 'CA', 'App' -IncludePreview

Runs the tests with the tags ‘CA’ and ‘App’ and includes preview tests. Generates a report of the results in the default ./test-results folder.

EXAMPLE 5

Section titled “EXAMPLE 5”
Invoke-Maester -OutputFolder './my-test-results'

Runs tests and generates a report of the results in the ./my-test-results folder.

EXAMPLE 6

Section titled “EXAMPLE 6”
Invoke-Maester -OutputHtmlFile './test-results/TestResults.html'

Runs the tests and generates a report of the results in the specified file.

EXAMPLE 7

Section titled “EXAMPLE 7”
Invoke-Maester -Path ./tests/EIDSCA

Runs tests in the EIDSCA folder.

EXAMPLE 8

Section titled “EXAMPLE 8”
Invoke-Maester -MailRecipient [email protected]

Runs the tests and sends a report of the results to an email recipient.

EXAMPLE 9

Section titled “EXAMPLE 9”
Invoke-Maester -TeamId '00000000-0000-0000-0000-000000000000' -TeamChannelId '19%3A00000000000000000000000000000000%40thread.tacv2'

Runs the tests and posts a summary of the results to a Teams channel.

EXAMPLE 10

Section titled “EXAMPLE 10”
Invoke-Maester -TeamChannelWebhookUri 'https://some-url.logic.azure.com/workflows/invoke?api-version=2016-06-01'

Runs the tests and posts a summary of the results to a Teams channel.

EXAMPLE 11

Section titled “EXAMPLE 11”
Invoke-Maester -Verbosity Normal

Shows results of tests as they are run, including details on failed tests.

EXAMPLE 12

Section titled “EXAMPLE 12”
$configuration = New-PesterConfiguration
$configuration.Run.Path = './tests/Maester'
$configuration.Filter.Tag = 'CA'
$configuration.Filter.ExcludeTag = 'App'


Invoke-Maester -PesterConfiguration $configuration

Runs Pester tests in the ./tests/Maester folder that include the ‘CA’ tag and exclude the ‘App’ tag.

EXAMPLE 13

Section titled “EXAMPLE 13”
Connect-Maester -Service All
Invoke-Maester -IncludeLongRunning -IncludePreview

Connect to all Microsoft 365 services and run their tests, including the long-running and preview tests. Active Directory tests remain excluded.

EXAMPLE 14

Section titled “EXAMPLE 14”
Connect-Maester -Service ActiveDirectory
Invoke-Maester -Tag 'AD' -SkipGraphConnect

Explicitly connect to Active Directory, then run the Active Directory tests without requiring a Microsoft Graph connection.

PARAMETERS

Section titled “PARAMETERS”

-Path

Section titled “-Path”

Specifies path to files containing tests. The value is a path\file name or a name pattern. Wildcards are permitted.

Type: String
Parameter Sets: (All)
Aliases:


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

-Tag

Section titled “-Tag”

Only run the tests that match this tag(s).

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


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

-ExcludeTag

Section titled “-ExcludeTag”

Exclude the tests that match this tag(s).

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


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

-IncludeLongRunning

Section titled “-IncludeLongRunning”

Include tests that can take a long time to run in tenants with a large number of objects.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-IncludePreview

Section titled “-IncludePreview”

Include tests that are still being tested or are dependent on preview APIs.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-OutputHtmlFile

Section titled “-OutputHtmlFile”

The path to the file to save the test results in html format. The filename should include an .html extension.

Type: String
Parameter Sets: (All)
Aliases:


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

-IncludeAffectedObjects

Section titled “-IncludeAffectedObjects”

Collect the affected objects: the consolidated list of objects the run touched. Adds the AffectedObjects property to the results, the Affected objects page to the html report and, with -OutputFolder, the <name>-affected-objects.json file (plus -affected-objects.csv with -ExportCsv). Off by default because it enlarges the report; it is enabled automatically when -RedactUserIdentity is used, since redaction is driven by the inventory.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-RedactUserIdentity

Section titled “-RedactUserIdentity”

Replaces user identities (display names, user principal names and object ids) with stable stable ids in the generated outputs. None (default): no redaction. AllOutputs: redact every generated output (html, json, markdown, csv, Excel, affected objects json and csv). HtmlOnly: redact the html report only, so the machine readable exports keep the real identifiers for follow up while the shareable report does not.

Type: String
Parameter Sets: (All)
Aliases:


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

-OutputMarkdownFile

Section titled “-OutputMarkdownFile”

The path to the file to save the test results in markdown format. The filename should include a .md extension.

Type: String
Parameter Sets: (All)
Aliases:


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

-OutputMarkdownSummaryFile

Section titled “-OutputMarkdownSummaryFile”

The path to the file to save a compact markdown summary with only result counters. The filename should include a .md extension.

Type: String
Parameter Sets: (All)
Aliases:


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

-OutputJsonFile

Section titled “-OutputJsonFile”

The path to the file to save the test results in json format. The filename should include a .json extension.

Type: String
Parameter Sets: (All)
Aliases:


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

-OutputFolder

Section titled “-OutputFolder”

The folder to save the test results in. If no -Output* is set, defaults to ./test-results. If set, other -Output* parameters are ignored and all formats will be generated (markdown, markdown summary, html, json) with a timestamp and saved in the folder.

Type: String
Parameter Sets: (All)
Aliases:


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

-OutputFolderFileName

Section titled “-OutputFolderFileName”

The filename prefix to use for all the files in the output folder. e.g. ‘TestResults’ will generate TestResults.html, TestResults.md, TestResults.json.

Type: String
Parameter Sets: (All)
Aliases:


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

-PesterConfiguration

Section titled “-PesterConfiguration”

An optional [PesterConfiguration] object for advanced configuration. Default is New-PesterConfiguration For help on each option see New-PesterConfiguration, or inspect the object it returns. See Pester Configuration for more information.

Type: PesterConfiguration
Parameter Sets: (All)
Aliases:


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

-Verbosity

Section titled “-Verbosity”

Set the Pester verbosity level. Default is ‘None’. None : Shows only the final summary. Normal : Focus on successful containers and failed tests/blocks. Shows basic discovery information and the summary of all tests. Detailed : Similar to Normal, but this level shows all blocks and tests, including successful. Diagnostic: Very verbose, but useful when troubleshooting tests. This level behaves like Detailed, but also enables debug messages.

Type: String
Parameter Sets: (All)
Aliases:


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

-NonInteractive

Section titled “-NonInteractive”

This will suppress the logo when Maester starts, prevent the test results from being opened in the default browser, and suppress all pretty messages.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-PassThru

Section titled “-PassThru”

Passes the output of the Maester tests to the console.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-MailRecipient

Section titled “-MailRecipient”

Optional: The email addresses of the report recipients. e.g. [email protected] No email will be sent if this parameter is not provided.

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


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

-MailTestResultsUri

Section titled “-MailTestResultsUri”

If sending the report to an email recipient, provide an absolute HTTP or HTTPS Uri to the detailed test results page.

Type: String
Parameter Sets: (All)
Aliases:


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

-MailUserId

Section titled “-MailUserId”

The user id of the sender of the mail. Defaults to the current user. This is required when using application permissions.

Type: String
Parameter Sets: (All)
Aliases:


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

-TeamId

Section titled “-TeamId”

Optional: The Teams team where the test results should be posted. To get the TeamId, right-click on the channel in Teams and select ‘Get link to channel’. Use the value of groupId. e.g. ?groupId=<TeamId>

Type: String
Parameter Sets: (All)
Aliases:


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

-TeamChannelId

Section titled “-TeamChannelId”

Optional: The channel where the results message should be posted. e.g. 19%3A00000000000000000000000000000000%40thread.tacv2 To get the TeamChannelId, right-click on the channel in Teams and select ‘Get link to channel’. Use the value found between channel and the channel name. e.g. /channel/<TeamChannelId>/my%20channel

Type: String
Parameter Sets: (All)
Aliases:


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

-TeamChannelWebhookUri

Section titled “-TeamChannelWebhookUri”

Optional: The webhook Uri where the results message should be posted. e.g. https://some-url/?value=123 To get the Webhook Uri, right-click on the channel in Teams and select ‘Workflow’. Create a workflow using the ‘Post to a channel when a webhook request is received’ template. Use the value after ‘complete.’

Type: String
Parameter Sets: (All)
Aliases:


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

-SkipGraphConnect

Section titled “-SkipGraphConnect”

Skip the graph connection check. This is used for running tests that does not require a Graph connection.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-DisableTelemetry

Section titled “-DisableTelemetry”

Disable Telemetry If set, telemetry information will not be logged.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-SkipVersionCheck

Section titled “-SkipVersionCheck”

Skip the version check. If set, the version check will not be performed.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-ExportCsv

Section titled “-ExportCsv”

Export the results to a CSV file.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-ExportExcel

Section titled “-ExportExcel”

Export the results to an Excel file.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
Section titled “-NoLogo”

Do not show the Maester logo.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:


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

-DriftRoot

Section titled “-DriftRoot”

The root directory for configuration drift tracking.

Type: String
Parameter Sets: (All)
Aliases:


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

-ProgressAction

Section titled “-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

Section titled “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

Section titled “INPUTS”

OUTPUTS

Section titled “OUTPUTS”

NOTES

Section titled “NOTES”
Section titled “RELATED LINKS”

https://maester.dev/docs/commands/Invoke-Maester

Maester is free and open source under the MIT licence.SponsorContributorsDiscordMaester Cloud