Merge pull request #190 from dlwyatt/HelpUpdates

Help updates

Functions/Context.ps1

@@ -1,13 +1,17 @@
 function Context {
 <#
 .SYNOPSIS
-Provides syntactic sugar for logiclly grouping It blocks within a single Describe block.
+Provides logical grouping of It blocks within a single Describe block. Any Mocks defined
+inside a Context are removed at the end of the Context scope, as are any files or folders
+added to the TestDrive during the Context block's execution. Any BeforeEach or AfterEach
+blocks defined inside a Context also only apply to tests within that Context .
 
 .PARAMETER Name
 The name of the Context. This is a phrase describing a set of tests within a describe.
 
 .PARAMETER Fixture
-Script that is executed. This may include setup specific to the context and one or more It blocks that validate the expected outcomes.
+Script that is executed. This may include setup specific to the context and one or more It
+blocks that validate the expected outcomes.
 
 .EXAMPLE
 function Add-Numbers($a, $b) {
@@ -30,27 +34,32 @@ Describe "Add-Numbers" {
 .LINK
 Describe
 It
+BeforeEach
+AfterEach
+about_Should
+about_Mocking
 about_TestDrive
 
 #>
-param(
-    [Parameter(Mandatory = $true)]
-    $name,
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Name,
+
+        [ValidateNotNull()]
+        [ScriptBlock] $Fixture  = $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)")
+    )
 
-    [ValidateNotNull()]
-    [ScriptBlock] $fixture = $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)")
-)
     Assert-DescribeInProgress -CommandName Context
 
-    $Pester.EnterContext($name)
+    $Pester.EnterContext($Name )
     $TestDriveContent = Get-TestDriveChildItem
 
     $Pester.CurrentContext | Write-Context
 
     try
     {
-        Add-SetupAndTeardown -ScriptBlock $fixture
-        $null = & $fixture
+        Add-SetupAndTeardown -ScriptBlock $Fixture 
+        $null = & $Fixture 
     }
     catch
     {

Functions/Describe.ps1

@@ -1,63 +1,69 @@
 function Describe {
 <#
 .SYNOPSIS
-Defines the context bounds of a test. One may use this block to
-encapsulate a scenario for testing - a set of conditions assumed
-to be present and that should lead to various expected results
-represented by the IT blocks.
+Creates a logical group of tests.  All Mocks and TestDrive contents
+defined within a Describe block are scoped to that Describe; they
+will no longer be present when the Describe block exits.  A Describe
+block may contain any number of Context and It blocks.
 
 .PARAMETER Name
-The name of the Test. This is often an expressive phsae describing the scenario being tested.
+The name of the test group. This is often an expressive phrase describing the scenario being tested.
 
 .PARAMETER Fixture
 The actual test script. If you are following the AAA pattern (Arrange-Act-Assert), this
 typically holds the arrange and act sections. The Asserts will also lie in this block but are
-typically nested each in its own IT block.
+typically nested each in its own It block. Assertions are typically performed by the Should
+command within the It blocks.
+
+.PARAMETER Tags
+Optional parameter containing an array of strings.  When calling Invoke-Pester, it is possible to
+specify a -Tag parameter which will only execute Describe blocks containing the same Tag.
 
 .EXAMPLE
 function Add-Numbers($a, $b) {
     return $a + $b
 }
 
 Describe "Add-Numbers" {
-
     It "adds positive numbers" {
         $sum = Add-Numbers 2 3
-        $sum.should.be(5)
+        $sum | Should Be 5
     }
 
     It "adds negative numbers" {
         $sum = Add-Numbers (-2) (-2)
-        $sum.should.be((-4))
+        $sum | Should Be (-4)
     }
 
     It "adds one negative number to positive number" {
         $sum = Add-Numbers (-2) 2
-        $sum.should.be(0)
+        $sum | Should Be 0
     }
 
     It "concatenates strings if given strings" {
         $sum = Add-Numbers two three
-        $sum.should.be("twothree")
+        $sum | Should Be "twothree"
     }
-
 }
 
 .LINK
 It
 Context
 Invoke-Pester
+about_Should
+about_Mocking
 about_TestDrive
 
 #>
 
-param(
-        [Parameter(Mandatory = $true, Position = 0)] $name,
-        $tags=@(),
+    param(
+        [Parameter(Mandatory = $true, Position = 0)]
+        [string] $Name,
+        $Tags=@(),
         [Parameter(Position = 1)]
         [ValidateNotNull()]
-        [ScriptBlock] $fixture = $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)")
-)
+        [ScriptBlock] $Fixture = $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)")
+    )
 
     if ($null -eq (Get-Variable -Name Pester -ValueOnly -ErrorAction SilentlyContinue))
     {
@@ -73,16 +79,17 @@ param(
     }
 
     #TODO add test to test tags functionality
-    if($pester.TagFilter -and @(Compare-Object $tags $pester.TagFilter -IncludeEqual -ExcludeDifferent).count -eq 0) {return}
+    if($Pester.TagFilter -and @(Compare-Object $Tags $Pester.TagFilter -IncludeEqual -ExcludeDifferent).count -eq 0) {return}
 
     $Pester.EnterDescribe($Name)
+
     $Pester.CurrentDescribe | Write-Describe
     New-TestDrive
 
     try
     {
-        Add-SetupAndTeardown -ScriptBlock $fixture
-        $null = & $fixture
+        Add-SetupAndTeardown -ScriptBlock $Fixture
+        $null = & $Fixture
     }
     catch
     {
@@ -100,7 +107,7 @@ param(
 function Assert-DescribeInProgress
 {
     param ($CommandName)
-    if ($null -eq $pester -or [string]::IsNullOrEmpty($pester.CurrentDescribe))
+    if ($null -eq $Pester -or [string]::IsNullOrEmpty($Pester.CurrentDescribe))
     {
         throw "The $CommandName command may only be used inside a Describe block."
     }

Functions/InModuleScope.ps1

@@ -1,5 +1,55 @@
 function InModuleScope
 {
+<#
+.SYNOPSIS
+   Allows you to execute parts of a test script within the
+   scope of a PowerShell script module.
+.DESCRIPTION
+   By injecting some test code into the scope of a PowerShell
+   script module, you can use non-exported functions, aliases
+   and variables inside that module, to perform unit tests on 
+   its internal implementation.
+
+   InModuleScope may be used anywhere inside a Pester script,
+   either inside or outside a Describe block.
+.PARAMETER ModuleName
+   The name of the module into which the test code should be
+   injected. This module must already be loaded into the current
+   PowerShell session.
+.PARAMETER ScriptBlock
+   The code to be executed within the script module.
+.EXAMPLE
+    # The script module:
+    function PublicFunction
+    {
+        # Does something
+    }
+
+    function PrivateFunction
+    {
+        return $true
+    }
+
+    Export-ModuleMember -Function PublicFunction
+
+    # The test script:
+
+    Import-Module MyModule
+
+    InModuleScope MyModule {
+        Describe 'Testing MyModule' {
+            It 'Tests the Private function' {
+                PrivateFunction | Should Be $true
+            }
+        }
+    }
+
+    Normally you would not be able to access "PrivateFunction" from
+    the powershell session, because the module only exported
+    "PublicFunction".  Using InModuleScope allowed this call to
+    "PrivateFunction" to work successfully.
+#>
+
     [CmdletBinding()]
     param (
         [Parameter(Mandatory = $true)]

Functions/It.ps1

@@ -4,18 +4,16 @@ function It {
 Validates the results of a test inside of a Describe block.
 
 .DESCRIPTION
-The It function is intended to be used inside of a Describe
-Block. If you are familiar with the AAA pattern
-(Arrange-Act-Assert), this would be the appropriate location
-for an assert. The convention is to assert a single
-expectation for each It block. The code inside of the It block
-should throw an exception if the expectation of the test is not
-met and thus cause the test to fail. The name of the It block
-should expressively state the expectation of the test.
-
-In addition to using your own logic to test expectations and
-throw exceptions, you may also use Pester's own helper functions
-to assist in evaluating test results using the Should object.
+The It command is intended to be used inside of a Describe or Context Block.
+If you are familiar with the AAA pattern (Arrange-Act-Assert), the body of
+the It block is the appropriate location for an assert. The convention is to
+assert a single expectation for each It block. The code inside of the It block
+should throw a terminating error if the expectation of the test is not met and
+thus cause the test to fail. The name of the It block should expressively state
+the expectation of the test.
+
+In addition to using your own logic to test expectations and throw exceptions,
+you may also use Pester's Should command to perform assertions in plain language.
 
 .PARAMETER Name
 An expressive phsae describing the expected test outcome.
@@ -32,27 +30,25 @@ function Add-Numbers($a, $b) {
 }
 
 Describe "Add-Numbers" {
-
     It "adds positive numbers" {
         $sum = Add-Numbers 2 3
-        $sum.should.be(5)
+        $sum | Should Be 5
     }
 
     It "adds negative numbers" {
         $sum = Add-Numbers (-2) (-2)
-        $sum.should.be((-4))
+        $sum | Should Be (-4)
     }
 
     It "adds one negative number to positive number" {
         $sum = Add-Numbers (-2) 2
-        $sum.should.be(0)
+        $sum | Should Be 0
     }
 
     It "concatenates strings if given strings" {
         $sum = Add-Numbers two three
-        $sum.should.be("twothree")
+        $sum | Should Be "twothree"
     }
-
 }
 
 .LINK
@@ -61,7 +57,8 @@ Context
 about_should
 #>
     param(
-        $name,
+        [Parameter(Mandatory = $true)]
+        [string]$name,
         [ScriptBlock] $test = $(Throw "No test script block is provided. (Have you put the open curly brace on the next line?)")
     )