function Invoke-MtTest { <# .SYNOPSIS Runs one or more Maester native tests through the engine and returns their result rows. .DESCRIPTION Runs built-in tests by ID, or the native tests (Test..ps1) in a file or folder, with the same applicability gates, parameter binding and result rows as Invoke-Maester, but without reports. This is how a custom test reuses a built-in check (instead of calling its function directly), and how a test author runs the test they are writing. .PARAMETER Id Test IDs to run: exact IDs or '*' wildcards. A family's instance ID runs that instance. .PARAMETER Path A Test..ps1 file or a folder of them. Without -Id every native test in it runs. A path inside a Maester Pack (a folder with maester-pack.json, or under one) runs as that pack, with its helpers and connectors, as while writing the pack. .PARAMETER Parameter Parameter values for the test. Allowed only when exactly one test is selected. .PARAMETER Config The run configuration: a path, an object or an array of them, as for Invoke-Maester. Defaults to the configuration of the current Invoke-Maester run, else the config files found from -Path or the current folder. .EXAMPLE Invoke-MtTest -Id MT.1005 Runs the built-in test MT.1005 and returns its result row. .EXAMPLE Invoke-MtTest -Path ./custom/Test.CONTOSO.1001.ps1 -Parameter @{ MaximumDays = 30 } Runs a custom test with a parameter value, as while writing it. .EXAMPLE Invoke-MtTest -Path ./my-pack Runs every test of a Maester Pack from its folder, as while writing the pack. .LINK https://maester.dev/docs/commands/Invoke-MtTest #> [CmdletBinding()] [OutputType([pscustomobject])] param( [Parameter(Position = 0)] [string[]] $Id, [Parameter()] [string] $Path, [Parameter()] [hashtable] $Parameter, [Parameter()] [object] $Config ) if (-not $Id -and -not $Path) { Write-Error 'Specify the tests to run with -Id, -Path or both.' return } Write-Verbose "Invoke-MtTest: Id=$($Id -join ', ') Path=$Path" $tests = [System.Collections.Generic.List[object]]::new() if ($Path) { if (-not (Test-Path -LiteralPath $Path)) { Write-Error "The path '$Path' does not exist."; return } $root = if (Test-Path -LiteralPath $Path -PathType Container) { (Resolve-Path -LiteralPath $Path).Path } else { Split-Path (Resolve-Path -LiteralPath $Path).Path -Parent } # A path inside a Maester Pack runs as that pack, with its helpers and connectors (Maester Packs design, section 7). try { $developmentPack = Get-MtPackDevelopmentSet -Path $Path } catch { Write-Error $_.Exception.Message; return } if ($developmentPack) { $fullPath = (Resolve-Path -LiteralPath $Path).Path # A folder matches the files under it, never a sibling that starts with its name (tests vs tests-extra). $isFolder = Test-Path -LiteralPath $fullPath -PathType Container $prefix = $fullPath.TrimEnd([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar) + [System.IO.Path]::DirectorySeparatorChar $comparison = if ($IsWindows) { [System.StringComparison]::OrdinalIgnoreCase } else { [System.StringComparison]::Ordinal } foreach ($t in @(Get-MtPackTestInventory -PackSet @($developmentPack))) { if (-not $t.File) { continue } $inPath = if ($isFolder) { $t.File.StartsWith($prefix, $comparison) } else { [string]::Equals($t.File, $fullPath, $comparison) } if ($inPath) { $tests.Add($t) } } } else { foreach ($t in @(Get-MtNativeTestInventory -Path $Path -Root $root)) { $tests.Add($t) } } } if ($Id) { $pool = if ($Path) { @($tests) } else { @(Get-MtTestCatalog) } # The tests of packs run by ID too: MP., or the code of a pack that ships with Maester. $builtInCodes = @(Get-MtBuiltInPack | Where-Object { $_.Manifest -and $_.Manifest.Code } | ForEach-Object { [string]$_.Manifest.Code }) if (-not $Path -and ($Id | Where-Object { $i = $_; 'MP.' -like $i -or $i -like 'MP.*' -or ($builtInCodes | Where-Object { $_ -like $i -or $i -like "$_*" }) })) { $pool = @($pool) + @(Get-MtPackTestInventory -PackSet @(Initialize-MtPackSet) | Where-Object { -not $_.PackStatus }) } $selected = @($pool | Where-Object { $t = $_ (Test-MtIdMatch -Id $t.Id -Pattern $Id) -or ($t.InstanceSource -and ($Id | Where-Object { $_ -like "$($t.Id).*" })) }) $unknown = @($Id | Where-Object { $i = $_; -not ($selected | Where-Object { (Test-MtIdMatch -Id $_.Id -Pattern @($i)) -or ($_.InstanceSource -and $i -like "$($_.Id).*") }) }) if ($unknown.Count -gt 0) { Write-Error "No native test matches: $($unknown -join ', '). Use Get-MtTest to list the tests." if ($selected.Count -eq 0) { return } } $tests = [System.Collections.Generic.List[object]]::new() foreach ($t in $selected) { $tests.Add($t) } } if ($tests.Count -eq 0) { Write-Error 'No native tests to run.'; return } if ($Parameter -and $tests.Count -ne 1) { Write-Error "-Parameter can be used only when exactly one test is selected; $($tests.Count) are."; return } # Called by a test during an Invoke-Maester run, the run's config is kept; otherwise it is resolved for # this call (the config a finished run leaves in the session must not apply to a later standalone call). $savedConfig = $__MtSession.MaesterConfig $insideRun = $null -ne $savedConfig -and -not [string]::IsNullOrEmpty([Maester.Engine.MtSession]::GetCurrentTest()) $ownsConfig = -not $insideRun -or $null -ne $Config try { if ($ownsConfig) { $searchPath = if ($Path) { $(if (Test-Path -LiteralPath $Path -PathType Container) { $Path } else { Split-Path $Path -Parent }) } else { (Get-Location).Path } $__MtSession.MaesterConfig = Resolve-MtRunConfig -Path $searchPath -Config $Config -WarningAction SilentlyContinue } $runConfig = $__MtSession.MaesterConfig $selection = Resolve-MtSelection -RunConfig $runConfig -TestId @($tests | ForEach-Object { $_.Id }) # The caller named the tests: the allow-list and the selectors of the config do not apply. $selection.DefaultAction = 'Run' foreach ($selector in 'Product', 'Feature', 'Area', 'Severity', 'Suite') { $selection.$selector = [string[]]@() } # Instance IDs given with -Id select those instances only. if ($Id) { $selection.TestId = @(@($tests | ForEach-Object { $_.Id }) | Where-Object { $tid = $_; $Id | Where-Object { $tid -like $_ } }) + @($Id | Where-Object { $i = $_; $tests | Where-Object { $_.InstanceSource -and $i -like "$($_.Id).*" } }) } $services = @($tests | ForEach-Object { $_.Service } | Where-Object { $_ } | Select-Object -Unique) $context = Get-MtTenantContext -Service $(if ($services) { $services } else { @('Graph') }) -Environment $(if ($runConfig.PSObject.Properties['Environment']) { $runConfig.Environment } else { $null }) $override = @{} if ($Parameter) { $override[$tests[0].Id] = $Parameter } $plan = @(Resolve-MtNativePlan -Test @($tests) -Selection $selection -RunConfig $runConfig -TenantContext $context -ParameterOverride $override) Invoke-MtNativePlan -Plan $plan -RunConfig $runConfig -Selection $selection } finally { if ($ownsConfig) { $__MtSession.MaesterConfig = $savedConfig } } }