about_Pester.help.txt

TOPIC
    about_Pester

SHORT DESCRIPTION
    Pester is a test framework for Windows PowerShell. Use the Pester language
    and its commands to write and run tests that verify that your scripts and
    modules work as designed.

    Pester 3.4.0 supports Windows PowerShell 2.0 and greater.

LONG DESCRIPTION
    Pester introduces a professional test framework for Windows PowerShell
    commands. You can use Pester to test commands of any supported type,
    including scripts, cmdlets, functions, CIM commands, workflows, and DSC
    resources, and test these commands in modules of all types.

    Each Pester test compares actual to expected output using a collection of
    comparison operators that mirror the familiar operators in Windows
    PowerShell. In this way, Pester supports "dynamic testing", that is, it
    tests the code while it's running, instead of just evaluating code syntax
    ("static testing").

    Once your Pester tests are written are verified to work correctly, you can
    run them automatically or on demand to verify that the output didn't change
    and that any code changes did not introduce errors. You can also add your
    tests to the build scripts of a continuous integration system, and add new
    tests at any time.


 WHAT CAN PESTER TEST?
    Pester is designed to support "test-driven development" (TDD), in which you
    write and run tests before writing your code, thereby using the test as a
    code specification.

    It also supports "behavior-driven development" (BDD), in which the tests
    verify the behavior and output of the code, and the user experience,
    independent of its implementation. This lets you change the implementation
    and use the test to verify that the behavior is unchanged.

    You can use Pester to write "unit tests" that test individual functions in
    isolation and "integration tests" that verify that functions can be used
    together to generate expected results.

    Pester creates and manages a temporary drive (PSDrive named TestDrive:) that
    you can use to simulate a file system. For more information, see
    about_TestDrive.

    Pester also has "mocking" commands that replace the actual output of
    commands with output that you specify. Mocking lets you test your commands
    with varied input without creating and maintaining fake entries in a file
    or database, or commenting-out and inserting code just for testing. For more
    information, see about_Mocking.


 THE PESTER LANGUAGE
    To make it easier to write tests, Pester uses a language especially designed
    for testing. This "domain-specific language" (DSL) hides the standard
    verb-noun syntax of PowerShell commands.

    To make the language more fluent, the command parameters are positional, so
    you don't typically use parameter names.

    For example, this "gets all widgets" test uses the Pester language,
    including its "It", "Should", and "Be" commands. The test verifies that the
    actual output of the Get-Widget cmdlet is the same as the expected value in
    the $allWidgets variables.

        It "gets all widgets" {
           Get-Widget | Should -Be $allWidgets
        }


    To learn the Pester language, start by reading the following About and
    cmdlet help topics:

    -- Describe:     Creates a required test container.
    -- Context:      Creates an optional scoped test sub-container.
    -- It:           Creates a test.
    -- about_Should  Compares actual to expected values. This topic also
                     lists all valid values of Be, which specify the
                     comparison operator used in the test.



 HOW TO CREATE TEST FILES
    To start using Pester, create a script and a test file that tests the
    script. If you already have a script, you can create a test file for it.

    Pester test files are Windows PowerShell scripts with a .Tests.ps1 file name
    extension. The distinctive file name extension enables Pester to identify
    tests and distinguish them from other scripts.

    Typically, the test file and file it tests have the same base file name,
    such as:

        New-Log.ps1
        New-Log.Tests.ps1

    For a quick start, use the New-Fixture cmdlet in the Pester module. It
    creates a script with an empty function and a matching test file with a
    valid test.

    For example, this command creates a New-Log.ps1 script and a
    New-Log.Tests.ps1 test script in the C:\Scripts\LogScripts directory.

    New-Fixture -Path C:\Scripts\LogScripts -Name New-Log

        Directory: C:\Scripts\LogScripts


        Mode                LastWriteTime     Length Name
        ----                -------------     ------ ----
        -a----        4/18/2016   9:51 AM         30 New-Log.ps1
        -a----        4/18/2016   9:51 AM        262 New-Log.Tests.ps1


    The similar names do not automatically associate the test file and script
    file. The test file must include code to import ("dot-source") the
    functions, aliases, and variables in the script being tested into the scope
    of the test script.

    For example:
       . .\New-Log.ps1
    -or-
       . C:\Scripts\LogScripts\New-Log.ps1


    Many Pester test files, including the files that New-Fixture creates, begin with these
    statements.

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

    This code finds the current path of the test file at run time and saves it
    in the $here variable. Then, it finds the script based on the path in $here.
    This code assumes that the script has the same base name and is located in
    the same directory as the test file.

    You can use any code in the test file that finds the script, but be sure
    that the test file has the required *.Tests.ps1 file name extension.



 HOW TO RUN PESTER TESTS
    Pester tests are Windows PowerShell scripts (.ps1 files), so you can run
    them at the command line, or in any editor.

    Pester also has an Invoke-Pester cmdlet with useful parameters. By default,
    Invoke-Pester runs all the tests in a directory and all of its subdirectories
    recursively, but you can run selected tests by specifying a script name or
    name pattern, a test name, or a test tag.

    Invoke-Pester parameters also let you save the test output in NUnitXml or
    LegacyNUnitXml formats that are commonly used by reporting tools.

    For example, the following command runs all tests in the current directory
    and all subdirectories recursively. It writes output to the host, but does
    not generate any objects.

    Invoke-Pester

    In contrast, this command runs only the tests in the New-Log.Tests.ps1 file
    that have the 'EventVwr' tag. It writes the test results as custom objects
    and saves them in NUnitXml format in the NewLogTests.xml file. It also runs
    an optional code coverage test to verify that all lines in the script ran
    at least once during the tests.

    Invoke-Pester -Script C:\Tests\New-Log.Tests.ps1 `
          -Tag EventVwr -OutputFile .\NewLogTests.xml -OutputFormat NUnitXml `
          -CodeCoverage


    To run the New-Log.Tests.ps1 file that New-Fixture created, change to its
    local directory or a parent directory, and run Invoke-Pester. You can also
    use the Script parameter of Invoke-Pester to run only the New-Log.Tests.ps1
    test.

        PS C:\Scripts> Invoke-Pester -Script .\New-Log.Tests.ps1

    For more information about Invoke-Pester, type: Get-Help Invoke-Pester


 EXAMPLE
    For your first Pester test, use the New-Fixture cmdlet to create a script
    file and matching test file.

    For example:

        New-Fixture -Path C:\TestPester -Name Get-Hello

        Directory: C:\TestPester


        Mode                LastWriteTime         Length Name
        ----                -------------         ------ ----
        -a----        4/18/2016   9:51 AM             30 Get-Hello.ps1
        -a----        4/18/2016   9:51 AM            262 Get-Hello.Tests.ps1


    The Get-Hello.ps1 script contains an empty Get-Hello.ps1 function.

        function Get-Hello {}

    The Get-Hello.Tests.ps1 file contains an empty Pester test that is named
    for the Get-Hello function.

        Describe "Get-Hello" {
            It "does something useful" {
                $true | Should -Be $false
            }
        }

    To run the test, use Invoke-Pester. For example,

       Invoke-Pester C:\TestPester

    When you run the test, it fails by design, because Should compares $True to
    $False using the equal operator ("Be") and $True doesn't equal $False.


    To start testing the Get-Hello function, change $True to Get-Hello and
    $False to "Hello". Now, the test compares the output of Get-Hello output to
    'hello'.

    It should still fail, because Get-Hello doesn't return anything.

        Describe "New-Log" {
            It "does something useful" {
                Get-Hello | Should -Be 'Hello'
            }
        }


    To make the test pass, change the Get-Hello function so it returns 'hello'.
    Then, in steps, change $False to more interesting values, then change the
    Get-Hello function output to make the test pass.

    You can also experiment with other comparison operators, such as the BeLike
    (supports wildcards) and BeExactly (case sensitive), and BeLikeExactly
    operators. For more, information about comparison operators in Pester, see
    about_Should.


 PESTER TEST OUTPUT
    When you run a test, Pester use a variation of Write-Host to write
    color-coded text to the console. You'll quickly learn to recognize the
    purple test names and green (passing) and red (failing) test results with
    the elapsed time of the test.

         Describing Get-Profile
          [+] Gets all profiles 156ms
          [+] Gets only profiles 24ms

    The output ends with a summary of the test results.

         Tests completed in 3.47s
         Passed: 20 Failed: 1 Skipped: 0 Pending: 0 Inconclusive: 0

    However, because Pester uses Write-Host, it does not write to the output
    stream (stdout), so there are no output objects to save in a variable or
    redirect to a file.

    To direct Pester to create custom objects, use its PassThru parameter. The
    result is a single PSCustomObject with a TestResult property that one
    TestResult custom object for each test in the test file.

    To save the custom objects to a file, use the OutputFile and OutputFormat
    parameters of Invoke-Pester, which save the output in NUnitXml and
    LegacyNUnitXml formats that are easy to parse and commonly used by reporting
    tools.



  REAL-WORLD EXAMPLES
    For help in writing Pester tests, examine the extensive collection of tests
    that Pester uses to verify its Windows PowerShell code.

    To find the Pester tests in the Pester module directory, type:

        dir <Pester_module_path>\*Tests.ps1 -Recurse

       -or-

    dir (Get-Module Pester -ListAvailable).ModuleBase -Include *Tests.ps1 -Recurse


SEE ALSO
    Pester wiki: https://github.com/pester/pester/wiki
    Describe
    Context
    It
    New-Fixture
    Invoke-Pester
    about_Mocking
    about_Should
    about_TestDrive