[ubuntu] Refactor test helpers (#8938)

* [ubuntu] Refactor test helpers

* [ubuntu] Adjust help comment

images/ubuntu/scripts/tests/Databases.Tests.ps1

@@ -11,7 +11,7 @@ Describe "MongoDB" -Skip:(Test-IsUbuntu22) {
 Describe "PostgreSQL" {
     It "PostgreSQL Service" {
         "sudo systemctl start postgresql" | Should -ReturnZeroExitCode
-        "pg_isready" | Should -MatchCommandOutput "/var/run/postgresql:5432 - accepting connections"
+        "pg_isready" | Should -OutputTextMatchingRegex "/var/run/postgresql:5432 - accepting connections"
         "sudo systemctl stop postgresql" | Should -ReturnZeroExitCode
     }
 

images/ubuntu/scripts/tests/Helpers.psm1

@@ -1,13 +1,32 @@
 Import-Module "$PSScriptRoot/../helpers/Common.Helpers.psm1" -DisableNameChecking
 
-# Validates that tool is installed and in PATH
-function Validate-ToolExist($tool) {
-    Get-Command $tool -ErrorAction SilentlyContinue | Should -BeTrue
-}
-
 function Invoke-PesterTests {
+    <#
+    .SYNOPSIS
+        Runs Pester tests based on the provided test file and test name.
+
+    .DESCRIPTION
+        The Invoke-PesterTests function runs Pester tests based on the provided test file and test name.
+
+    .PARAMETER TestFile
+        The name of the test file to run. This should be the base name of the test file without the extension.
+        Using "*" will run all tests from all test files.
+
+    .PARAMETER TestName
+        The name of the specific test to run. If provided, only the test with the matching name will be executed.
+
+    .EXAMPLE
+        Invoke-PesterTests -TestFile "MyTests" -TestName "Test1"
+        Runs the test named "Test1" from the test file "MyTests.Tests.ps1".
+
+    .EXAMPLE
+        Invoke-PesterTests -TestFile "*"
+        Runs all tests from all test files
+
+    #>
     Param(
-        [Parameter(Mandatory)][string] $TestFile,
+        [Parameter(Mandatory = $true)]
+        [string] $TestFile,
         [string] $TestName
     )
 
@@ -17,12 +36,12 @@ function Invoke-PesterTests {
     }
 
     # Check that Pester module is imported
-    if (!(Get-Module "Pester")) {
+    if (-not (Get-Module "Pester")) {
         Import-Module Pester
     }
 
     $configuration = [PesterConfiguration] @{
-        Run = @{ Path = $testPath; PassThru = $true }
+        Run    = @{ Path = $testPath; PassThru = $true }
         Output = @{ Verbosity = "Detailed"; RenderMode = "Plaintext" }
     }
     if ($TestName) {
@@ -43,6 +62,29 @@ function Invoke-PesterTests {
 }
 
 function ShouldReturnZeroExitCode {
+    <#
+    .SYNOPSIS
+        Implements a custom Should-operator for the Pester framework.
+
+    .DESCRIPTION
+        This function is used to check if a command has returned a zero exit code.
+        It can be used by registering it using the Add-ShouldOperator function in Pester.
+
+    .PARAMETER ActualValue
+        The actual value to be checked.
+
+    .PARAMETER Negate
+        A switch parameter that, when specified, negates the result of the check.
+
+    .PARAMETER Because
+        An optional string that provides additional context or explanation for the check.
+
+    .NOTES
+        This function is designed to be used with the Pester framework.
+
+    .LINK
+        https://pester.dev/docs/assertions/custom-assertions
+    #>
     Param(
         [string] $ActualValue,
         [switch] $Negate,
@@ -51,7 +93,7 @@ function ShouldReturnZeroExitCode {
 
     $result = Get-CommandResult $ActualValue -ValidateExitCode $false
 
-    [bool]$succeeded = $result.ExitCode -eq 0
+    [bool] $succeeded = $result.ExitCode -eq 0
     if ($Negate) { $succeeded = -not $succeeded }
 
     if (-not $succeeded)
@@ -67,7 +109,30 @@ function ShouldReturnZeroExitCode {
     }
 }
 
-function ShouldMatchCommandOutput {
+function ShouldOutputTextMatchingRegex {
+    <#
+    .SYNOPSIS
+        Implements a custom Should-operator for the Pester framework.
+
+    .DESCRIPTION
+        This function is used to check if a command outputs text that matches a regular expression.
+        It can be used by registering it using the Add-ShouldOperator function in Pester.
+
+    .PARAMETER ActualValue
+        The actual value to be checked.
+
+    .PARAMETER RegularExpression
+        The regular expression to be used for the check.
+
+    .PARAMETER Negate
+        A switch parameter that, when specified, negates the result of the check.
+
+    .NOTES
+        This function is designed to be used with the Pester framework.
+
+    .LINK
+        https://pester.dev/docs/assertions/custom-assertions
+    #>
     Param(
         [string] $ActualValue,
         [string] $RegularExpression,
@@ -77,9 +142,7 @@ function ShouldMatchCommandOutput {
     $output = (Get-CommandResult $ActualValue -ValidateExitCode $false).Output | Out-String
     [bool] $succeeded = $output -cmatch $RegularExpression
 
-    if ($Negate) {
-        $succeeded = -not $succeeded
-    }
+    if ($Negate) { $succeeded = -not $succeeded }
 
     $failureMessage = ''
 
@@ -100,5 +163,5 @@ function ShouldMatchCommandOutput {
 
 If (Get-Command -Name Add-ShouldOperator -ErrorAction SilentlyContinue) {
     Add-ShouldOperator -Name ReturnZeroExitCode -InternalName ShouldReturnZeroExitCode -Test ${function:ShouldReturnZeroExitCode}
-    Add-ShouldOperator -Name MatchCommandOutput -InternalName ShouldMatchCommandOutput -Test ${function:ShouldMatchCommandOutput}
+    Add-ShouldOperator -Name OutputTextMatchingRegex -InternalName ShouldOutputTextMatchingRegex -Test ${function:ShouldOutputTextMatchingRegex}
 }

images/ubuntu/scripts/tests/Java.Tests.ps1

@@ -45,6 +45,6 @@ Describe "Java" {
         if ($Version -eq 8) {
             $Version = "1.${Version}"
         }
-        "`"$javaPath`" -version" | Should -MatchCommandOutput "openjdk\ version\ `"${Version}(\.[0-9_\.]+)?`""
+        "`"$javaPath`" -version" | Should -OutputTextMatchingRegex "openjdk\ version\ `"${Version}(\.[0-9_\.]+)?`""
     }
 }

images/ubuntu/scripts/tests/Tools.Tests.ps1

@@ -281,7 +281,7 @@ Describe "Kubernetes tools" {
     }
 
     It "kubectl" {
-        "kubectl version --client=true" | Should -MatchCommandOutput "Client Version: v"
+        "kubectl version --client=true" | Should -OutputTextMatchingRegex "Client Version: v"
     }
 
     It "helm" {
@@ -341,7 +341,7 @@ Describe "Containers" {
 
     # https://github.com/actions/runner-images/issues/7753
     It "podman networking" -TestCases "podman CNI plugins" {
-        "podman network create -d bridge test-net && podman network ls" | Should -Not -MatchCommandOutput "Error"
+        "podman network create -d bridge test-net && podman network ls" | Should -Not -OutputTextMatchingRegex "Error"
     }
 
 }
@@ -382,7 +382,7 @@ Describe "Ruby" {
     if ($gemTestCases)
     {
         It "Gem <gemName> is installed" -TestCases $gemTestCases {
-            "gem list -i '^$gemName$'" | Should -MatchCommandOutput "true"
+            "gem list -i '^$gemName$'" | Should -OutputTextMatchingRegex "true"
         }
     }
 }