# Powershell

How to set up a PowerShell agent can be read in the chapter [Automation Agent; Creation & Configuration](/documentation/automation/web-client/automation-agent/creation-and-configuration.md). 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.

<figure><img src="/files/zG5kAHUDBWHyRkSaIPyb" alt=""><figcaption><p>Adding PowerShell script</p></figcaption></figure>

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:

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

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

```powershell
param($variables, $tempDir, $aquaCallback)
```

{% hint style="info" %}
Note that all used variables must be declared in a single “param” command.
{% endhint %}

Sample script using those objects:&#x20;

<mark style="color:blue;">**# Sample PowerShell script that uses .NET objects and TC variables from aqua**</mark> <mark style="color:blue;"></mark> &#x20;

{% code overflow="wrap" %}

```powershell
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  
}
```

{% endcode %}

<mark style="color:blue;">**#Request Test Execution information via**</mark> <mark style="color:blue;">**$aquaCallback.GetExecutionInfo()#Returns an object with ProjectId, TestCaseId, TestExecutionId, \[TestScenarioId and TestScenarioExecutionId]**</mark>&#x20;

{% code overflow="wrap" %}

```powershell
$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
```

{% endcode %}

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

**# SUTError, ScriptExecutionError, PreparationError, ExecutionError, InformationalInfo, InformationalDebug, InformationalWarn, InformationalSuccess** &#x20;

{% code overflow="wrap" %}

```powershell
$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");   
}  
```

{% endcode %}

<mark style="color:blue;">**# Return status of script execution. One of: Ready, Blocked, Fail, Aborted**</mark>**&#x20;** return "Ready" &#x20;

<figure><img src="/files/2cwoTKb1zfAcSRi778Ql" alt=""><figcaption><p>Powershell automation script</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aqua-cloud.io/documentation/automation/web-client/powershell.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.