Convert-MtTest

Synopsis

Converts custom Pester-format Maester tests to the native format (Test.<ID>.ps1 and Test.<ID>.md).

Syntax

Convert-MtTest [-Path] <String> [-OutputPath <String>] [-Force] [-ProgressAction <ActionPreference>] [-WhatIf]
 [-Confirm] [<CommonParameters>]

Description

Reads the *.Tests.ps1 files in a folder from their AST (no test code runs) and writes one native test per It block:

• An It whose body calls one function defined in a .ps1 file of the same folder and checks the result with a boolean Should (the documented split-file pattern) becomes a native test containing that function, with the [MaesterTest] attribute added. A leading Test-MtConnection guard becomes the Service property, and an outer try/catch that only reports -SkippedBecause Error is removed: the engine does both. When the It passes arguments, the function is kept as a private helper in the file and the test calls it with those arguments.
• An It with inline logic becomes a function whose body is the It body, with a trailing ‘<value> | Should -Be $true’ rewritten to ‘return <value>’. Other assertions, -ForEach and -TestCases data, BeforeDiscovery data and Set-ItResult are left in place with a TODO comment and listed in the report.

The It name gives the ID and title (an ID without a prefix such as CT0001 is kept; the report suggests a prefix). The Describe name becomes Feature, so the Block of the test’s result rows, and with it the name of its test case in CI, stays what it was. The tags are kept; a Severity:<value> tag also gives Severity, a Preview tag becomes Lifecycle = ‘Preview’ and a LongRunning tag the LongRunning flag. The Markdown comes from the function’s .md file, else from -Description in the code or the function’s help.

The original Pester files are not changed. Once a test is converted, Invoke-Maester runs the native test and does not run the Pester test with the same ID. Delete the Pester file when you are satisfied.

Examples

Example 1

Convert-MtTest -Path ./Custom -WhatIf

Shows which tests would be converted and what needs attention, without writing anything.

Example 2

Convert-MtTest -Path ./Custom | Format-Table Id, Status, Notes

Converts the custom tests and shows the report.

Parameters

-Path

The folder with the Pester-format custom tests. Subfolders are included.

Type: String
Parameter Sets: (All)
Aliases:

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

-OutputPath

The folder to write the native tests to. Defaults to -Path.

Type: String
Parameter Sets: (All)
Aliases:

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

-Force

Overwrites native test files that already exist.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: wi

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

-Confirm

Prompts you for confirmation before running the cmdlet.

Type: SwitchParameter
Parameter Sets: (All)
Aliases: cf

Required: False
Position: Named
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

System.Management.Automation.PSObject

Notes

Related links

https://maester.dev/docs/commands/Convert-MtTest