# Write-MtTestProgress

Shows where a long-running test is (its stage, the items done, what it is working on and its errors) in the

Source: https://maester.dev/docs/commands/Write-MtTestProgress

## SYNOPSIS

Shows where a long-running test is (its stage, the items done, what it is working on and its errors) in the
Maester console.

## SYNTAX

### Progress (Default)

```powershell
Write-MtTestProgress [-Stage <String>] [-StageNumber <Int32>] [-StageCount <Int32>] [-Completed <Int32>]
 [-Total <Int32>] [-Failed <Int32>] [-Running <Int32>] [-Current <String[]>] [-Status <String>]
 [-Stages <String[]>] [-Items <Object[]>] [-Results <Object>] [-Groups <Object[]>] [-GroupLabel <String>]
 [-ErrorMessage <String[]>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
```

### Clear

```powershell
Write-MtTestProgress [-Clear] [-ProgressAction <ActionPreference>] [<CommonParameters>]
```

## DESCRIPTION

For a test, or the instance source of a family, that runs a tool for a long time and knows how far the tool
has got: the stage it is in, how many of the items of that stage are done, which items it is working on and
the errors it reported.
Write-MtTestOutput shows the tool's log; this shows the progress that the log is
hard to read it from.

In the full-screen dashboard of an interactive run, the progress is a header at the top of the box that
Write-MtTestOutput opens: the stage, a bar of the items done with the counts, what the work is on now, and
the newest two errors.
Each call replaces the progress of the call before, so pass every part you know
each time.
A call with only -ErrorMessage adds the errors and keeps the progress.

Otherwise (the compact layout, CI and redirected output) a line is written to the host when the stage
changes, each error as it comes, and the counts at most every ten seconds.

A tool that runs in another process, in any language, can report its progress without calling this
command: a line it writes that Write-MtTestOutput is given, of the form

    ##maester[progress] \{"stage":"Exporting data","stageNumber":1,"stageCount":3,"completed":12,"total":40\}
    ##maester[error] The export of Users failed: Forbidden

is passed to this command instead of being shown in the log.
The JSON object takes the names of the
parameters of this command (any case); the parts it leaves out are empty.

Maester removes the progress when the test or the instance source finishes, with the box.

## EXAMPLES

### EXAMPLE 1

```powershell
Write-MtTestProgress -Stage 'Exporting tenant data' -StageNumber 1 -StageCount 3 -Completed 12 -Total 40 -Running 2 -Current 'Users', 'Groups'
```

Shows that the work is in the first of three stages, with 12 of its 40 items done and two running.

### EXAMPLE 2

```powershell
Write-MtTestProgress -Stage 'Running tests' -Results @{ Passed = 80; Failed = 12; Total = 300; Running = 4 } -GroupLabel 'Pillars' -Groups @{ Name = 'Identity'; Passed = 50; Failed = 8; Total = 120 }, @{ Name = 'Devices'; Passed = 30; Failed = 4; Total = 90 }
```

Shows the results of the tool's own tests in the dashboard's Results panel and result blocks, and its
pillars where the products are listed.

Each item that finishes with a time (in -Items, in any stage) is also kept: while the box is open the Pace
graph next to the logo draws how long each took, and the Slowest panel lists the slowest.

### EXAMPLE 3

```powershell
Write-MtTestProgress -ErrorMessage 'The export of Devices failed: Forbidden'
```

Adds an error to the box, keeping the progress.

### EXAMPLE 4

```powershell
&1 | Write-MtTestOutput -Title 'Collecting the tenant data'
```

The script writes lines such as '##maester[progress] \{"stage":"Exporting","completed":3,"total":9\}' to
standard output; they set the progress, and its other lines are shown in the box.

## PARAMETERS

### -Stage

The name of the stage the work is in, such as "Exporting tenant data".

```yaml
Type: String
Parameter Sets: Progress
Aliases:

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

### -StageNumber

The number of the stage, from 1.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -StageCount

How many stages there are.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -Completed

The items of the stage that are done and did not fail.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -Total

The items of the stage.
With a total the header shows a bar of the items done (completed and failed), the
percentage, and the time left once there is something to go on.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -Failed

The items of the stage that failed.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -Running

The items of the stage that are running now.

```yaml
Type: Int32
Parameter Sets: Progress
Aliases:

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

### -Current

What the work is on now, such as the names of the items running.

```yaml
Type: String[]
Parameter Sets: Progress
Aliases:

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

### -Status

A line of status that fits no other part, such as "Waiting for the throttling limit".

```yaml
Type: String
Parameter Sets: Progress
Aliases:

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

### -Stages

The names of all the stages, in order.
The header draws them as a track, like the phases of a Maester run:
the stages before -StageNumber done, that one running, the others to come.

```yaml
Type: String[]
Parameter Sets: Progress
Aliases:

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

### -Items

The items running and the ones that finished last (such as the exports or tests of a tool), shown the way
the dashboard shows Maester's own tests: the ones running with a spinner and the time they have run, the
ones that finished with their result and how long they took.
Each is a hashtable or object with Id, and
optionally Title, Status (Running, Passed, Failed, TimedOut or Skipped; Running when left out), Detail
(what it is doing, or why it failed) and Seconds.
Outside the dashboard each item that finished is written
once, with its result and time.

```yaml
Type: Object[]
Parameter Sets: Progress
Aliases:

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

### -Results

The results of the work so far, when it is a tool that runs tests of its own: a hashtable or object with
Passed, Failed, Error, Investigate, Skipped, Running and Total, and optionally Name.
While the box is open the
dashboard shows them in place of Maester's own: in its Results panel, under Name (or the title of the box),
and, before Maester's tests start, as a block for each item over the box.

```yaml
Type: Object
Parameter Sets: Progress
Aliases:

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

### -Groups

The results by group, such as the pillars of an assessment: each a hashtable or object with Name and the
counts of -Results.
While the box is open the dashboard lists them where it lists the products, with a bar
and the counts of each.

```yaml
Type: Object[]
Parameter Sets: Progress
Aliases:

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

### -GroupLabel

What the groups are called, such as "Pillars": the title of the box that lists them.

```yaml
Type: String
Parameter Sets: Progress
Aliases:

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

### -ErrorMessage

Errors the work reported.
They are listed under the progress, newest last, and counted on the box.

```yaml
Type: String[]
Parameter Sets: Progress
Aliases:

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

### -Clear

Removes the progress and the errors from the box.

```yaml
Type: SwitchParameter
Parameter Sets: Clear
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.

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

## NOTES

## RELATED LINKS

[https://maester.dev/docs/commands/Write-MtTestProgress](https://maester.dev/docs/commands/Write-MtTestProgress)