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[]>]
 [-ExcludeProduct <String[]>] [-Feature <String[]>] [-Area <String[]>] [-Severity <String[]>]
 [-Suite <String[]>] [-Pack <String[]>] [-AllPacks] [-IncludeLongRunning] [-IncludePreview]
 [-OutputHtmlFile <String>] [-IncludeAffectedObjects] [-ExcludeAffectedObjects] [-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] [-PackLock <String>] [-SkipPack]
 [-ProgressAction <ActionPreference>] [<CommonParameters>]

Description

Invoke-Maester runs the tests against the services you connected to with Connect-Maester and writes a report of the results.

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.

Invoke-Maester checks that Microsoft Graph is connected only when the run needs it: when a selected test declares the Graph service, when the run includes Pester-format tests (which do not declare their services), or when the results are sent by mail or to a Teams channel with -TeamId and -TeamChannelId. A run of tests that read nothing from Graph, such as Active Directory tests or a pack that reads a results file, needs no -SkipGraphConnect.

-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. -ExcludeProduct leaves out the tests of a product and wins over every selector. 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 tests that ship with Maester and the custom tests in the ./Custom folder, except Active Directory tests, preview tests and long-running tests. Writes the report to the ./test-results folder and opens it in the browser.

Example 2

Invoke-Maester -TestId MT.1005

Runs one test. A test named by its exact ID runs even if it is a preview or long-running test.

Example 3

Invoke-Maester -TestId 'MT.1005', 'CISA.MS.AAD.3.*'

Runs test MT.1005 and the tests whose ID starts with CISA.MS.AAD.3. IDs are not case-sensitive and ’*’ is a wildcard.

Example 4

Invoke-Maester -ExcludeTestId 'MT.1024.*', 'CIS.M365.1.1.1'

Runs everything a default run does, except the tests with these IDs. -ExcludeTestId wins over -TestId.

Example 5

Invoke-Maester -Product entra

Runs the Microsoft Entra tests: every test whose Product or RelatedProduct is entra.

Example 6

Invoke-Maester -Product entra, exchange -Severity Critical, High

Runs the Entra and Exchange Online tests whose severity is Critical or High. The values of one selector are alternatives; different selectors must all match.

Example 7

Invoke-Maester -ExcludeProduct exchange, teams

Runs everything a default run does, except the tests about Exchange Online and Teams. -ExcludeProduct wins over every selector. Pester-format custom tests have no product and still run.

Example 8

Invoke-Maester -Suite cisa -Area authentication

Runs the tests of the CISA suite that are about authentication.

Example 9

Invoke-Maester -Feature conditional-access

Runs the tests about one feature of a product, here Conditional Access.

Example 10

Invoke-Maester -IncludeLongRunning -IncludePreview

Adds the long-running tests and the preview tests to the run.

Example 11

Invoke-Maester -Product entra -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 12

Invoke-Maester ./maester

Runs the tests that ship with Maester and the custom tests in the ./maester folder, with the maester-config.json found there.

Example 13

Invoke-Maester -Path ./maester/Custom -SkipBuiltIn

Runs only the custom tests in the ./maester/Custom folder.

Example 14

Invoke-Maester -Pack ZTA

Runs the tests that ship with Maester and the Zero Trust Assessment pack, including its long-running test, even though the pack is off by default. Other installed packs do not run.

Example 15

Invoke-Maester -Pack ZTA -SkipBuiltIn

Runs only the Zero Trust Assessment pack.

Example 16

Invoke-Maester -AllPacks

Runs the tests that ship with Maester and every installed pack. Without -Pack or -AllPacks, installed packs do not run.

Example 17

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 18

Connect-Maester -Service ActiveDirectory
Invoke-Maester -Product ad

Explicitly connect to Active Directory, then run the Active Directory tests. They do not use Microsoft Graph, so no Graph connection is needed.

Example 19

Invoke-Maester -OutputFolder ./my-test-results

Runs the tests and writes the html, markdown and json reports to the ./my-test-results folder.

Example 20

Invoke-Maester -OutputHtmlFile ./test-results/TestResults.html

Runs the tests and writes only the html report, to the file named.

Example 21

Invoke-Maester -NonInteractive -OutputFolder ./test-results

Runs unattended, for a scheduled task or a pipeline: no logo, no dashboard, no run summary, and the report is not opened in the browser.

Example 22

Invoke-Maester -OutputMode Stream

Writes the console output as lines instead of the full-screen dashboard. This is what a pipeline or redirected output gets without asking; Plain also leaves out colour and symbols.

Example 23

Invoke-Maester -Verbosity Normal

Writes one line for each finished test, and keeps a two-line status at the bottom of the console instead of the dashboard.

Example 24

$results = Invoke-Maester -PassThru -NonInteractive

Returns the results as an object, for a script that goes on to read $results.FailedCount or $results.Tests.

Example 25

Invoke-Maester -MailRecipient [email protected]

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

Example 26

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 27

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 28

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

-ProductNew in 3.0Preview 3.0

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

-ExcludeProductNew in 3.0Preview 3.0

Do not run the tests of these products: keys such as entra or exchange, or an alias such as ‘exo’ or ‘Entra ID’. Matches a test’s Product or any of its RelatedProduct values, and ’*’ wildcards are allowed, as for -Product. Adds to Selection.ExcludeProduct in the run configuration and wins over -Product, -TestId and the other selectors. Excluded tests are reported as NotRun with the reason code ExcludedByProduct. A test without a product, such as a Pester-format custom test, is never excluded.

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

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

-FeatureNew in 3.0Preview 3.0

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

-AreaNew in 3.0Preview 3.0

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

-SeverityNew in 3.0Preview 3.0

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

-SuiteNew in 3.0Preview 3.0

Only run the tests of these suites, for example Maester, CISA, CIS, ASD, DISA, 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

-PackNew in 3.0Preview 3.0

Run these Maester Packs, by pack ID or code, for example ZTA or maester.zero-trust-assessment. ’*’ wildcards are allowed. An installed pack runs only when it is named here (or turned on with “Enabled”: true in the config), so installing a pack never adds its tests to every run. A pack named here runs even if it is off by default or in the config, and its long-running and preview tests run too. Other packs do not run; the other tests are not affected.

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

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

-AllPacksNew in 3.0Preview 3.0

Run every installed pack, as if each were named with -Pack, except those the config turns off.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
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 preview tests: new tests that are left out of a default run while they are tried out and feedback on them is gathered.

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

Affected objects are collected by default. The switch is kept so that older scripts still run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-ExcludeAffectedObjectsNew in 3.0Preview 3.0

Do not collect the affected objects: the consolidated list of objects the run touched. By default the results carry the AffectedObjects property, the html report has an Affected objects page when any test recorded an object and, with -OutputFolder, the <name>-affected-objects.json file is written (plus -affected-objects.csv with -ExportCsv). Use this switch to keep the report smaller. The objects are still collected when -RedactUserIdentity is used, since redaction is driven by them, but left out of the outputs.

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 Microsoft Graph connection check. Invoke-Maester checks the connection only when a selected test declares the Graph service, the run includes Pester-format tests, or the results are sent by mail or Teams. Use this switch when you connect to Graph yourself, or to run Pester-format tests that do not use Graph.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-DisableTelemetry

Do not send the run events to api.maester.dev: a random installation ID, a hash of the tenant ID, the versions and platform, when the run started and how long it took, its outcome, the result counts and the public packs installed and run. Setting the environment variable MAESTER_DISABLE_TELEMETRY to 1 does the same for every command.

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

-OutputModeNew in 3.0Preview 3.0

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

-TestIdNew in 3.0Preview 3.0

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

-ExcludeTestIdNew in 3.0Preview 3.0

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

-ConfigNew in 3.0Preview 3.0

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

-DryRunNew in 3.0Preview 3.0

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

-SkipBuiltInNew in 3.0Preview 3.0

Run only the custom tests under -Path. The tests that ship with Maester always run otherwise. The packs that ship with Maester are left out too, except those named in -Pack.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-PackLockNew in 3.0Preview 3.0

The pack lock file to run the installed packs from. Defaults to the MAESTER_PACK_LOCK environment variable, then to the maester-packs.lock.json beside the Maester config found from -Path.

Type: String
Parameter Sets: (All)
Aliases:

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

-SkipPackNew in 3.0Preview 3.0

Do not run any Maester Pack, installed or shipped with Maester.

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.