feat: enhance test scripts with detailed documentation and improve directory search function

Author: MariusStorhaug

.github/linters/.powershell-psscriptanalyzer.psd1

@@ -50,6 +50,7 @@
         }
     }
     ExcludeRules = @(
+        'PSAvoidUsingWriteHost',        # Write-Host is acceptable in GitHub Actions runners
         'PSMissingModuleManifestField', # This rule is not applicable until the module is built.
         'PSUseToExportFieldsInManifest'
     )

scripts/main.ps1

@@ -249,21 +249,36 @@ process {
                         return $testFiles
                     }
 
-                    function Find-TestDirectories {
-                        param ([string]$Path)
+                    <#
+                    .SYNOPSIS
+                        Recursively finds all test directories.
+
+                    .DESCRIPTION
+                        Recursively searches for all subdirectories within the specified path.
+
+                    .OUTPUTS
+                        System.String[]
+                        Returns an array of directory paths.
+                    #>
+                    function Find-TestDirectory {
+                        [CmdletBinding()]
+                        param(
+                            #The root path to search for test directories.
+                            [string]$Path
+                        )
 
                         $directories = @()
                         $childDirs = Get-ChildItem -Path $Path -Directory
 
                         foreach ($dir in $childDirs) {
                             $directories += $dir.FullName
-                            $directories += Find-TestDirectories -Path $dir.FullName
+                            $directories += Find-TestDirectory -Path $dir.FullName
                         }
 
                         return $directories
                     }
 
-                    $allTestFolders = @($testsPath) + (Find-TestDirectories -Path $testsPath)
+                    $allTestFolders = @($testsPath) + (Find-TestDirectory -Path $testsPath)
 
                     foreach ($folder in $allTestFolders) {
                         $testItems = Get-TestItemsFromFolder -FolderPath $folder

tests/Validate-Settings.ps1

@@ -51,9 +51,30 @@ Write-Host "`nComparing with reference settings..."
 $referencePath = Join-Path $PSScriptRoot 'Settings.json'
 $expectedSettings = Get-Content $referencePath -Raw | ConvertFrom-Json
 
-# Function to compare object structures
+<#
+.SYNOPSIS
+    Compares the structure of two objects.
+
+.DESCRIPTION
+    Recursively compares the structure of an actual object against an expected object,
+    validating that all expected properties exist in the actual object.
+
+.OUTPUTS
+    System.String[]
+    Returns an array of error messages for any structural mismatches.
+#>
 function Test-ObjectStructure {
-    param($Actual, $Expected, $Path = 'Root')
+    [CmdletBinding()]
+    param(
+        # The actual object to validate.
+        $Actual,
+
+        # The expected object structure to validate against.
+        $Expected,
+
+        # The current path in the object hierarchy (used for error reporting).
+        $Path = 'Root'
+    )
 
     $errors = @()