Add targeted test file option to build script

Tests/Build/BuildModule.tests.ps1

@@ -48,6 +48,56 @@ Describe "Build Module Tests" {
         }
     }
 
+    Context "Test-ScriptAnalyzer test path selection" {
+        BeforeEach {
+            Mock Invoke-Pester { $Path } -ModuleName build
+        }
+
+        It "selects only the supplied test file" {
+            $testPath = Join-Path $TestDrive "single.tests.ps1"
+            New-Item -Path $testPath -ItemType File | Out-Null
+
+            $selectedPaths = @(Test-ScriptAnalyzer -InProcess -TestPath $testPath)
+
+            $selectedPaths.Count | Should -Be 1
+            $selectedPaths[0] | Should -Be (Resolve-Path -LiteralPath $testPath).ProviderPath
+        }
+
+        It "passes test paths containing apostrophes intact" {
+            $testPath = Join-Path $TestDrive "one'two.tests.ps1"
+            New-Item -Path $testPath -ItemType File | Out-Null
+
+            $selectedPaths = @(Test-ScriptAnalyzer -InProcess -TestPath $testPath)
+
+            $selectedPaths.Count | Should -Be 1
+            $selectedPaths[0] | Should -Be (Resolve-Path -LiteralPath $testPath).ProviderPath
+        }
+
+        It "fails when the supplied test path does not exist" {
+            { Test-ScriptAnalyzer -InProcess -TestPath (Join-Path $TestDrive "missing.tests.ps1") } | Should -Throw
+        }
+
+        It "fails when the supplied test path is a directory" {
+            { Test-ScriptAnalyzer -InProcess -TestPath $TestDrive } | Should -Throw "TestPath must point to a test file."
+        }
+
+        It "selects the four default test suite directories when no path is supplied" {
+            $selectedPaths = @(Test-ScriptAnalyzer -InProcess)
+            $repoRoot = (Resolve-Path -LiteralPath (Join-Path $PSScriptRoot "..\..")).Path
+            $expectedPaths = @(
+                "${repoRoot}\Tests\Build"
+                "${repoRoot}\Tests\Engine"
+                "${repoRoot}\Tests\Rules"
+                "${repoRoot}\Tests\Documentation"
+            )
+
+            $selectedPaths.Count | Should -Be 4
+            foreach ($expectedPath in $expectedPaths) {
+                $selectedPaths | Should -Contain $expectedPath
+            }
+        }
+    }
+
     Context "Test result functions" {
         BeforeAll {
             $xmlFile = @'

build.ps1

@@ -30,6 +30,9 @@ param(
     [Parameter(Mandatory=$true,ParameterSetName='Test')]
     [switch] $Test,
 
+    [Parameter(ParameterSetName='Test')]
+    [string] $TestPath,
+
     [Parameter(ParameterSetName='Test')]
     [switch] $InProcess,
     [string] $WithPowerShell,
@@ -88,6 +91,7 @@ END {
         "Test" {
             $testArgs = @{
                 InProcess = $InProcess
+                TestPath = $TestPath
                 WithPowerShell = $WithPowerShell
                 Verbose = $verboseWanted
             }

build.psm1

@@ -296,6 +296,7 @@ function Test-ScriptAnalyzer
     [CmdletBinding()]
     param (
         [switch] $InProcess,
+        [string] $TestPath,
         [string] $WithPowerShell
     )
 
@@ -318,7 +319,16 @@ function Test-ScriptAnalyzer
         #
         #
         $testModulePath = Join-Path "${projectRoot}" -ChildPath out
-        $testScripts = "'${projectRoot}\Tests\Build','${projectRoot}\Tests\Engine','${projectRoot}\Tests\Rules','${projectRoot}\Tests\Documentation'"
+        if ($TestPath) {
+            $resolvedTestPath = (Resolve-Path -LiteralPath $TestPath -ErrorAction Stop).ProviderPath
+            if ((Get-Item -LiteralPath $resolvedTestPath).PSIsContainer) {
+                throw "TestPath must point to a test file."
+            }
+            $testScripts = "'{0}'" -f $resolvedTestPath.Replace("'", "''")
+        }
+        else {
+            $testScripts = "'${projectRoot}\Tests\Build','${projectRoot}\Tests\Engine','${projectRoot}\Tests\Rules','${projectRoot}\Tests\Documentation'"
+        }
         try {
             $savedModulePath = $env:PSModulePath
             $env:PSModulePath = "${testModulePath}{0}${env:PSModulePath}" -f [System.IO.Path]::PathSeparator