Enhance error messaging in test functions for better clarity and debugging.

Author: fdcastel

src/image.tests.ps1

@@ -62,7 +62,7 @@ function Test-Port([string]$ContainerName, [int]$Port) {
 
 # Asserts that InputValue contains at least one occurence of Pattern.
 #   If -ReturnMatchPosition is informed, return the match value for that pattern position.
-function Contains([Parameter(ValueFromPipeline)]$InputValue, [string[]]$Pattern, [int]$ReturnMatchPosition) {
+function Contains([Parameter(ValueFromPipeline)]$InputValue, [string[]]$Pattern, [int]$ReturnMatchPosition, [string]$ErrorMessage) {
     process {
         if ($hasMatch) { return; }
         $_matches = $InputValue | Select-String -Pattern $Pattern
@@ -74,37 +74,49 @@ function Contains([Parameter(ValueFromPipeline)]$InputValue, [string[]]$Pattern,
     }
 
     end {
-        assert $hasMatch
+        if ([string]::IsNullOrEmpty($ErrorMessage)) {
+            $ErrorMessage = "InputValue does not contain the specified Pattern."
+        }
+        assert $hasMatch $ErrorMessage
         return $result
     }
 }
 
 # Asserts that InputValue contains exactly ExpectedCount occurences of Pattern.
-function ContainsExactly([Parameter(ValueFromPipeline)]$InputValue, [string[]]$Pattern, [int]$ExpectedCount) {
+function ContainsExactly([Parameter(ValueFromPipeline)]$InputValue, [string[]]$Pattern, [int]$ExpectedCount, [string]$ErrorMessage) {
     process {
         $_matches = $InputValue | Select-String -Pattern $Pattern
         $totalMatches += $_matches.Count
     }
 
     end {
-        assert ($totalMatches -eq $ExpectedCount)
+        if ([string]::IsNullOrEmpty($ErrorMessage)) {
+            $ErrorMessage = "InputValue does not contain exactly $ExpectedCount occurrences of Pattern."
+        }
+        assert ($totalMatches -eq $ExpectedCount) $ErrorMessage
     }
 }
 
 # Asserts that LastExitCode is equal to ExpectedValue.
-function ExitCodeIs ([Parameter(ValueFromPipeline)]$InputValue, [int]$ExpectedValue) {
+function ExitCodeIs ([Parameter(ValueFromPipeline)]$InputValue, [int]$ExpectedValue, [string]$ErrorMessage) {
     process { }
     end {
-        assert ($LastExitCode -eq $ExpectedValue)
+        if ([string]::IsNullOrEmpty($ErrorMessage)) {
+            $ErrorMessage = "ExitCode = $InputValue, expected = $ExpectedValue."
+        }
+        assert ($LastExitCode -eq $ExpectedValue) $ErrorMessage
     }
 }
 
 # Asserts that the difference between two DateTime values are under a given tolerance.
-function IsAdjacent ([Parameter(ValueFromPipeline)][datetime]$InputValue, [datetime]$ExpectedValue, [timespan]$Tolerance=[timespan]::FromSeconds(2)) {
+function IsAdjacent ([Parameter(ValueFromPipeline)][datetime]$InputValue, [datetime]$ExpectedValue, [timespan]$Tolerance=[timespan]::FromSeconds(1), [string]$ErrorMessage) {
     process { }
     end {
         $difference = $InputValue - $ExpectedValue
-        assert ($difference.Duration() -lt $Tolerance)
+        if ([string]::IsNullOrEmpty($ErrorMessage)) {
+            $ErrorMessage = "The difference between $InputValue and $ExpectedValue is larger than the expected tolerance ($Tolerance)."
+        }
+        assert ($difference.Duration() -lt $Tolerance) $ErrorMessage
     }
 }
 
@@ -122,7 +134,7 @@ function New-TemporaryDirectory {
 
 task With_command_should_not_start_Firebird {
     Invoke-Container -ImageParameters 'ps', '-A' |
-        ContainsExactly -Pattern 'firebird|fbguard' -ExpectedCount 0
+        ContainsExactly -Pattern 'firebird|fbguard' -ExpectedCount 0 -ErrorMessage "Firebird processes should not be running when a command is specified."
 }
 
 task Without_command_should_start_Firebird {
@@ -131,18 +143,18 @@ task Without_command_should_start_Firebird {
 
         # Both firebird and fbguard must be running
         docker exec $cId ps -A |
-            ContainsExactly -Pattern 'firebird|fbguard' -ExpectedCount 2
+            ContainsExactly -Pattern 'firebird|fbguard' -ExpectedCount 2 -ErrorMessage "Expected 'firebird' and 'fbguard' processes to be running."
 
         # "Starting" but no "Stopping"
         docker logs $cId |
-            ContainsExactly -Pattern 'Starting Firebird|Stopping Firebird' -ExpectedCount 1
+            ContainsExactly -Pattern 'Starting Firebird|Stopping Firebird' -ExpectedCount 1 -ErrorMessage "Expected 'Starting Firebird' log entry."
 
         # Stop
         docker stop $cId > $null
 
         # "Starting" and "Stopping"
         docker logs $cId |
-            ContainsExactly -Pattern 'Starting Firebird|Stopping Firebird' -ExpectedCount 2
+            ContainsExactly -Pattern 'Starting Firebird|Stopping Firebird' -ExpectedCount 2 -ErrorMessage "Expected both 'Starting Firebird' and 'Stopping Firebird' log entries after container stop."
     }
 }
 
@@ -151,10 +163,10 @@ task FIREBIRD_DATABASE_can_create_database {
         param($cId)
 
         docker exec $cId test -f /var/lib/firebird/data/test.fdb |
-            ExitCodeIs -ExpectedValue 0
+            ExitCodeIs -ExpectedValue 0 -ErrorMessage "Expected database file '/var/lib/firebird/data/test.fdb' to exist."
 
         docker logs $cId |
-            Contains -Pattern "Creating database '/var/lib/firebird/data/test.fdb'"
+            Contains -Pattern "Creating database '/var/lib/firebird/data/test.fdb'" -ErrorMessage "Expected log message indicating creation of database '/var/lib/firebird/data/test.fdb'."
     }
 }
 
@@ -163,10 +175,10 @@ task FIREBIRD_DATABASE_can_create_database_with_absolute_path {
         param($cId)
 
         docker exec $cId test -f /tmp/test.fdb |
-            ExitCodeIs -ExpectedValue 0
+            ExitCodeIs -ExpectedValue 0 -ErrorMessage "Expected database file '/tmp/test.fdb' to exist when absolute path is used."
 
         docker logs $cId |
-            Contains -Pattern "Creating database '/tmp/test.fdb'"
+            Contains -Pattern "Creating database '/tmp/test.fdb'" -ErrorMessage "Expected log message indicating creation of database '/tmp/test.fdb' with absolute path."
     }
 }
 
@@ -176,15 +188,15 @@ task FIREBIRD_DATABASE_PAGE_SIZE_can_set_page_size_on_database_creation {
 
         'SET LIST ON; SELECT mon$page_size FROM mon$database;' |
             docker exec -i $cId isql -b -q /var/lib/firebird/data/test.fdb |
-                Contains -Pattern 'MON\$PAGE_SIZE(\s+)4096'
+                Contains -Pattern 'MON\$PAGE_SIZE(\s+)4096' -ErrorMessage "Expected database page size to be 4096."
     }
 
     Use-Container -Parameters '-e', 'FIREBIRD_DATABASE=test.fdb', '-e', 'FIREBIRD_DATABASE_PAGE_SIZE=16384' {
         param($cId)
 
         'SET LIST ON; SELECT mon$page_size FROM mon$database;' |
             docker exec -i $cId isql -b -q /var/lib/firebird/data/test.fdb |
-                Contains -Pattern 'MON\$PAGE_SIZE(\s+)16384'
+                Contains -Pattern 'MON\$PAGE_SIZE(\s+)16384' -ErrorMessage "Expected database page size to be 16384."
     }
 }
 
@@ -194,24 +206,24 @@ task FIREBIRD_DATABASE_DEFAULT_CHARSET_can_set_default_charset_on_database_creat
 
         'SET LIST ON; SELECT rdb$character_set_name FROM rdb$database;' |
             docker exec -i $cId isql -b -q /var/lib/firebird/data/test.fdb |
-                Contains -Pattern 'RDB\$CHARACTER_SET_NAME(\s+)NONE'
+                Contains -Pattern 'RDB\$CHARACTER_SET_NAME(\s+)NONE' -ErrorMessage "Expected default database charset to be NONE."
     }
 
     Use-Container -Parameters '-e', 'FIREBIRD_DATABASE=test.fdb', '-e', 'FIREBIRD_DATABASE_DEFAULT_CHARSET=UTF8' {
         param($cId)
 
         'SET LIST ON; SELECT rdb$character_set_name FROM rdb$database;' |
             docker exec -i $cId isql -b -q /var/lib/firebird/data/test.fdb |
-                Contains -Pattern 'RDB\$CHARACTER_SET_NAME(\s+)UTF8'
+                Contains -Pattern 'RDB\$CHARACTER_SET_NAME(\s+)UTF8' -ErrorMessage "Expected default database charset to be UTF8."
     }
 }
 
 task FIREBIRD_USER_fails_without_password {
     # Captures both stdout and stderr
     $($stdout = Invoke-Container -DockerParameters '-e', 'FIREBIRD_USER=alice') 2>&1 |
-        Contains -Pattern 'FIREBIRD_PASSWORD variable is not set.'    # stderr
+        Contains -Pattern 'FIREBIRD_PASSWORD variable is not set.' -ErrorMessage "Expected error message 'FIREBIRD_PASSWORD variable is not set.' when FIREBIRD_USER is set without FIREBIRD_PASSWORD."    # stderr
 
-    assert ($stdout -eq $null)
+    assert ($stdout -eq $null) "Expected stdout to be null when FIREBIRD_USER is set without FIREBIRD_PASSWORD."
 }
 
 task FIREBIRD_USER_can_create_user {
@@ -224,19 +236,19 @@ task FIREBIRD_USER_can_create_user {
         # Correct password
         'SELECT 1 FROM rdb$database;' |
             docker exec -i $cId isql -b -q -u alice -p bird inet:///var/lib/firebird/data/test.fdb |
-                ExitCodeIs -ExpectedValue 0
+                ExitCodeIs -ExpectedValue 0 -ErrorMessage "Expected successful login with correct password for user 'alice'."
 
         # Incorrect password
         'SELECT 1 FROM rdb$database;' |
             docker exec -i $cId isql -b -q -u alice -p tiger inet:///var/lib/firebird/data/test.fdb 2>&1 |
-                ExitCodeIs -ExpectedValue 1
+                ExitCodeIs -ExpectedValue 1 -ErrorMessage "Expected failed login with incorrect password for user 'alice'."
 
         # File /opt/firebird/SYSDBA.password exists?
         docker exec $cId test -f /opt/firebird/SYSDBA.password |
-            ExitCodeIs -ExpectedValue 0
+            ExitCodeIs -ExpectedValue 0 -ErrorMessage "Expected SYSDBA.password file to exist when a new user is created."
 
         docker logs $cId |
-            Contains -Pattern "Creating user 'alice'"
+            Contains -Pattern "Creating user 'alice'" -ErrorMessage "Expected log message indicating creation of user 'alice'."
     }
 }
 
@@ -247,19 +259,19 @@ task FIREBIRD_ROOT_PASSWORD_can_change_sysdba_password {
         # Correct password
         'SELECT 1 FROM rdb$database;' |
             docker exec -i $cId isql -b -q -u SYSDBA -p passw0rd inet:///var/lib/firebird/data/test.fdb |
-                ExitCodeIs -ExpectedValue 0
+                ExitCodeIs -ExpectedValue 0 -ErrorMessage "Expected successful login with new SYSDBA password."
 
         # Incorrect password
         'SELECT 1 FROM rdb$database;' |
             docker exec -i $cId isql -b -q -u SYSDBA -p tiger inet:///var/lib/firebird/data/test.fdb 2>&1 |
-                ExitCodeIs -ExpectedValue 1
+                ExitCodeIs -ExpectedValue 1 -ErrorMessage "Expected failed login with incorrect (old) SYSDBA password."
 
         # File /opt/firebird/SYSDBA.password removed?
         docker exec $cId test -f /opt/firebird/SYSDBA.password |
-            ExitCodeIs -ExpectedValue 1
+            ExitCodeIs -ExpectedValue 1 -ErrorMessage "Expected SYSDBA.password file to be removed after changing SYSDBA password."
 
         docker logs $cId |
-            Contains -Pattern 'Changing SYSDBA password'
+            Contains -Pattern 'Changing SYSDBA password' -ErrorMessage "Expected log message indicating SYSDBA password change."
     }
 }
 
@@ -268,10 +280,10 @@ task FIREBIRD_USE_LEGACY_AUTH_enables_legacy_auth {
         param($cId)
 
         $logs = docker logs $cId
-        $logs | Contains -Pattern "Using Legacy_Auth"
-        $logs | Contains -Pattern "AuthServer = Legacy_Auth"
-        $logs | Contains -Pattern "AuthClient = Legacy_Auth"
-        $logs | Contains -Pattern "WireCrypt = Enabled"
+        $logs | Contains -Pattern "Using Legacy_Auth" -ErrorMessage "Expected log message 'Using Legacy_Auth'."
+        $logs | Contains -Pattern "AuthServer = Legacy_Auth" -ErrorMessage "Expected log message 'AuthServer = Legacy_Auth'."
+        $logs | Contains -Pattern "AuthClient = Legacy_Auth" -ErrorMessage "Expected log message 'AuthClient = Legacy_Auth'."
+        $logs | Contains -Pattern "WireCrypt = Enabled" -ErrorMessage "Expected log message 'WireCrypt = Enabled' when Legacy_Auth is used."
     }
 }
 
@@ -280,8 +292,8 @@ task FIREBIRD_CONF_can_change_any_setting {
         param($cId)
 
         $logs = docker logs $cId
-        $logs | Contains -Pattern "DefaultDbCachePages = 64K"
-        $logs | Contains -Pattern "FileSystemCacheThreshold = 100M"
+        $logs | Contains -Pattern "DefaultDbCachePages = 64K" -ErrorMessage "Expected log message 'DefaultDbCachePages = 64K'."
+        $logs | Contains -Pattern "FileSystemCacheThreshold = 100M" -ErrorMessage "Expected log message 'FileSystemCacheThreshold = 100M'."
     }
 }
 
@@ -290,14 +302,14 @@ task FIREBIRD_CONF_key_is_case_sensitive {
         param($cId)
 
         $logs = docker logs $cId
-        $logs | Contains -Pattern "WireCrypt = Disabled"
+        $logs | Contains -Pattern "WireCrypt = Disabled" -ErrorMessage "Expected log message 'WireCrypt = Disabled' when using correct case."
     }
 
     Use-Container -Parameters '-e', 'FIREBIRD_CONF_WIRECRYPT=Disabled' {
         param($cId)
 
         $logs = docker logs $cId
-        $logs | ContainsExactly -Pattern "WireCrypt = Disabled" -ExpectedCount 0
+        $logs | ContainsExactly -Pattern "WireCrypt = Disabled" -ExpectedCount 0 -ErrorMessage "Expected no log message 'WireCrypt = Disabled' when using incorrect case (WIRECRYPT)."
     }
 }
 
@@ -326,12 +338,12 @@ task Can_init_db_with_scripts {
             param($cId)
 
             $logs = docker logs $cId
-            $logs | Contains -Pattern "10-create-table.sql"
-            $logs | Contains -Pattern "20-insert-data.sql"
+            $logs | Contains -Pattern "10-create-table.sql" -ErrorMessage "Expected log message for '10-create-table.sql' execution."
+            $logs | Contains -Pattern "20-insert-data.sql" -ErrorMessage "Expected log message for '20-insert-data.sql' execution."
 
             'SET LIST ON; SELECT count(*) AS country_count FROM country;' |
             docker exec -i $cId isql -b -q /var/lib/firebird/data/test.fdb |
-                Contains -Pattern 'COUNTRY_COUNT(\s+)5'
+                Contains -Pattern 'COUNTRY_COUNT(\s+)5' -ErrorMessage "Expected country count to be 5 after init scripts."
         }
     }
     finally {