Invoke-Maester
SYNOPSIS
This is the main Maester command that runs the tests and generates a report of the results.
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 <Object>]
[-Verbosity <String>] [-NonInteractive] [-PassThru] [-MailRecipient <String[]>] [-MailTestResultsUri <String>]
[-MailUserId <String>] [-TeamId <String>] [-TeamChannelId <String>] [-TeamChannelWebhookUri <String>]
[-SkipGraphConnect] [-DisableTelemetry] [-SkipVersionCheck] [-ExportCsv] [-ExportExcel] [-NoLogo]
[-DriftRoot <String>] [-TestId <String[]>] [-ExcludeTestId <String[]>] [-Config <Object>] [-DryRun]
[-SkipBuiltIn] [-ProgressAction <ActionPreference>] [<CommonParameters>]
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
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
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
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
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
Invoke-Maester -OutputFolder './my-test-results'
Runs tests and generates a report of the results in the ./my-test-results folder.
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
Invoke-Maester -Path ./tests/EIDSCA
Runs tests in the EIDSCA folder.
EXAMPLE 8
Invoke-Maester -MailRecipient john@contoso.com
Runs the tests and sends a report of the results to an email recipient.
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
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
Invoke-Maester -Verbosity Normal
Shows results of tests as they are run, including details on failed tests.
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
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
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.
EXAMPLE 15
Invoke-Maester -TestId 'MT.1005', 'CISA.MS.AAD.3.*'
Runs only test MT.1005 and the tests whose ID starts with CISA.MS.AAD.3. A test named by its exact ID runs even if it is a preview or long-running test.
EXAMPLE 16
Invoke-Maester -ExcludeTestId 'MT.1024.*' -DryRun -PassThru
Shows what would run, and why every other test would not, without running any test. Each test that would have run is reported as NotRun with reason DryRun. Native tests are only read; Pester-format custom tests still go through Pester discovery, which runs their BeforeDiscovery and Describe-level code.
EXAMPLE 17
Invoke-Maester -Config ./maester-config.json, @{ Selection = @{ DefaultAction = 'Skip' }; TestSettings = @(@{ Id = 'MT.1005'; Enabled = $true }) }
Runs with an explicit configuration instead of the config files found next to the tests. Several sources are merged left to right; here only tests enabled in TestSettings are run.
PARAMETERS
-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
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
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
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
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
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
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
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
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
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
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
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
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
An optional Pester configuration for Pester-format custom tests: a [PesterConfiguration] object or a hashtable. Its Run.Path, Filter.Tag, Filter.ExcludeTag and TestResult options also apply to native tests. Pester is needed only when the run has Pester-format tests. See Pester Configuration for more information.
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-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
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
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
Optional: The email addresses of the report recipients. e.g. john@contoso.com 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
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
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
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
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
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
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
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
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
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
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
-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
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
-TestId
Only run the tests with these IDs. Exact IDs or '*' wildcards, case-insensitive. A test named by its exact ID runs even if it is a preview or long-running test.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ExcludeTestId
Do not run the tests with these IDs. Exact IDs or '*' wildcards, case-insensitive. Wins over -TestId.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Config
The run configuration: a path to a maester-config.json file, a config object (hashtable or PSCustomObject), or an array of paths and objects merged left to right. When set, config files next to the tests are not read. Defaults to the MAESTER_CONFIG environment variable, then to the config files found from -Path.
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-DryRun
Work out which tests would run, and why the others would not, without running any test. Each test that would have run is reported as NotRun with reason DryRun. Pester-format custom tests still go through Pester discovery, which runs their BeforeDiscovery and Describe-level code.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SkipBuiltIn
Run only the custom tests under -Path. The tests that ship with Maester always run otherwise.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
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.