Merge pull request #102 from adamdriscoll/feature/documentation-and-scaffolding

Feature/documentation and scaffolding

Author: itfranck

.gitignore

@@ -1,3 +1,5 @@
-.vscode/launch.json
-CI/LocalPostProcessing.ps1
-
+.vscode
+CI/LocalPostProcessing.ps1
+Scratchpad.ps1
+Output/testResults*.xml
+Output/stats.json

CI/CI.ps1

@@ -1,69 +1,69 @@
 param (
-    [string[]]$BrowserList=@('Chrome','Firefox')
+    [string[]]$BrowserList = @('Chrome', 'Firefox')
 )
 #Get the OS/PS version info for later. On Linux run headless On windows and PS 6 (but not 7)  add WindowsPowershell to the module path.
-$Platform       = ([environment]::OSVersion.Platform).ToString() + ' PS' + $PSVersionTable.PSVersion.Major
-if ($Platform -notlike 'win*')  {$env:AlwaysHeadless = $true}
-if ($Platform -like    'win*6') {
-        $env:PSModulePath -split ';' | Where-Object {$_ -match "\w:\\Prog.*PowerShell\\modules"} | ForEach-Object {
-            $env:PSModulePath = ($_ -replace "PowerShell","WindowsPowerShell") + ";" +  $env:PSModulePath
-        }
+$Platform = ([environment]::OSVersion.Platform).ToString() + ' PS' + $PSVersionTable.PSVersion.Major
+if ($Platform -notlike 'win*') { $env:AlwaysHeadless = $true }
+if ($Platform -like 'win*6') {
+    $env:PSModulePath -split ';' | Where-Object { $_ -match "\w:\\Prog.*PowerShell\\modules" } | ForEach-Object {
+        $env:PSModulePath = ($_ -replace "PowerShell", "WindowsPowerShell") + ";" + $env:PSModulePath
+    }
 }
 
 #Make sure we have the modules we need
-Import-Module .\Selenium.psd1 -Force -ErrorAction Stop
+Import-Module .\Output\Selenium\Selenium.psd1 -Force -ErrorAction Stop
 $checkImportExcel = Get-Module -ListAvailable ImportExcel
 if (-not ($checkImportExcel)) {
     Write-Verbose -Verbose 'Installing ImportExcel'
     Install-Module ImportExcel -Force -SkipPublisherCheck
 }
-else {$checkImportExcel | Out-Host}
-$checkPester = Get-Module -ListAvailable Pester| Where-Object {$_.version.major -ge 4 -and $_.version.minor -ge 4}
+else { $checkImportExcel | Out-Host }
+$checkPester = Get-Module -ListAvailable Pester | Where-Object { $_.version.major -ge 4 -and $_.version.minor -ge 4 }
 if (-not $checkPester) {
     Write-Verbose -Verbose 'Installing Pester'
     Install-Module Pester -Force -SkipPublisherCheck
 }
-else {$checkPester | Out-Host}
+else { $checkPester | Out-Host }
 
 #Run the test and results export to an Excel file for current OS - Test picks up the selected browser from an environment variable.
-$RunParameters  = @{
-    XLFile     = '{0}/results/Results-{1}.xlsx' -f $env:BUILD_ARTIFACTSTAGINGDIRECTORY, [environment]::OSVersion.Platform.ToString()
-    Script     = Join-Path -Path (Join-Path $pwd 'Examples') -ChildPath 'Combined.tests.ps1'
+$RunParameters = @{
+    XLFile = '{0}/results/Results-{1}.xlsx' -f $env:BUILD_ARTIFACTSTAGINGDIRECTORY, [environment]::OSVersion.Platform.ToString()
+    Script = Join-Path -Path (Join-Path $pwd 'Examples') -ChildPath 'Combined.tests.ps1'
 }
 foreach ( $b   in $BrowserList) {
     $env:DefaultBrowser = $b
-    $RunParameters['OutputFile']    = Join-Path $pwd "TestResults-$platform$b.xml"
-    $RunParameters['WorkSheetName'] =  "$B $Platform"
+    $RunParameters['OutputFile'] = Join-Path $pwd "TestResults-$platform$b.xml"
+    $RunParameters['WorkSheetName'] = "$B $Platform"
     $RunParameters | Out-Host
     & "$PSScriptRoot\Pester-To-XLSx.ps1"  @RunParameters
 }
 
 #Merge the results sheets into a sheet named 'combined'.
-$excel          = Open-ExcelPackage $RunParameters.XLFile
-$wslist         = $excel.Workbook.Worksheets.name
+$excel = Open-ExcelPackage $RunParameters.XLFile
+$wslist = $excel.Workbook.Worksheets.name
 Close-ExcelPackage -NoSave $excel
-Merge-MultipleSheets -path  $RunParameters.XLFile -WorksheetName $wslist -OutputSheetName combined -OutputFile $RunParameters.XLFile -HideRowNumbers -Property name,result
+Merge-MultipleSheets -path  $RunParameters.XLFile -WorksheetName $wslist -OutputSheetName combined -OutputFile $RunParameters.XLFile -HideRowNumbers -Property name, result
 
 #Hide everything on 'combined' except test name, results for each browser, and test group, Set column widths, tweak titles, apply conditional formatting.
-$excel          = Open-ExcelPackage $RunParameters.XLFile
-$ws             = $excel.combined
+$excel = Open-ExcelPackage $RunParameters.XLFile
+$ws = $excel.combined
 2..$ws.Dimension.end.Column | ForEach-Object {
-    if ($ws.Cells[1,$_].value -notmatch '^Name|Result$|PS\dGroup$') {
+    if ($ws.Cells[1, $_].value -notmatch '^Name|Result$|PS\dGroup$') {
         Set-ExcelColumn -Worksheet $ws -Column $_ -Hid
     }
-    elseif ($ws.Cells[1,$_].value -match 'Result$' )  {
+    elseif ($ws.Cells[1, $_].value -match 'Result$' ) {
         Set-ExcelColumn -Worksheet $ws -Column $_ -Width 17
-        Set-ExcelRange $ws.Cells[1,$_] -WrapText
+        Set-ExcelRange $ws.Cells[1, $_] -WrapText
     }
-    if ($ws.cells[1,$_].value -match 'PS\dGroup$') {
-            Set-ExcelRange $ws.Cells[1,$_] -WrapText -Value 'Group'
+    if ($ws.cells[1, $_].value -match 'PS\dGroup$') {
+        Set-ExcelRange $ws.Cells[1, $_] -WrapText -Value 'Group'
     }
-    if ($ws.cells[1,$_].value -match '^Name|PS\dGroup$' -and ($ws.Column($_).Width -gt 80)) {
+    if ($ws.cells[1, $_].value -match '^Name|PS\dGroup$' -and ($ws.Column($_).Width -gt 80)) {
         $ws.Column($_).Width = 80
     }
 }
 Set-ExcelRow -Worksheet $ws -Height 28.5
-$cfRange        = [OfficeOpenXml.ExcelAddress]::new(2,3,$ws.Dimension.end.Row,  (3*$wslist.count -2)).Address
+$cfRange = [OfficeOpenXml.ExcelAddress]::new(2, 3, $ws.Dimension.end.Row, (3 * $wslist.count - 2)).Address
 Add-ConditionalFormatting -WorkSheet $ws -range $cfRange -RuleType ContainsText -ConditionValue "Failure" -BackgroundPattern None -ForegroundColor Red   -Bold
 Add-ConditionalFormatting -WorkSheet $ws -range $cfRange -RuleType ContainsText -ConditionValue "Success" -BackgroundPattern None -ForeGroundColor Green
 Close-ExcelPackage $excel

CI/pipeline.yml

@@ -1,48 +1,48 @@
 # https://aka.ms/yaml
 
 trigger:
-    branches:
-      include:
-      - '*'
-      # - master
-      # - releases/*
-    paths:
-      exclude:
+  branches:
+    include:
+      - "*"
+    # - master
+    # - releases/*
+  paths:
+    exclude:
       - additions.md
       - ChangeLog.Txt
       - README.md
 
 jobs:
-  - job: 'Windows'
+  - job: "Windows"
     pool:
-      vmImage: 'windows-latest'
+      vmImage: "windows-latest"
     steps:
-    - powershell: './CI/CI.ps1 -browserlist Chrome,Firefox,IE'
-      displayName: 'Run Test on Windows PowerShell'
-    - pwsh: './CI/CI.ps1 -browserlist Chrome'
-      displayName: 'Run Test on PowerShell core on Windows'
-    - task: PublishPipelineArtifact@1
-      inputs:
-        targetPath: '$(Build.ArtifactStagingDirectory)/results'
-        artifact: 'Windows Results'
-    - task: PublishTestResults@2
-      inputs:
-        testResultsFormat: 'NUnit'
-        testResultsFiles: '**/TestResults*.xml'
-        failTaskOnFailedTests: true
+      - powershell: "./CI/CI.ps1 -browserlist Chrome,Firefox,IE"
+        displayName: "Run Test on Windows PowerShell"
+      - pwsh: "./CI/CI.ps1 -browserlist Chrome"
+        displayName: "Run Test on PowerShell core on Windows"
+      - task: PublishPipelineArtifact@1
+        inputs:
+          targetPath: "$(Build.ArtifactStagingDirectory)/results"
+          artifact: "Windows Results"
+      - task: PublishTestResults@2
+        inputs:
+          testResultsFormat: "NUnit"
+          testResultsFiles: "**/TestResults*.xml"
+          failTaskOnFailedTests: true
 
-  - job: 'Ubuntu'
+  - job: "Ubuntu"
     pool:
-      vmImage: 'ubuntu-latest'
+      vmImage: "ubuntu-latest"
     steps:
-    - powershell: './CI/CI.ps1 -browserlist Chrome,Firefox'
-      displayName: 'Run Test on Linux'
-    - task: PublishPipelineArtifact@1
-      inputs:
-        targetPath: '$(Build.ArtifactStagingDirectory)/results'
-        artifact: 'Linux Results'
-    - task: PublishTestResults@2
-      inputs:
-        testResultsFormat: 'NUnit'
-        testResultsFiles: '**/TestResults*.xml'
-        failTaskOnFailedTests: true
+      - powershell: "./CI/CI.ps1 -browserlist Chrome,Firefox"
+        displayName: "Run Test on Linux"
+      - task: PublishPipelineArtifact@1
+        inputs:
+          targetPath: "$(Build.ArtifactStagingDirectory)/results"
+          artifact: "Linux Results"
+      - task: PublishTestResults@2
+        inputs:
+          testResultsFormat: "NUnit"
+          testResultsFiles: "**/TestResults*.xml"
+          failTaskOnFailedTests: true

ChangeLog.md

@@ -4,12 +4,16 @@
 
 - Added -IgnoreProtectedModeSettings to Start-SeInternetExplorer - https://github.com/adamdriscoll/selenium-powershell/issues/79 - Thanks, @MysticRyuujin!
 
+- Added Markdown documentation (See Help subfolder) for all the cmdlets (PlatyPS is used behind the scene to maintain it) 
+- Added MAML embedded help that can be accessed through `Get-Help`(eg: `Get-Help Start-SeChrome -Examples`)
+
 # 3.0.0 - 3/31/2020
 
 ## Changed
 
 - Fixed issue with importing module in PSv5.1 - https://github.com/adamdriscoll/selenium-powershell/issues/69
 - Updated Chrome drivers
+- Converted monolythic module into a scaffolded module through a Plaster template. Module will now have a debug version and a compiled version that need to be built with Invoke-Build. See the Debug folder for additional informations on how to debug.
 
 # 3.0.0-beta2 - 1/29/2020
 

Debug/Debug.ps1

@@ -0,0 +1,21 @@
+import-module Platyps
+import-module InvokeBuild
+
+# Just a line to replace $PsScriptRoot since the former does not work when debugging with F8
+$ScriptFullPath, $ScriptRoot, $ScriptName, $ScriptNameShort = @('', '', '', ''); $ScriptFullPath = if (-not [String]::IsNullOrEmpty($PSCommandPath)) { $PSCommandPath } elseif ($psEditor -ne $null) { $psEditor.GetEditorContext().CurrentFile.Path } elseif ($psise -ne $null) { $psise.CurrentFile.FullPath }; $ScriptRoot = Split-Path -Path $ScriptFullPath -Parent; $ScriptName = Split-Path -Path $ScriptFullPath -Leaf; $ScriptNameShort = ([System.IO.Path]::GetFileNameWithoutExtension($ScriptFullPath))
+$ProjectPath = Split-Path $ScriptRoot 
+
+# Load Debug version
+#import-module "$ProjectPath\Selenium.psd1" -Force
+
+#Load Compiled version
+import-module "$ProjectPath\output\selenium\Selenium.psd1" -Force
+Invoke-Pester -Script 'C:\Github\selenium-powershell\Examples\Combined.tests.ps1'
+
+# Build module
+#invoke-build -File "$ProjectPath\Selenium.build.ps1"
+
+
+
+
+

Debug/README.md

@@ -0,0 +1,31 @@
+# Instructions
+
+## Prerequisites
+- InvokeBuild module
+- PlatyPS module
+
+## How to
+
+### Debug
+
+To load the debugging version, simply load the Selenium.psd1 located at the root of this directory.
+
+`import-module "$ProjectPath\Selenium.psd1" -Force`
+
+To load the compiled version, load the psd1 located in the output directory instead. 
+
+`import-module "$ProjectPath\output\selenium\Selenium.psd1" -Force`
+
+When developping, you should always load the development version of the module. Never work in the files from the **output** directory directly as these will be wiped out whenever you compile the module again.
+
+### Compile the module
+The module is scaffolded into multiple files for convenience and compiled into a psm1 file when ready to be published. 
+
+Alongside this, additional tasks are performed suche as basic Powershell validation, self-updating Markdown documentation, embedded help file generation, psd1 function replace based on Public folder content, etc. 
+
+To perform these tasks and produce a compiled (but not packaged) version of the module, run the following
+
+`invoke-build -File "$ProjectPath\Selenium.build.ps1"`
+
+
+See the debug.ps1 file in this directory to get started.