Help Updates

Beginning to update comment-based help and wiki pages to match each other (and be accurate for v3.0 usage.)

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,31 @@ Describe "Add-Numbers" {
 .LINK
 Describe
 It
+BeforeEach
+AfterEach
+about_Mocking
 about_TestDrive
 
 #>
-param(
-    [Parameter(Mandatory = $true)]
-    $name,
+    param(
+        [Parameter(Mandatory = $true)]
+        $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,68 @@
 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
+Should
 Invoke-Pester
+about_Mocking
 about_TestDrive
 
 #>
 
-param(
-        [Parameter(Mandatory = $true, Position = 0)] $name,
-        $tags=@(),
+    param(
+        [Parameter(Mandatory = $true, Position = 0)] $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 +78,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 +106,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/SetupTeardown.ps1

@@ -1,10 +1,40 @@
 function BeforeEach
 {
+<#
+.SYNOPSIS
+    Defines a series of steps to perform at the beginning of every It block within
+    the current Context or Describe block.
+
+.DESCRIPTION
+    BeforeEach and AfterEach are unique in that they apply to the entire Context
+    or Describe block, even those that come before the BeforeEach or AfterEach
+    definition within the Context or Describe.  For a full description of this
+    behavior, as well as how multiple BeforeEach or AfterEach blocks interact
+    with each other, please refer to the about_BeforeEach_AfterEach help file.
+
+.LINK
+    about_BeforeEach_AfterEach
+#>
     Assert-DescribeInProgress -CommandName BeforeEach
 }
 
 function AfterEach
 {
+<#
+.SYNOPSIS
+    Defines a series of steps to perform at the end of every It block within
+    the current Context or Describe block.
+
+.DESCRIPTION
+    BeforeEach and AfterEach are unique in that they apply to the entire Context
+    or Describe block, even those that come before the BeforeEach or AfterEach
+    definition within the Context or Describe.  For a full description of this
+    behavior, as well as how multiple BeforeEach or AfterEach blocks interact
+    with each other, please refer to the about_BeforeEach_AfterEach help file.
+
+.LINK
+    about_BeforeEach_AfterEach
+#>
     Assert-DescribeInProgress -CommandName AfterEach
 }
 

en-US/about_BeforeEach_AfterEach.help.txt

@@ -0,0 +1,49 @@
+BeforeEach and AfterEach
+-------------------------------
+
+The BeforeEach and AfterEach commands allow you to define setup and teardown tasks that are
+performed at the beginning and end of every It block. This can eliminate duplication of code
+in test scripts, ensure that each test is performed on a pristine state regardless of their
+order, and perform any necessary cleanup tasks after each test.
+
+BeforeEach and AfterEach blocks may be defined inside of any Describe or Context. If they
+are present in both a Context and its parent Describe, BeforeEach blocks in the Describe scope
+are executed first, followed by BeforeEach blocks in the Context scope. AfterEach blocks are
+the reverse of this, with the Context  AfterEach blocks executing before Describe.
+
+The script blocks assigned to BeforeEach and AfterEach are dot-sourced in the Context or Describe
+which contains the current It statement, so you don't have to worry about the scope of variable
+assignments. Any variables that are assigned values within a BeforeEach block can be used inside
+the body of the It block.
+
+Note about syntax and placement
+-------------------------------
+
+Unlike most of the commands in a Pester script, BeforeEach and AfterEach blocks apply to the
+entire Describe or Context scope in which they are defined, regardless of the order of commands
+inside the Describe or Context. In other words, even if an It block appears before BeforeEach
+or AfterEach in the tests file, the BeforeEach and AfterEach will still be executed.
+
+Examples
+-------------------------------
+
+Describe 'Testing BeforeEach and AfterEach' {
+    $afterEachVariable = 'AfterEach has not been executed yet'
+
+    It 'Demonstrates that BeforeEach may be defined after the It command' {
+        $beforeEachVariable | Should Be 'Set in a describe-scoped BeforeEach'
+        $afterEachVariable | Should Be 'AfterEach has not been executed yet'
+    }
+
+    It 'Demonstrates that AfterEach has executed after the end of the first test' {
+        $afterEachVariable | Should Be 'AfterEach has been executed'
+    }
+
+    BeforeEach {
+        $beforeEachVariable = 'Set in a describe-scoped BeforeEach'
+    }
+
+    AfterEach {
+        $afterEachVariable = 'AfterEach has been executed'
+    }
+}