From 07f6eab2eb1ddf0a6a04763afc75c4605b4bc7d2 Mon Sep 17 00:00:00 2001 From: Johan Ljunggren Date: Tue, 20 Aug 2024 13:04:05 +0200 Subject: [PATCH] Add comment-based help and make eval case-sensitive --- source/Public/Assert-BlockString.ps1 | 83 ++++++++++++++-------------- 1 file changed, 42 insertions(+), 41 deletions(-) diff --git a/source/Public/Assert-BlockString.ps1 b/source/Public/Assert-BlockString.ps1 index 0d94218..f9a3695 100644 --- a/source/Public/Assert-BlockString.ps1 +++ b/source/Public/Assert-BlockString.ps1 @@ -1,57 +1,58 @@ <# - The choice of encoding method depends on your specific requirements and the context in which you are working. Here are some common encoding methods and their typical use cases: + .SYNOPSIS + Asserts that a string, here-string or array of strings matches the expected + string, here-string or array of strings. - UTF-8: + .DESCRIPTION + The `Assert-BlockString` command compares a string, here-string or array + of strings with the expected string, here-string or array of strings and + throws an error that includes the hex output if they are not equal. The + comparison is case sensitive. It is commonly used in unit testing scenarios + to verify the correctness of string outputs on byte level. - Use Case: This is the most commonly used encoding on the web and is compatible with ASCII. It is efficient for text that primarily uses characters from the ASCII set but can also represent any Unicode character. - Pros: Compact for ASCII characters, widely supported. - Cons: Variable-length encoding can be less efficient for characters outside the ASCII range. - ASCII: + .PARAMETER Actual + The actual string, here-string or array of strings to be compared with the + expected value. This parameter accepts pipeline input. - Use Case: Suitable for text that only contains characters in the ASCII set (0-127). - Pros: Very compact for ASCII characters. - Cons: Cannot represent characters outside the ASCII range. - Unicode (UTF-16): + .PARAMETER Expected + The expected string, here-string or array of strings that the actual value + should match. - Use Case: Often used in Windows environments and for text that contains a large number of non-ASCII characters. - Pros: Fixed-length for most common characters, widely supported. - Cons: Less efficient for ASCII-only text compared to UTF-8. - UTF-32: + .PARAMETER Because + An optional reason or explanation for the assertion. - Use Case: Used when fixed-length encoding is required, and memory usage is not a concern. - Pros: Fixed-length encoding makes it easy to index characters. - Cons: Uses more memory compared to UTF-8 and UTF-16. + .PARAMETER DifferenceAnsi + An optional ANSI color code to highlight the difference between the expected + and actual strings. The default value is '31m' (red text). - Given these considerations, UTF-8 is generally a good default choice due to its efficiency and wide support. -#> -# $string = "Your string here" - -# # Convert the string to a byte array using UTF-8 encoding -# $byteArray = [System.Text.Encoding]::UTF8.GetBytes($string) + .EXAMPLE + PS> Assert-BlockString -Actual 'hello', 'world' -Expected 'Hello', 'World' -# # Create a ByteCollection from the byte array -# $byteCollection = [Microsoft.PowerShell.Commands.ByteCollection]::new($byteArray) + This example asserts that the array of strings 'hello' and 'world' matches + the expected array of strings 'Hello' and 'World'. If the assertion fails, + an error is thrown. -# # Convert the byte array to a hexadecimal string -# $hexString = -join ($byteArray | ForEach-Object { "{0:X2} " -f $_ }) + .EXAMPLE + PS> 'hello', 'world' | Assert-BlockString -Expected 'Hello', 'World' -# # Output the ByteCollection and the hexadecimal string to verify -# $byteCollection -# $hexString + This example demonstrates the usage of pipeline input. The block of strings + 'Hello' and 'World' is piped to `Assert-BlockString` and compared with the + expected strings 'Hello' and 'World'. If the assertion fails, an error is + thrown. -# [System.BitConverter]::ToString($byteArray) -replace '-', ' ' + .NOTES + TODO: Is it possible to rename command to `Should-BeBlockString`. Pester handles Should verb with, not sure it possible to resolve here: + https://github.com/pester/Pester/commit/c8bc9679bed19c8fbc4229caa01dd083f2d03d4f#diff-b7592dd925696de2521c9b12b966d65519d502045462f002c343caa7c0986936 + and + https://github.com/pester/Pester/commit/c8bc9679bed19c8fbc4229caa01dd083f2d03d4f#diff-460f64eafc16facefbed201eb00fb151c75eadf7cc58a504a01527015fb1c7cdR17 -#Tags = @('testing', 'tdd', 'bdd', 'assertion', 'assert', 'pester') - -# Pester handles Should verb with: -# https://github.com/pester/Pester/commit/c8bc9679bed19c8fbc4229caa01dd083f2d03d4f#diff-b7592dd925696de2521c9b12b966d65519d502045462f002c343caa7c0986936 -# and -# https://github.com/pester/Pester/commit/c8bc9679bed19c8fbc4229caa01dd083f2d03d4f#diff-460f64eafc16facefbed201eb00fb151c75eadf7cc58a504a01527015fb1c7cdR17 +#> function Assert-BlockString # Should-BeBlockString { [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseProcessBlockForPipelineCommand', '')] [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidThrowOutsideOfTry', '')] - param ( + param + ( [Parameter(Position = 1, ValueFromPipeline = $true)] $Actual, @@ -65,7 +66,7 @@ function Assert-BlockString # Should-BeBlockString [Parameter()] [System.String] - $DifferenceAnsi = '30;31m' + $DifferenceAnsi = '31m' ) $hasPipelineInput = $MyInvocation.ExpectingInput @@ -78,13 +79,13 @@ function Assert-BlockString # Should-BeBlockString # Verify if $Actual is a string or string array $isStringType = $Actual -is [System.String] -or ($Actual -is [System.Array] -and $Actual[0] -is [System.String]) - $stringsAreEqual = $isStringType -and (-join $Actual) -eq (-join $Expected) + $stringsAreEqual = $isStringType -and (-join $Actual) -ceq (-join $Expected) if (-not $stringsAreEqual) { if (-not $isStringType) { - $message = "Expected to actual value to be of type string or string[], but it was not." + $message = 'Expected to actual value to be of type string or string[], but it was not.' } else {