AboutCmdletVerbs.Koans.ps1

using module PSKoans
[Koan(Position = 105)]
param()
<#
    Cmdlet Verbs

    The fundamental building block of PowerShell are cmdlets and functions, both
    of which are named according to a Verb-Noun syntax by convention.

    You can see the list of PowerShell's recommended / approved verbs by calling
    Get-Verb in your PowerShell console, or going to the following docs page:
    https://docs.microsoft.com/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands

    Each command should use a verb appropriate to the action it's taking, and a
    noun that succinctly and clearly describes what it's acting upon.

    In this topic, we'll cover a few of the most common verbs which you'll see
    most frequently.
#>

Describe "Basic Verbs" {

    BeforeAll {
        # We'll be using this path later on.
        $FilePath = Join-Path -Path $TestDrive -ChildPath "YOUR_PATH.txt"

        if (Test-Path $FilePath) {
            Remove-Item -Path $FilePath
        }
    }

    Context "Get" {
        <#
            Cmdlets with the Get verb are used for retrieving data.

            So for example "Get-Process" will retrieve all the processes running
            on your current machine.
        #>

        It 'is for commands that retrieve data' {
            <#
                Using the Get-Command cmdlet, which retrieves all available
                commands, find 5 commands with the Get verb.

                Fill in each blank with the name of a different Get-* command.
            #>
            $Answers = @(
                "____"
                "____"
                "____"
                "____"
                "____"
            )
            $Answers | Should -BeIn (Get-Command -Verb Get).Name

            $Answers | Get-Unique | Should -HaveCount 5 -Because "five unique cmdlets are required"
        }
    }

    Context "New" {
        <#
            Cmdlets with the New verb are used to create data.

            So for example 'New-Guid' will create a new GUID, or 'New-TimeSpan'
            will create a new [timespan] object with the specified parameters.
        #>

        It 'is for commands that create data' {
            <#
                Using Get-Command, find 5 commands with the New verb.

                Replace each ____ with the name of a New-* command.
            #>
            $Answers = @(
                "____"
                "____"
                "____"
                "____"
                "____"
            )
            $Answers | Should -BeIn (Get-Command -Verb New).Name

            $Answers | Get-Unique | Should -HaveCount 5 -Because "five unique cmdlets are required"
        }

        It 'can create a New-Item' {
            <#
                Let's try creating a file!

                Use New-Item to create a new text file, in the location
                specified with the $FilePath variable, which is defined above.

                The necessary parameters are already filled in for you here. In
                this case, the file we're creating is simply empty. You could
                also specify a -Value parameter with some text to put in the
                newly-created file.

                Take some time to experiment with New-Item in your console if
                you'd like to see what it can do! Start with:

                    Get-Command New-Item -Syntax
                    Get-Help New-Item -Examples
            #>

            $File = ____ -Path $FilePath -ItemType File

            # All "file" objects are of this type.
            $File | Should -BeOfType [System.IO.FileInfo]

            # An empty file has a "length" of zero.
            $File.Length | Should -Be 0
        }
    }

    Context "Add" {
        <#
            Cmdlets with the Add verb append data to an existing object or data
            source.

            Essentially, if the target doesn't exist then a cmdlet with the Add
            verb will typically create it. If it does exist, the cmdlet will
            add data to it, if data can be added without overwriting the
            original data.

            A common example one might see working with Office 365 is calendar
            permissions. If you want to grant permissions to somebody who
            doesn't have any, you use "Add-MailboxFolderPermission".
        #>

        It 'is for commands that append data' {
            <#
                Using Get-Command, find 5 commands with the Add verb.

                Replace each ____ with the name of an Add-* command.
            #>
            $Answers = "____", "____", "____", "____", "____"
            $Answers | Should -BeIn (Get-Command -Verb Add).Name

            $Answers | Get-Unique | Should -HaveCount 5 -Because "five unique cmdlets are required"
        }

        It 'can Add-Content to a file' {
            <#
                Try adding this content to the file we created above using
                Add-Content.
            #>
            "Mountains are merely mountains." | ____ -Path $FilePath

            <#
                Let's see what happens if we add a whole bunch of things! Fill
                in these blanks with whatever you like.
            #>

            '____' | Add-Content -Path $FilePath
            '____' | Add-Content -Path $FilePath
            '____' | Add-Content -Path $FilePath
            '____' | Add-Content -Path $FilePath

            # Let's check the contents of the file.
            $FileData = Get-Content -Path $FilePath

            # How many lines did we end up with?
            __ | Should -Be $FileData.Count

            <#
                We can see that several lines of content were added to the file.
                Add-* cmdlets can only append data, they can't overwrite. With
                this information, you should be able to determine what the
                expected content of the file is at this point.
            #>

            $ExpectedContent = @(
                'Mountains are merely mountains.'
                '____'
                '____'
                '____'
                'The road onwards, the road back; which is the shorter?'
            )

            $ExpectedContent | Should -BeExactly $FileData
        }
    }

    Context "Set" {
        <#
            Cmdlets with the Set verb will overwrite information that already
            exists.

            Some Set-* cmdlets require the instance to already be present for
            you to change it; you'll need to use a New-* cmdlet first to create
            an instance before you can overwrite information within it.

            A common example one may see working with Office 365 is with
            calendar permissions. If a user already has some permissions
            configured, you can use "Set-MailboxFolderPermission" to change the
            user's permissions.
        #>

        It 'is for commands that overwrite data' {
            <#
                Using Get-Command, find 5 commands with the Set verb.

                Replace each ____ with the name of a Set-* command.
            #>
            $Answers = "____", "____", "____", "____", "____"
            $Answers | Should -BeIn (Get-Command -Verb Set).Name

            $Answers | Get-Unique | Should -HaveCount 5 -Because "five unique cmdlets are required"
        }

        It 'can Set-Content for a file' {
            <#
                Let's try using Set-Content on our text file from before. But
                first, let's check that it still has the contents we added. We
                should still have 5 lines in it from before.

                If you added extra lines to the file in the Add-Content koan
                above, make sure to update the expected line count here!
            #>
            $LineCount = 5
            Get-Content -Path $FilePath | Should -HaveCount $LineCount

            # Now let's try setting the contents.
            "Wherever you are, it's the place you need to be." | Set-Content -Path $FilePath

            # So what should be in the file now?
            $FileContent = Get-Content -Path $FilePath
            "____" | Should -BeExactly $FileContent

            # What happens if we set the contents again?
            '____' | Set-Content -Path $FilePath
            Get-Content -Path $FilePath | Should -BeExactly "Rest and be kind, you don't have to prove anything."
            <#
                You'll see that there's only one line of text in the file. This
                is because the Set-Content command will completely overwrite
                whatever is in the file already.
            #>
        }
    }

    Context "Remove" {
        <#
            Cmdlets with the Remove verb will delete data from an object or data
            source.

            Once again with calendar permissions in Office 365, you can use a
            Remove cmdlet to completely remove a user's permissions to a
            calendar.
            #>

        It "is for commands that delete data" {
            <#
            Using Get-Command, find 5 commands with the Remove verb.

            Replace each ____ with the name of a Remove-* command.
        #>
            $Answers = "____", "____", "____", "____", "____"
            $Answers | Should -BeIn (Get-Command -Verb Remove).Name

            $Answers | Get-Unique | Should -HaveCount 5 -Because "five unique cmdlets are required"
        }

        It 'can Remove-Item to delete a file' {
            <#
                    We can use Remove-Item to delete the text file we've been
                    working with. Before we do, let's just double check the file
                    still exists. 'Leaf' here refers to a file; 'Container'
                    would be the corresponding type for a folder.
                #>
            Test-Path $FilePath -PathType Leaf | Should -BeTrue

            # Pester has its own way of checking that files exist.
            $FilePath | Should -Exist

            # Use Remove-item to delete the file completely.
            ____ -Path $FilePath

            # Let's check it was removed properly.                Test-Path $FilePath -PathType Leaf | Should -BeTrue
            Test-Path $FilePath | Should -BeFalse

            <#
                    If we try to remove a file that doesn't exist, we should get
                    an error. What does that error look like?
                #>
            $Message = "____"
            { Remove-Item -Path $FilePath -ErrorAction Stop } | Should -Throw -ExpectedMessage $Message
        }
    }
}