Write-MtTestOutput
SYNOPSIS
Shows the lines a long-running test writes while it works, live in the Maester console.
SYNTAX
Line (Default)
Write-MtTestOutput [[-InputObject] <Object>] [-Title <String>] [-Progress] [-ProgressAction <ActionPreference>]
[<CommonParameters>]
Complete
Write-MtTestOutput [-Complete] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
For a test, or the instance source of a family, that runs a tool for a long time (for example a command in another PowerShell process) and wants the person running Maester to see that tool's log as it runs.
While the full-screen dashboard of an interactive run has the screen, nothing else can write to the console. The lines go into a box in the main column of the dashboard, which scrolls as they come in. Otherwise (the compact layout, CI and redirected output) each line is written to the host as it comes, indented and dimmed, and a line of -Progress at most every ten seconds. The lines go to the host itself, not to the information stream: Write-Host in a test is kept and shown only when the test has finished.
The box opens with the first line, or with -Title, and closes with -Complete. Maester closes it when the test or the instance source finishes.
A line that starts with ##maester[progress] followed by a JSON object, or with ##maester[error] followed by text, is not shown as a line: it sets the progress at the top of the box, or adds an error to it, as Write-MtTestProgress does. A tool in another process, in any language, reports its progress that way by writing those lines to its output.
EXAMPLES
EXAMPLE 1
&1 | Write-MtTestOutput -Title 'Collecting the tenant data'
Write-MtTestOutput -Complete
Shows the output of a script that runs in another PowerShell process in the console while it runs.
EXAMPLE 2
'##maester[progress] {"stage":"Exporting","stageNumber":1,"stageCount":3,"completed":4,"total":9}' | Write-MtTestOutput
Sets the progress at the top of the box, as Write-MtTestProgress -Stage Exporting -StageNumber 1 -StageCount 3 -Completed 4 -Total 9 does.
PARAMETERS
-InputObject
A line to show. Line breaks start new lines. Escape sequences, emoji and other control characters are removed.
Type: Object
Parameter Sets: Line
Aliases:
Required: False
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False
-Title
The title of the box. A new title starts the box again, empty.
Type: String
Parameter Sets: Line
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Progress
The line is a status that changes (such as "Completed: 12 / 300"). In the dashboard it is pinned at the bottom of the box, under the lines that scroll, and the next line of progress replaces it.
Type: SwitchParameter
Parameter Sets: Line
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Complete
Closes the box.
Type: SwitchParameter
Parameter Sets: Complete
Aliases:
Required: True
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.