Learning Pester and better comment based Help. Please leave feedback if you have any suggestions!

Test-EventLogExists.ps1

Function Test-EventLogExists
{
<#
    .SYNOPSIS
        Tests to see if an Event Log exists

    .DESCRIPTION
        Tests to see if an Event Log exists and returns $true or $false

    .PARAMETER  EventLogname
        The Name of the Event Log to be written to.

    .PARAMETER  Source
        The Source that generates the Event Log.

    .EXAMPLE
        Test-EventLogExists -LogName Application -Source AppName

        This command Returns a Boolean value. In the above example it returns $true since the Source exists.

    .EXAMPLE
        Test-EventLogExists -LogName Application -Source MissingAppName

        This command Returns a Boolean value. In the above example it returns $false since the Source does not exist.

    .INPUTS
        System.String

    .OUTPUTS
        System.Boolean

    .NOTES
        This function is an Extension to be used with PSAppDeployToolkit.

        TODO: Add a NoToolkit switch to swap PsAppToolkit specific functions for Built In alternatives.

    .LINK
        http://psappdeploytoolkit.com
#>

    [CmdletBinding()]
    Param
    (
        [Parameter(Mandatory = $true, Position = 0)]
        [String]$EventLogName,

        [Parameter(Mandatory = $true, Position = 1)]
        [String[]]$Source
    )

    Begin
    {
        [string]${CmdletName} = $PSCmdlet.MyInvocation.MyCommand.Name
        Write-FunctionHeaderOrFooter -CmdletName ${CmdletName} -CmdletBoundParameters $PSBoundParameters -Header
    }

    Process
    {
        Try
        {
            $Null = Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Services\Eventlog\$EventLogName\$Source" -ErrorAction Stop
            Write-Log -Message "Event Log Exists" -Severity 1 -Source ${CmdletName}
            Return $true
        }
        Catch
        {
            Write-Log -Message "Event Log does not Exist: `n$(Resolve-Error)" -Severity 1 -Source ${CmdletName}
            Return $false
        }
    }

    End
    {
        Write-FunctionHeaderOrFooter -CmdletName ${CmdletName} -Footer
    }
}

Test-EventLogExists.Tests.ps1

$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path).Replace('.Tests.', '.')
. "$here\$sut"

Remove-EventLog -LogName Pester -ErrorAction SilentlyContinue

Describe 'Test-EventLogExists' {
    
    Set-StrictMode -Version latest
    
    Mock Write-Log
    Mock Write-FunctionHeaderOrFooter

    Context 'Help and Parameter checks' {
        
        Mock Get-ItemProperty

        It 'should have inbuilt help along with Description and examples' {
            
            $helpinfo = Get-Help Test-EventLogExists
            $helpinfo.examples | Should not BeNullOrEmpty  
            $helpinfo.Details | Should not BeNullOrEmpty   
            $helpinfo.Description | Should not BeNullOrEmpty
        }

        It 'Should have EventLogName and Source Mandatory params' {
            
            { Test-EventLogExists -EventLogName $null } | Should Throw
            { Test-EventLogExists -EventLogName $null -Source 'String' -ErrorAction Continue } | Should Throw
            { Test-EventLogExists -EventLogName 'String' -Source $null } | Should Throw
            { Test-EventLogExists -EventLogName 'String' -Source 'String' } | Should Not Throw
        }
    }
    
    Context "Event log doesn't Exist" {
        
        Mock Get-ItemProperty { Throw 'EventLog does not Exist' }

        It 'Returns False' {
            
            $Results = Test-EventLogExists -EventLogName 'MadeUpLogName' -Source 'MadeUpSource'
            $Results | Should Be $false
        }
    }

    Context 'Event log Exists' {
        
        Mock Get-ItemProperty { Return $true }
            
        It 'Returns True' {
            
            $Results = Test-EventLogExists -EventLogName 'LogNameThatExists' -Source 'SourceThatExists'
            $Results | Should Be $true
        }    
    }

    Context 'Integration - Test Errors' {
            
        It 'Errors and Returns False' {
            
            $Results = Test-EventLogExists -EventLogName 'Pester' -Source 'Test-EventLogExists'
            $Results | Should Not Be $true
            $Results | Should Be $false
        }

        It 'No Error and Returns True' {
            
            New-EventLog -LogName 'Pester' -Source 'Test-EventLogExists' -ErrorAction SilentlyContinue

            $Results = Test-EventLogExists -EventLogName 'Pester' -Source 'Test-EventLogExists'
            $Results | Should Be $true
            $Results | Should Not Be $false
        }
    }
}

Write-PSADTEventLog.ps1

function Write-PSADTEventLog
{
<#
    .SYNOPSIS
        Writes an Event Log for PSAppDeployToolkit

    .DESCRIPTION
        If Event Log does not Exist, it creates it and writes a Message to it.

    .PARAMETER  Message
        The Message to be written to the Event Log.

    .PARAMETER  EventLogName
        The Name of the Event Log to be written to.

        The Default Value is PSADT.

    .PARAMETER  Source
        The Source that generates the Event Log.

        The Default Value is the PSAppDeployToolkit Variable: $appName

    .PARAMETER  EntryType
        The Event Log Severity Level Type.

        Valid Values: Information, Warning and Error

    .PARAMETER  EventID
        The Event ID to be written to the Event Log.

        The Default Value is 10.

    .EXAMPLE
        Write-PSADTEventLog -Message 'The Installation Completed' -EntryType 'Information'

        Output would write an Event Log with the following properties:
            Message:        'The Installation Completed'
            EventLogName:   PSADT
            Source:         $appName
            EntryType:      Information
            EventID:        10

    .EXAMPLE
        Write-PSADTEventLog -Message 'The Installation Failed!' -EventLogName 'Application' -Source 'MyApp' -EntryType 'Error' -EventID '1'

        Output would write an Event Log with the following properties:
            Message:        'The Installation Failed!'
            EventLogName:   Application
            Source:         MyApp
            EntryType:      Error
            EventID:        1

    .INPUTS
        System.String,System.Int32

    .OUTPUTS


    .NOTES
        This function is an Extension to be used with PSAppDeployToolkit.

        TODO: Add a NoToolkit switch to swap PsAppToolkit specific functions for Built In alternatives.

    .LINK
        http://psappdeploytoolkit.com

#>

    [CmdletBinding()]
    param(
        [Parameter(Mandatory=$true)]
        [System.String]$Message,

        [Parameter(Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [System.String]$EventLogName = "PSADT",

        [Parameter(Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [System.String]$Source = "$appName",

        [Parameter(Mandatory=$true)]
        [ValidateSet('Information', 'Error', 'Warning')]
        [System.String]$EntryType,

        [Parameter(Mandatory=$false)]
        [ValidateNotNullOrEmpty()]
        [System.Int32]$EventId = 10
    )

    Begin
    {
        [string]${CmdletName} = $PSCmdlet.MyInvocation.MyCommand.Name
        Write-FunctionHeaderOrFooter -CmdletName ${CmdletName} -CmdletBoundParameters $PSBoundParameters -Header
    }

    Process
    {
        if (!(Test-EventLogExists -EventLogName $EventLogName -Source $Source))
        {
            try
            {
                Write-Log -Message "Creating Eventlog: `nSource: $($Source) `nEventLog Name: $($EventLogName)" -Severity 1 -Source ${CmdletName}
                New-Eventlog -LogName $EventLogName -Source $Source -ErrorAction Stop
            }
            catch [System.Security.SecurityException]
            {
                Write-Log -Message "Failed to run New-Eventlog. `n$(Resolve-Error)" -Severity 3 -Source ${CmdletName}
                throw "Failed to run New-Eventlog: $($_)"
            }
        }
        else
        {
            Write-Log -Message "Event Log [$($EventLogName)] with Source [$($Source)] already exists." -Severity 1 -Source ${CmdletName}
        }

        try
        {
            Write-Log -Message "Writing Eventlog: `nSource: $($Source) `nEventLog Name: $($EventLogName) `nEvent ID: $($EventId) `nMessage: $($Message)" -Severity 1 -Source ${CmdletName}
            Write-EventLog -LogName $EventLogName -Source $Source -EntryType $EntryType -EventId $EventId -Message $Message -ErrorAction Stop
        }
        catch [System.Security.SecurityException]
        {
            Write-Log -Message "Failed to run Write-Eventlog. `n$(Resolve-Error)" -Severity 3 -Source ${CmdletName}
            throw "Failed to run Write-Eventlog: $($_)"
        }
    }

    End
    {
        Write-FunctionHeaderOrFooter -CmdletName ${CmdletName} -Footer
    }
}

Write-PSADTEventLog.Tests.ps1

$here = Split-Path -Parent $MyInvocation.MyCommand.Path
$sut = (Split-Path -Leaf $MyInvocation.MyCommand.Path).Replace('.Tests.', '.')
. "$here\$sut"

Remove-EventLog -LogName Pester -ErrorAction SilentlyContinue

Describe 'Write-PSADTEventLog' {
    
    Set-StrictMode -Version latest
    
    Mock Write-Log
    Mock Write-FunctionHeaderOrFooter

     Context 'Help and Parameter checks' {
        Set-StrictMode -Version latest
        
        Mock Test-EventLogExists
        Mock New-EventLog
        Mock Write-EventLog

        It 'should have inbuilt help along with Description and examples' {
            
            $helpinfo = Get-Help Write-PSADTEventLog
            $helpinfo.examples | Should not BeNullOrEmpty  
            $helpinfo.Details | Should not BeNullOrEmpty
            $helpinfo.Description | Should not BeNullOrEmpty
        }

        It 'Should have Message and EntryType Mandatory params' {
            
            { Write-PSADTEventLog -Message $null } | Should Throw
            { Write-PSADTEventLog -EventID 'String' -Message $null } | Should Throw
            { Write-PSADTEventLog -EventLogName 'Pester' -Message $Null } | Should Throw
            { Write-PSADTEventLog -EntryType 'Error' -EventLogName 'Pester' -Message 'Test Message' } | Should Not Throw
        }

        It 'Should have EntryType param values of Warning, Information, or Error' {
            
            { Write-PSADTEventLog -EntryType $null -Message 'Test Message' } | should throw
            { Write-PSADTEventLog -EntryType 'WrongInput' -Message 'Test Message' } | should throw
            { Write-PSADTEventLog -EntryType 'Error' -EventLogName 'Pester' -Message 'Test Message' } | Should Not Throw
            { Write-PSADTEventLog -EntryType 'Warning' -EventLogName 'Pester' -Message 'Test Message' } | Should Not Throw
            { Write-PSADTEventLog -EntryType 'Information' -EventLogName 'Pester' -Message 'Test Message' } | Should Not Throw
        }

        It 'Should only accept Int for EventID Parameter' {

            { Write-PSADTEventLog -EntryType 'Error' -EventLogName 'Pester' -Message 'Test Message' -EventId '13' } | Should Not Throw
            { Write-PSADTEventLog -EntryType 'Error' -EventLogName 'Pester' -Message 'Test Message' -EventId 'String13' } | Should Throw

        }
    }

    Context 'EventLog Missing' {
        
        Mock Test-EventLogExists
        Mock New-EventLog
        Mock Write-EventLog { return $true }

        It 'Creates New Eventlog and Writes and Event Log to It ' {
            
            $Result = Write-PSADTEventLog -Message 'This is a Pester Test Event' -EventLogName Pester -Source Write-PSADTEventLog -EventId '10' -EntryType 'Information'
         
            Assert-MockCalled Test-EventLogExists -Scope It -Times 1
            Assert-MockCalled New-EventLog -Scope It -Times 1
            Assert-MockCalled Write-EventLog -Scope It -Times 1

            $Result | Should Be $true
        }
    }
    
    Context 'EventLog Exists' {
        
        Mock Test-EventLogExists { Return $true }
        Mock New-EventLog
        Mock Write-EventLog { return $true }

        It 'Write to Event Log' {
            
            $Result = Write-PSADTEventLog -Message 'This is a Pester Test Event' -EventLogName Pester -Source Write-PSADTEventLog -EventId '12' -EntryType 'Warning'

            Assert-MockCalled Test-EventLogExists -Scope It -Times 1
            Assert-MockCalled New-EventLog -Scope It -Times 0
            Assert-MockCalled Write-EventLog -Scope It -Times 1

            $Result | Should Be $true
        }
    }
    
    Context 'Integration - Test for Creating Event' {
        
        Mock Test-EventLogExists { Return $false }
        Mock Write-EventLog

        It 'Creates Event Log if it does not Exist' {

            $Result = Write-PSADTEventLog -Message 'This is a Pester Test Event' -EventLogName Pester -Source Write-PSADTEventLog -EventId '11' -EntryType 'Information'

            { Get-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\Eventlog\Pester\Write-PSADTEventLogTest' -ErrorAction Stop } | Should Throw
            { Get-ItemProperty -Path 'HKLM:\SYSTEM\CurrentControlSet\Services\Eventlog\Pester\Write-PSADTEventLog' -ErrorAction Stop } | Should Not Throw

            $Result | Should BeNullOrEmpty
        }
    }

    Context 'Integration - Test for Writing to an Event Log' {
        
        Mock Test-EventLogExists { Return $true }

        It 'Writes Message to Event Log from Source' {

            $Result = Write-PSADTEventLog -Message 'This is a Pester Test Event' -EventLogName Pester -Source Write-PSADTEventLog -EventId '1' -EntryType 'Error'

            Get-EventLog -LogName Pester -Source Write-PSADTEventLog | Select-Object -ExpandProperty Message -ErrorAction Stop | Should Be 'This is a Pester Test Event'
            Get-EventLog -LogName Pester -Source Write-PSADTEventLog | Select-Object -ExpandProperty EntryType | Should Be 'Error'
            Get-EventLog -LogName Pester -Source Write-PSADTEventLog | Select-Object -ExpandProperty EntryType | Should Not Be 'Warning'

            $Result | Should BeNullOrEmpty

            Remove-EventLog -LogName Pester -ErrorAction SilentlyContinue
        }
    }
}