Nutstone.Selenium.Powershell 1.0.25

Nutstone Selenium Powershell

Powershell implementation of Nutstone.Selenium.Core

This package wraps the nutstone.seleniu.core package in a series of powershell cmdlet's. A selenium session is created and the relevant version of the Chrome driver is downloaded and used for the session.

Only the Chrome driver is (currently) supported.

The powershell cmdlets wrap the core functionalty of the IWebDriverProxy provider implemented in nutstone.selenium.core

The Cmdlets

Open-WebSession

creates a new selenium session and sets up global PS variables used by most other cmdlets in this module. This cmdlet should be the executed before any other selenium-based cmdlets.

Open-WebSession -Headless $false -LeaveBrowserRunning $true --Logfile somefilepath 

Get-WebDriver

returns the current instance of IwebDriverProxy. You can then use the methods exposed on this interface to directly communicate with the selenium driver instance

$webDriver = Get-WebDriver  
# display available methods on the webdriver 
Write-Host ($webDriver | Get-Member | Format-Table | Out-String)  

Open-Url

opens a browser at the specified url and waits for it to be 'ready'

Open-Url -Url http://acme:8080/api   

Set-Element

populates an html element value (in the browser) from the specified Xpath. Currently supports Action's of Input, Click, Select, SelectMaterial

Set-Element -Xpath "//*[@id='firstname']" -Value "some value" -Action Input 

Get-Element

returns an IWebElement object (see selenium docs) that can be used to manipulate the element

$element = Get-Element -Xpath "//*[@id='firstname']" 
$element.Click() # maybe  

Close-WebSession

Closes the web session and disposes of associated selenium objects

Close-WebSession 

Support cmdlets

Utilities

Import-Scripts

Imports into current scope all files called *.ps1 in a directory (and subdirectories) - so you can reference functions etc from all of those ps1 scripts

Import-Scripts -Path C:\somerootPath\scriptdir   

"Page" cmdlets

This package supports the idea of a 'Page' (similar to selenium). A page consists of a number of html elements that will be populated. Local powsershell functions/scriptblock's can be used to further enhance/replace the default cmdlet functionality.

Using Pages

New-Page / Add-PageElement

# set surname - this gets called when the element surname is being processed 
function setSurname() {
    param (
       [Parameter(Mandatory)]
       $PageModel
    )
    Set-Element -Xpath $PageModel.Xpath -Value "some surname"  
}

# create new page definition and save it to C:\deleteme\ps\SimplePage.Json
New-Page -Name "SimplePage" 
     | Add-PageElement -Name "TestButton" -Xpath "//*[@id='simpletests']" -Action Click
     | Add-PageElement -Name "FirstName" -Xpath "//*[@id='firstname']" -Action Input -Value "Person 1"
     | Add-PageElement -Name "Surname" -Xpath "//*[@id='surname']" -Action Code -Function "setSurname"
     | Add-PageElement -Name "Sex" -Xpath "//*[@id='sex']" -Action Select -Value "Female"
     | Add-PageElement -Name "Date" -Xpath "//*[@id='dob']" -Action Code -Value "22/01/2023"     
     | Save-Page -Path "C:\Deleteme\ps"  

Get-Page / Run-Page

# example scriptblock 
$beforeExecution = {
   param (
       [Parameter(Mandatory)]
       $PageModelCollectionObject
   )
   # do something 
}

$afterExecution = {
   param (
       [Parameter(Mandatory)]
       $PageModelCollectionObject
   )
   # maybe run some assertions 
}


# example function 
function setDate() {
   param (
       [Parameter(Mandatory)]
       $PageObject
   )
   # do something ;special 
   Set-Element 
}

# get the PsPageModelCollection Object previously created and saved  
$simplePage = Get-Page -Path "C:\Deleteme\ps\SimplePage"     
# start the page and populate elements definied in it.
# whenever an -Action of 'code' is encountered - execute the setDate function passing the 'current'
# PsPageModel object 
# before the page 'runs' execute the scriptblock (could be a function) $beforeExecution 
# after the page has run execute the scriptblock (could be a function) $afterExecution 
Start-Page -Page $simplePage -ActionCode ${function:setDate} -BeforeExecution $beforeExecution  -AfterExecution $afterExecution

# if you prefer you can use string representations of a function so :- 
# Start-Page -Page $simplePage -ActionFunction "somefunction" -BeforeExecutionFunction "someFunction  -AfterExecutionFunction "somefunction"
# this will scan existing funtcions (imported or otherwise) and execute the containing script

Examples

Create page and run it

Import-Module Nutstone.Selenium.Powershell

$beforeExecution = {
   param (
       [Parameter(Mandatory)]
       $PageModelCollectionObject
   )
   # do something 
}

$afterExecution = {
   param (
       [Parameter(Mandatory)]
       $PageModelCollectionObject
   )
   # maybe run some assertions 
}


# example function 
function setDate() {
   param (
       [Parameter(Mandatory)]
       $PageObject
   )
   # do something ;special 
   Set-Element 
}

Open-WebSession -Headless $false -LeaveBrowserRunning $true

Open-Url -Url "Http://A-UI-Implementation"

# get previously created page and change a property value  
$simplePage = Get-Page -Path "C:\Deleteme\ps\SimplePage" | Alter-Page -Name "FirstName" -Value "tom"     

Start-Page -Page $simplePage -ActionFunction "setDate" -BeforeExecution $beforeExecution  -AfterExecution $afterExecution

Close-WebSession

Installation

# installs nutstone.selenium.powershell package to the (first) powershell PSModulePath 
# NUGET must be installed and available in the enviroment path variable 

$packageName = "Nutstone.Selenium.PowerShell"
$location = $env:TEMP 
$source = "https://api.nuget.org/v3/index.json"

$latestVersionAll = nuget list $packageName -Source $source 

Write-Host "Found Package $($latestVersionAll)"

$latestVersion = ($latestVersionAll -split ' ') | Select-Object -Last 1  

# Install latest version to user's temp path 
nuget install $packageName -OutputDirectory $location -Version $latestVersion -Source $source -NoCache -DirectDownload

$sourcePath = "$($location)\$($packageName).$($latestVersion)"

Write-Host "Source path $($sourcePath)"

# get first psmodulepath (probably users/documents/windowspowershell)
$psTargetPath = $env:PSModulePath -split(';') | Select-Object -First 1  

$targetPath = "$psTargetPath\$packageName" 

If (!(Test-Path $targetPath)) {
    New-Item -Path $targetPath -ItemType Directory
}

# copy to nutstone.selenium.powershell
Copy-Item -Path "$sourcePath\*" -Destination $targetPath -Recurse -Force -Verbose

# check we can access the new module
Import-module -name Nutstone.Selenium.PowerShell