PowerShell

PowerShell agent exposes several objects available for PowerShell scripts:

• Variables – array of aqua.ProcessEngine.WebServiceProxy.VariableValue objects containing TC variables (and their values) used for execution. Name and Value are the most important properties of VariableValue.

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

• aquaCallback – reference to AquaShellCallbackHelper object that can be used to communicate with aqua from PowerShell script. Available functionality includes:

• sending log messages to aqua (also with screenshots)

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

• 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 stop in 5 seconds after the flag is set, the agent does force 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, a 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  
}
# 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"  

Execution Status

PowerShell's 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.

Please note that execution status is only visible in WebClient.

# 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)
 
Two automated steps 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 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")