From 00506d4ff5774ae825951f0a8382a8c51d4b377c Mon Sep 17 00:00:00 2001
From: Daniel Hughes <2237515+dan-hughes@users.noreply.github.com>
Date: Mon, 30 Sep 2024 07:43:47 +0100
Subject: [PATCH] `Assert-ElevatedUser` - Add custom error message parameter
 (#129)

---
 CHANGELOG.md                                  |  5 ++++
 source/Public/Assert-ElevatedUser.ps1         | 17 +++++++++--
 .../Unit/Public/Assert-ElevatedUser.Tests.ps1 | 29 +++++++++++++++----
 3 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f4f8088..ad4574d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Public command:
   - `Get-UserName` - get current user name cross platform.
 
+### Changed
+
+- `Assert-ElevatedUser`
+  - Add new parameter `ErrorMessage` to allow custom error messages.
+
 ### Fixed
 
 - `Get-PSModulePath`
diff --git a/source/Public/Assert-ElevatedUser.ps1 b/source/Public/Assert-ElevatedUser.ps1
index 6ae3df3..6b18b48 100644
--- a/source/Public/Assert-ElevatedUser.ps1
+++ b/source/Public/Assert-ElevatedUser.ps1
@@ -7,11 +7,19 @@
         throw a statement-terminating error if the script is not run from an elevated
         session.
 
+    .PARAMETER ErrorMessage
+        The error message to assign to the exception.
+
     .EXAMPLE
         Assert-ElevatedUser
 
         Throws an exception if the user has not elevated the PowerShell session.
 
+    .EXAMPLE
+        Assert-ElevatedUser -ErrorMessage 'A custom error message to throw'
+
+        Throws an exception if the user has not elevated the PowerShell session.
+
     .EXAMPLE
         `Assert-ElevatedUser -ErrorAction 'Stop'`
 
@@ -24,7 +32,12 @@
 function Assert-ElevatedUser
 {
     [CmdletBinding()]
-    param ()
+    param (
+        [Parameter()]
+        [ValidateNotNullOrEmpty()]
+        [System.String]
+        $ErrorMessage = $script:localizedData.ElevatedUser_UserNotElevated
+    )
 
     $isElevated = $false
 
@@ -43,7 +56,7 @@ function Assert-ElevatedUser
     {
         $PSCmdlet.ThrowTerminatingError(
             [System.Management.Automation.ErrorRecord]::new(
-                $script:localizedData.ElevatedUser_UserNotElevated,
+                $ErrorMessage,
                 'UserNotElevated',
                 [System.Management.Automation.ErrorCategory]::InvalidOperation,
                 'Command parameters'
diff --git a/tests/Unit/Public/Assert-ElevatedUser.Tests.ps1 b/tests/Unit/Public/Assert-ElevatedUser.Tests.ps1
index 1058583..dac6667 100644
--- a/tests/Unit/Public/Assert-ElevatedUser.Tests.ps1
+++ b/tests/Unit/Public/Assert-ElevatedUser.Tests.ps1
@@ -63,16 +63,33 @@ Describe 'Assert-ElevatedUser' -Tag 'Public' {
         }
     }
 
-    It 'Should throw the correct error' -Skip:$mockIsElevated {
-        $mockErrorMessage = InModuleScope -ScriptBlock {
-            $script:localizedData.ElevatedUser_UserNotElevated
+    Context 'When not supplying an error message' {
+        It 'Should throw the correct error' -Skip:$mockIsElevated {
+            $mockErrorMessage = InModuleScope -ScriptBlock {
+                $script:localizedData.ElevatedUser_UserNotElevated
+            }
+
+            { Assert-ElevatedUser } | Should -Throw -ExpectedMessage $mockErrorMessage
         }
 
-        { Assert-ElevatedUser } | Should -Throw -ExpectedMessage $mockErrorMessage
+        It 'Should not throw an exception' -Skip:(-not $mockIsElevated) {
+            { Assert-ElevatedUser } | Should -Not -Throw
+        }
     }
 
-    It 'Should not throw an exception' -Skip:(-not $mockIsElevated) {
-        { Assert-ElevatedUser } | Should -Not -Throw
+    Context 'When supplying a custom error message' {
+        BeforeAll {
+            $mockCustomMessage = 'This is a custom error message'
+        }
+
+        It 'Should throw the correct error' -Skip:$mockIsElevated {
+            { Assert-ElevatedUser -ErrorMessage $mockCustomMessage } | Should -Throw -ExpectedMessage $mockCustomMessage
+        }
+
+
+        It 'Should not throw an exception' -Skip:(-not $mockIsElevated) {
+            { Assert-ElevatedUser -ErrorMessage $mockCustomMessage} | Should -Not -Throw
+        }
     }
 
     Context 'When on Linux or macOS' {