Implemented new Test-SqlDscIsRole for testing whether a server principal is a Role. Fixed documentation in Test-SqlDscIsLogin

CHANGELOG.md

@@ -4,6 +4,8 @@ The format is based on and uses the types of changes according to [Keep a Change
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+- SqlServerDsc
+  - Added Test-SqlDscIsRole to be used like Test-SqlDscIsLogin but tests for a server role as principal
 
 ### Changed
 

source/Public/Test-SqlDscIsLogin.ps1

@@ -1,15 +1,15 @@
 <#
     .SYNOPSIS
-        Returns whether the database principal exist.
+        Returns whether the server principal exist and is a login.
 
     .DESCRIPTION
-        Returns whether the database principal exist.
+        Returns whether the server principal exist and is a login.
 
     .PARAMETER ServerObject
         Specifies current server connection object.
 
     .PARAMETER Name
-        Specifies the name of the database principal.
+        Specifies the name of the server principal.
 
     .OUTPUTS
         [System.Boolean]

source/Public/Test-SqlDscIsRole.ps1

@@ -0,0 +1,50 @@
+<#
+    .SYNOPSIS
+        Returns whether the database principal exists and is a database role.
+
+    .DESCRIPTION
+        Returns whether the database principal exist and is a database role.
+
+    .PARAMETER ServerObject
+        Specifies current server connection object.
+
+    .PARAMETER Name
+        Specifies the name of the database principal.
+
+    .OUTPUTS
+        [System.Boolean]
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        Test-SqlDscIsDatabaseRole -ServerObject $serverInstance -Name 'MyPrincipal'
+
+        Returns $true if the principal exist as role, if not $false is returned.
+#>
+function Test-SqlDscIsRole
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [Microsoft.SqlServer.Management.Smo.Server]
+        $ServerObject,
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name
+    )
+
+    process
+    {
+        $principalExist = $false
+
+        if ($ServerObject.Roles[$Name])
+        {
+            $principalExist = $true
+        }
+
+        return $principalExist
+    }
+}

tests/Unit/Public/Test-SqlDscIsRole.Tests.ps1

@@ -0,0 +1,96 @@
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '')]
+param ()
+
+BeforeDiscovery {
+    try
+    {
+        if (-not (Get-Module -Name 'DscResource.Test'))
+        {
+            # Assumes dependencies has been resolved, so if this module is not available, run 'noop' task.
+            if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable))
+            {
+                # Redirect all streams to $null, except the error stream (stream 2)
+                & "$PSScriptRoot/../../../build.ps1" -Tasks 'noop' 2>&1 4>&1 5>&1 6>&1 > $null
+            }
+
+            # If the dependencies has not been resolved, this will throw an error.
+            Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop'
+        }
+    }
+    catch [System.IO.FileNotFoundException]
+    {
+        throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.'
+    }
+}
+
+BeforeAll {
+    $script:dscModuleName = 'SqlServerDsc'
+
+    $env:SqlServerDscCI = $true
+
+    Import-Module -Name $script:dscModuleName
+
+    # Loading mocked classes
+    Add-Type -Path (Join-Path -Path (Join-Path -Path $PSScriptRoot -ChildPath '../Stubs') -ChildPath 'SMO.cs')
+
+    $PSDefaultParameterValues['InModuleScope:ModuleName'] = $script:dscModuleName
+    $PSDefaultParameterValues['Mock:ModuleName'] = $script:dscModuleName
+    $PSDefaultParameterValues['Should:ModuleName'] = $script:dscModuleName
+}
+
+AfterAll {
+    $PSDefaultParameterValues.Remove('InModuleScope:ModuleName')
+    $PSDefaultParameterValues.Remove('Mock:ModuleName')
+    $PSDefaultParameterValues.Remove('Should:ModuleName')
+
+    # Unload the module being tested so that it doesn't impact any other tests.
+    Get-Module -Name $script:dscModuleName -All | Remove-Module -Force
+
+    Remove-Item -Path 'env:SqlServerDscCI'
+}
+
+Describe 'Test-SqlDscIsRole' -Tag 'Public' {
+    Context 'When the instance does not have the specified principal' {
+        BeforeAll {
+            $mockServerObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Server' |
+                Add-Member -MemberType 'ScriptProperty' -Name 'Roles' -Value {
+                    return @{
+                        'JuniorDBA' = New-Object -TypeName Object |
+                            Add-Member -MemberType 'NoteProperty' -Name 'Name' -Value 'JuniorDBA' -PassThru -Force
+                    }
+                } -PassThru -Force
+        }
+
+        It 'Should return $false' {
+            $result = Test-SqlDscIsRole -ServerObject $mockServerObject -Name 'UnknownUser'
+
+            $result | Should -BeFalse
+        }
+    }
+
+    Context 'When the instance have the specified principal' {
+        BeforeAll {
+            $mockServerObject = New-Object -TypeName 'Microsoft.SqlServer.Management.Smo.Server' |
+                Add-Member -MemberType 'ScriptProperty' -Name 'Roles' -Value {
+                    return @{
+                        'JuniorDBA' = New-Object -TypeName Object |
+                            Add-Member -MemberType 'NoteProperty' -Name 'Name' -Value 'JuniorDBA' -PassThru -Force
+                    }
+                } -PassThru -Force
+        }
+
+        It 'Should return $true' {
+            $result = Test-SqlDscIsRole -ServerObject $mockServerObject -Name 'JuniorDBA'
+
+            $result | Should -BeTrue
+        }
+
+        Context 'When passing ServerObject over the pipeline' {
+            It 'Should return $true' {
+                $result = $mockServerObject | Test-SqlDscIsRole -Name 'JuniorDBA'
+
+                $result | Should -BeTrue
+            }
+        }
+    }
+}