PowerShell

How to set up a PowerShell agent can be read in the chapter Creating an Automation Agent. 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'.

If you now select PowerShell, a sample PowerShell script is automatically inserted. In the sample script you can easily understand the functionalities provided by the PowerShell agent. You can then further customize the script or replace it directly with other scripts.

Here is some more information on the objects and functions provided by the PowerShell agent 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 includes:
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, 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 oject 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"

Upload File

Using the Upload file button, you can add files to the automated PowerShell step, which are then automatically downloaded during execution and stored in the temp folder of the agent in which the script is also executed. This allows you to easily use these files within the script.

In addition, files can also be uploaded during script execution and attached to the execution. This is done with the following call: $aquaCallback.AddExecutionAttachment("Filepath")

Execution Status

PowerShell automation provides the capability to set an execution status of a given list of parameters that can be updated from time to time. This is helpful if you have a long running test execution and want to show an intermediate status in aqua, e.g. progress in percent or number of checks performed so far. Sample code how to do this is given below.

# sending multiple values as execution status

$attributes = @()

$attribute = New-Object aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttribute

$attribute.AttrName = "dummy"

$attribute.AttrType = [aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttributeType] "Integer"

$attribute.AttrValue = "14"

$attributes += $attribute

$attribute = New-Object aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttribute

$attribute.AttrName = "dummy2"

$attribute.AttrType = [aqua.ProcessEngine.WebServiceProxy.ExecutionDataAttributeType] "String"

$attribute.AttrValue = "HelloWorld"

$attributes += $attribute

# if second parameter is true, execution status is replaced entirely with the given array. In contrast, false does a partial update

$aquaCallback.AddExecutionData($attributes, $true)

# sending single value as execution status

# $aquaCallback.AddExecutionDataString(string name, string value)

$aquaCallback.AddExecutionDataString("Progress", "50%")

# $aquaCallback.AddExecutionDataInteger(string name, int value)

$aquaCallback.AddExecutionDataInteger("No. of Checks", 50)

Transfer information between steps

Two automated step in aqua are running independent of each other. Thus, you are not able to access data from one automated step in a subsequent step by default. To solve this issue, you can use the execution status to hand over some data from one automated step to another.

# $aquaCallback.GetAllExecutionAttributesInExecution()

$allAttributes = $aquaCallback.GetAllExecutionAttributesInExecution()

# $aquaCallback.GetExecutionAttributeInExecution(string attributeName)

$progress = $aquaCallback.GetExecutionAttributeInExecution("Progress")

# $aquaCallback.GetExecutionAttributeValueInExecution(string attributeName)

$noOfChecks = $aquaCallback.GetExecutionAttributeValueInExecution("No. of Checks")

Here is a minimal example for the transfer and output of a string between two steps:

In step 1:

$aquaCallback.AddExecutionDataString("SharedStringVariable","this is the content of the string variable from step 1")

In step 2:
$aquaCallback.SendMessage($aquaCallback.GetExecutionAttributeValueInExecution("SharedStringVariable"),[aqua.ProcessEngine.WebServiceProxy.ExecutionLogMessageType]::InformationalInfo, "my category");