Powershell

How to set up a PowerShell agent can be read in the chapter Automation Agent; Creation & Configuration. The PowerShell agent is required for executing a test case with PowerShell scripts.

To add a PowerShell script to a test case, open a test case and navigate to step designer. Switch to the tab 'Automation'.

When you select PowerShell, a sample PowerShell script is automatically inserted. You can use the sample script to easily understand the functionality that the PowerShell agent provides. You can then further customise the script or replace it directly with other scripts.

Adding PowerShell script

Here is some more information about the objects and functions that the PowerShell agent provides for PowerShell scripts:

• variables – array of objects containing TC variables (and their values) used for execution. Name and Value are the most important properties of each object.

• tempDir – string variable containing path of the temporary directory where the script attachments have been saved (if applicable).

• aquaCallback – reference to AquaShellCallbackHelper object that can be used to communicate with aqua from within the PowerShell script. Available functionalities include:

  • sending log messages to aqua (also with screenshots)

  • sending attachments to aqua (saved as attachments in the execution object)

  • sending execution status via AddExecutionData

  • retrieve test execution information (Ids of project, test case, test execution, test scenario, test scenario execution)

• StopRequest property - set by agent on abort requests received from aqua. Long-running scripts should periodically check this flag and stop gently in case when set. If not stopped in 5 seconds after the flag is set, the agent does a forced stop of the running script.

To call nunit by PowerShell, you can use commands like:

$output = & $nunitLocation $testDll --test=$testCaseName 2>&1

To use exposed objects, PowerShell script needs to declare their usage by issuing the following command:

param($variables, $tempDir, $aquaCallback)

Note that all used variables must be declared in a single “param” command.

Sample script using those objects:

# Sample PowerShell script that uses .NET objects and TC variables from aqua

param($variables, $tempDir, $aquaCallback)  
$text = new-object System.Text.StringBuilder  
$date = [System.DateTime]::Now  
$text.AppendLine($date.ToLongDateString())  
$text.AppendLine($date.ToLongTimeString())  
echo "$text" > script-sample.log  
foreach ($var in $variables)  
{  
    $varName = $var.Name  
    $varValue = $var.Value  
    echo "Variable: $varName : $varValue" >> script-sample.log  
}

#Request Test Execution information via $aquaCallback.GetExecutionInfo()#Returns an object with ProjectId, TestCaseId, TestExecutionId, [TestScenarioId and TestScenarioExecutionId]

$executionInfo = $aquaCallback.GetExecutionInfo()                                                             
Write-Output "Project ID: $($executionInfo.ProjectId)" >> script-sample.log
Write-Output "TestCase ID: $($executionInfo.TestCaseId)"  >> script-sample.log
Write-Output "Execution ID $($executionInfo.TestExecutionId)" >> script-sample.log
Write-Output "Scenario ID (when run in scenario): $($executionInfo.TestScenarioId)" >> script-sample.log
Write-Output "Scenario Execution ID (when run in scenario): $($executionInfo.TestScenarioExecutionId)" >> script-sample.log

# Possible Types of [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]

# SUTError, ScriptExecutionError, PreparationError, ExecutionError, InformationalInfo, InformationalDebug, InformationalWarn, InformationalSuccess

$aquaCallback.SendMessage("hello, I was sent from script", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
$aquaCallback.SendMessageWithScreenshot("and this is Screenshot", "c:\sample.jpg", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
dir $tempDir >> script-sample.log  
$aquaCallback.AddExecutionAttachment("script-sample.log");  
while ($true)  
{  
    if ($aquaCallback.StopRequest)  
    {
        $aquaCallback.SendMessage("Aborting on StopRequest", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
        return "Aborted"   
    }  
    Start-Sleep -s 10  
    aquaCallback.SendMessage("Looping in PowerShell…", [aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalWarn, "my category");   
}  

# Return status of script execution. One of: Ready, Blocked, Fail, Aborted return "Ready"

Powershell automation script