Public/Get-VesterTest.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
function Get-VesterTest {
    <#
    .SYNOPSIS
    Gather Vester test filepaths and details of each test.
 
    .DESCRIPTION
    Get-VesterTest looks for .Vester.ps1 files, excludes some if the -Scope
    or -Name parameters were specified, and then inspects each test file.
    File path and detailed properties about each test are returned.
 
    By default, all tests included with the module are inspected, and only
    three properties are displayed: Name, Scope, and Description.
 
    "Get-Help Get-VesterTest -Examples" for more details.
 
    .EXAMPLE
    Get-VesterTest -Verbose
    Displays the Name, Scope, and Description of all Vester test files
    packaged with the module.
    Verbose messages are available, if extra info is desired.
 
    .EXAMPLE
    Get-VesterTest | Select-Object -First 1 | Format-List *
    Returns the first Vester test found from the module.
    "Format-List *" displays all properties, instead of the default three.
 
    .EXAMPLE
    Get-VesterTest -Scope Cluster,vCenter
    Returns all Vester tests that apply to the "Cluster" and "vCenter" scopes.
 
    .EXAMPLE
    Get-VesterTest -Name 'CPU-Limits','ntp*'
    Returns tests named "CPU-Limits" and tests starting with "NTP".
    -Name is case insensitive.
 
    .EXAMPLE
    Get-VesterTest -Path C:\Vester\CustomTest.Vester.ps1
    -Path can be used to retrieve tests outside of the Vester module install.
    Here, it collects info from CustomTest to return.
 
    .EXAMPLE
    Get-VesterTest -Path C:\Vester\
    -Path can also be pointed at a directory containing custom tests.
    Get-VesterTest will search here for all .Vester.ps1 files, recursively.
     
    (Note that the immediate parent folder of all test files should have a
    name matching the test's intended scope, like "VM".)
 
    .EXAMPLE
    Get-VesterTest -Scope VM -Simple
    Returns only the file path of each test, instead of rich object details.
    Invoke-Vester currently expects paths only, so this saves a little time
    when supplying a filtered test suite to Invoke-Vester.
 
    .INPUTS
    [System.Object]
    Accepts piped input(s) for parameter -Path.
 
    .OUTPUTS
    [PSCustomObject] / [Vester.Test]
    PSCustomObjects (with custom typename "Vester.Test") are returned.
 
    [System.String]
    If -Simple is active, only strings with each file's full path are returned.
 
    .NOTES
    "Get-Help about_Vester" for more information.
 
    .LINK
    https://wahlnetwork.github.io/Vester
 
    .LINK
    https://github.com/WahlNetwork/Vester
    #>

    [CmdletBinding()]
    param (
        # The file/folder path(s) to retrieve test info from.
        # If a directory, child .Vester.ps1 files are gathered recursively.
        [Parameter(ValueFromPipeline = $true)]
        [ValidateScript({
            If ($_.FullName) {Test-Path $_.FullName}
            Else {Test-Path $_}
        })]
        [object[]]$Path = "$(Split-Path -Parent $PSScriptRoot)\Tests\",

        # Return only test files belonging to the specified Vester scope(s).
        # Vester determines test file scope by the name of its parent directory.
        [ValidateSet('Cluster','DSCluster','Host','Network','vCenter','VM')]
        [string[]]$Scope = @('Cluster','DSCluster','Host','Network','vCenter','VM'),

        # Filter results by test name (e.g. "DRS-Enabled" or "*DRS*").
        # -Name parameter is not case sensitive.
        [string[]]$Name,

        # Simply return the full path of the file, instead of a rich object
        # Faster, as it does not inspect the contents of each Vester test file
        [switch]$Simple
    )

    BEGIN {
        Write-Verbose '[Get-VesterTest] Function called'

        # Using $PSBoundParameters to set variable $Get
        If (-not $PSBoundParameters.ContainsKey('Path')) {
            Write-Verbose "-Path not specified; searching default module path"
            $PSBoundParameters.Add('Path', $Path)
        }
        If (-not $PSBoundParameters.ContainsKey('Scope')) {
            Write-Verbose "-Scope not specified; including all scopes"
            $PSBoundParameters.Add('Scope', $Scope)
        }

        # Construct empty array to throw file paths of tests into
        $TestFiles = New-Object 'System.Collections.Generic.List[PSCustomObject]'
    }

    PROCESS {
        # Need to ForEach if multiple -Test locations
        ForEach ($TestPath in $Path) {
            # Gracefully handle FileSystemInfo objects (Get-Item / Get-ChildItem)
            If ($TestPath.FullName) {
                $TestPath = $TestPath.FullName
            }

            If (Test-Path $TestPath -PathType Container) {
                # If Test-Path finds a folder, get all *.Vester.ps1 files beneath it
                Write-Verbose "Discovering .Vester.ps1 files below directory '$TestPath'"
                # Leverage PSBoundParameters and splatting to pass only needed parameters
                $Get = Get-VesterChildItem @PSBoundParameters

                If ($Get) {
                    Write-Verbose "Discovered $($Get.Count) Vester test files"

                    If ($Simple) {
                        # Keep only the full file path
                        $Get.FullName | ForEach-Object {
                            $TestFiles.Add($_)
                        }
                    } Else {
                        # Extract details of each test file

                        $Get | ForEach-Object {
                            Write-Verbose "Processing Vester test file $($_.Name)"
                            $Vest = Extract-VestDetails -Object $_

                            # Add each *.Vester.ps1 file found to the array
                            $TestFiles.Add($Vest)
                        } #ForEach Get
                    }
                } Else {
                    throw "No *.Vester.ps1 files found at location '$TestPath'"
                } #If Get

                $Get = $null
            } ElseIf ($TestPath -like '*.Vester.ps1') {
                If ($Simple) {
                    # Keep only the full file path
                    $TestFiles.Add($Vest)
                } Else {
                    # Extract details of the file
                    Write-Verbose "Processing Vester test file $TestPath"

                    $Get = Get-VesterChildItem -Path $TestPath
                    $Vest = Extract-VestDetails -Object $_
                    $TestFiles.Add($Vest)
                    $Get = $null
                }
            } Else {
                # Because Vester tests have a very specific format,
                # and for future discoverability of that test if parent folder is specified,
                # prefer that tests are consciously named *.Vester.ps1
                throw "'$TestPath' does not match the *.Vester.ps1 naming convention for test files."
            } #If Test-Path
        } #ForEach -Test param entry
    } #process

    END {
        If (-not $Simple) {
            # Reduce default property set for readability
            $TypeData = @{
                TypeName = 'Vester.Test'
                DefaultDisplayPropertySet = 'Name','Scope','Description'
            }
            # Include -Force to avoid errors after the first run
            Update-TypeData @TypeData -Force
        }

        $TestFiles
    } #end
} #function