# Convert-MtTest

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

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

## SYNOPSIS

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

## SYNTAX

```powershell
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
  '&lt;value&gt; | Should -Be $true' rewritten to 'return &lt;value&gt;'.
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:&lt;value&gt; 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

```powershell
Convert-MtTest -Path ./Custom -WhatIf
```

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

### EXAMPLE 2

```powershell
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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](http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

## OUTPUTS

### System.Management.Automation.PSObject

## NOTES

## RELATED LINKS

[https://maester.dev/docs/commands/Convert-MtTest](https://maester.dev/docs/commands/Convert-MtTest)