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[]>] [-Product <String[]>]
[-Feature <String[]>] [-Area <String[]>] [-Severity <String[]>] [-Suite <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]
[-OutputMode <String>] [-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 the tests that ship with Maester and the custom tests in the Custom folder of the current directory, except Active Directory tests, preview tests and long-running tests. With -Path, native custom tests (Test..ps1) are found anywhere under the path and Pester-format custom tests (.Tests.ps1) only in a Custom folder. Folders are searched up to three levels deep. Active Directory tests run only after an explicit Connect-Maester -Service ActiveDirectory call succeeds.
-Product, -Feature, -Area, -Severity and -Suite select tests by their typed attributes. Each takes a list: the values of one selector are alternatives, and different selectors must all match. They combine the same way with -Tag and -TestId. The tags of Maester 2.x, such as CA or CIS, still select the same built-in tests.
EXAMPLES
EXAMPLE 1
Invoke-Maester
Runs the built-in tests and the custom tests in the ./Custom folder (except for Active Directory tests, preview tests and long-running tests) and generates a report of the results in the ./test-results folder.
EXAMPLE 2
Invoke-Maester ./maester
Runs the built-in tests and the custom tests and maester-config.json in the folder ./maester (except for Active Directory tests, preview tests and long-running tests) 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 -Product entra -Severity Critical, High
Runs the Entra ID tests whose severity is Critical or High. Values of one selector are alternatives; different selectors must all match.
EXAMPLE 6
Invoke-Maester -Suite cisa -Area authentication
Runs the tests of the CISA suite that are about authentication. -Product, -Feature, -Area, -Severity and -Suite select by the typed attributes of the tests and combine with -Tag and -TestId.
EXAMPLE 7
Invoke-Maester -OutputFolder './my-test-results'
Runs tests and generates a report of the results in the ./my-test-results folder.
EXAMPLE 8
Invoke-Maester -OutputHtmlFile './test-results/TestResults.html'
Runs the tests and generates a report of the results in the specified file.
EXAMPLE 9
Invoke-Maester -Path ./maester/Custom -SkipBuiltIn
Runs only the custom tests in the ./maester/Custom folder.
EXAMPLE 10
Invoke-Maester -MailRecipient john@contoso.com
Runs the tests and sends a report of the results to an email recipient.
EXAMPLE 11
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 12
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 13
Invoke-Maester -Verbosity Normal
Shows results of tests as they are run, including details on failed tests.
EXAMPLE 14
$configuration = New-PesterConfiguration
$configuration.Run.Path = './tests/Custom'
$configuration.Filter.Tag = 'CA'
$configuration.Filter.ExcludeTag = 'App'
Invoke-Maester -PesterConfiguration $configuration
Runs the built-in tests and the custom tests in the ./tests/Custom folder that include the 'CA' tag and exclude the 'App' tag.
EXAMPLE 15
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 16
Connect-Maester -Service ActiveDirectory
Invoke-Maester -Product ad -SkipGraphConnect
Explicitly connect to Active Directory, then run the Active Directory tests without requiring a Microsoft Graph connection.
EXAMPLE 17
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 18
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 19
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
The folder that holds your custom tests and configuration, or the path of one test file. Native tests are found in any folder under it, Pester-format tests only in a Custom folder, up to three folder levels deep. Without -Path, the Custom folder of the current folder is used. Wildcards are not expanded.
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
-Product
Only run the tests of these products: keys such as entra or exchange, or an alias such as 'Entra ID'. Matches a test's Product or any of its RelatedProduct values. '*' wildcards are allowed.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Feature
Only run the tests about these features of a product, for example conditional-access. '*' wildcards are allowed.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Area
Only run the tests of these security areas, for example authentication or privileged-access. '*' wildcards are allowed.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Severity
Only run the tests with these severities: Critical, High, Medium, Low or Info. A severity set for a test in the run configuration is the one that counts.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Suite
Only run the tests of these suites, for example Maester, CISA, CIS, EIDSCA, ORCA or AD. '*' wildcards are allowed.
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. [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
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
-OutputMode
How the console output is written. Interactive draws a live status line with the result counts, a progress bar and the running test, on a terminal. Stream writes lines only, for CI and redirected output, with a progress line every 50 tests or 10 seconds and log groups and annotations on GitHub Actions and Azure Pipelines. Plain is Stream without colour or symbols. Auto, the default, picks Interactive on a terminal and Stream otherwise. The MAESTER_OUTPUT_MODE environment variable and Output.ConsoleMode in maester-config.json set it too.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: Auto
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.