Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge pull request #520 from juneb/FixAboutTypo
Fixed typo and tabs
  • Loading branch information
nohwnd committed Apr 24, 2016
2 parents cec8204 + d6318d6 commit d9bd6d5
Showing 1 changed file with 87 additions and 88 deletions.
175 changes: 87 additions & 88 deletions en-US/about_Pester.help.txt
Expand Up @@ -3,76 +3,75 @@

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.
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.
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").
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.
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.
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.
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.
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.
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 varyied 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.
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.
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.
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.
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
}
It "gets all widgets" {
Get-Widget | Should Be $allWidgets
}


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

-- Describe: Creates a required test container.
-- Context: Creates an optional scoped test sub-container.
Expand All @@ -85,24 +84,24 @@ LONG DESCRIPTION

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.
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.
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:
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.
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-Log.Tests.ps1 test script in the C:\Scripts\LogScripts directory.

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

Expand All @@ -116,75 +115,75 @@ LONG DESCRIPTION


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.
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


You'll often see this code at the beginning of a Pester test file and in
Pester snippets.
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.
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.
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.
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.
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.
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.
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.
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 ` -CodeCoverage
-Tag EventVwr -OutputFile .\NewLogTests.xml -OutputFormat NUnitXml
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.
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
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.
file and matching test file.

For example:

Expand Down Expand Up @@ -221,8 +220,8 @@ LONG DESCRIPTION


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'.
$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.

Expand All @@ -234,20 +233,20 @@ LONG DESCRIPTION


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.
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.
(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.
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
Expand All @@ -259,23 +258,23 @@ LONG DESCRIPTION
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.
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.
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.
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.
that Pester uses to verify its Windows PowerShell code.

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

Expand Down

0 comments on commit d9bd6d5

Please sign in to comment.