UnixShell

The UnixShell-Agent allows to execute a Shell-Script on a remote Unix (Linux) machine. In order to setup the Unix-Shell-Agent, please follow the next steps.

Setup

The following steps require fundamental knowledge about the UnixShell. The given commands are not guaranteed to work on any Unix (Linux) distribution and need to be adopted according to your distribution.

• Create an automation agent in aqua and write down the Access key (also known as Agent code)

• Check if Java is installed on the target Unix (Linux) machine, e.g. by running the following command: java -version The result should be similar to the following screenshot:

  

If java is not installed on your target machine, you can install java by following the guidelines for your Unix (Linux) distribution. As an alternative, you can download a java runtime environment (jre) as *.tar.gz package and untar it to a folder of your choice. The following commands are examples for an Ubuntu distribution:

mkdir /usr/java
cd /usr/java
tar zxvf <path-to-your-java-tar.gz>

Upload aqua UnixShell-agent to your Unix (Linux) machine and unzip it to a folder of your choice (e.g. using unzip command in Ubuntu that can be installed via sudo apt-get install unzip).

cd /usr
unzip <path-to-UnixShell-agent-zip-file>

Edit the file agent.properties (e.g. using command nano) and change the line agentCode (see step 1) as well as aquaServiceUrl so that the agent can communicate with your aqua Server.

cd <path to agent folder>
nano ./agent.properties
 

An example can be seen below.

If you installed java following the alternative approach as described in Step 2, please edit the file agent.sh and adopt the path to the java command.

Please note the option to run agent in window-mode. This might be suitable for Unix (Linux) machines that have a GUI installed.

Make the file agent.sh executable.

sudo chmod +x ./agent.sh

Start agent by running agent.sh.

cd <path to agent folder>
./agent.sh

When an exception occurred, please check file agent.properties again, if agentcode and aquaServiceUrl is set properly.

In aqua, you should see a green indicator for your agent.

Writing Shell-Scripts that return results to aqua

In order to run a UnixShell-Script in aqua, create a new test case, open Step Designer and select tab Automation. Select the test step (click the empty space of the given step) and add a new Unix shell-Script via New Script-Button.

In the Script-area of the step, you are able to insert the script to be run on the remote machine. An example is given below:

##################
#!/bin/bash
# Sample bash script
 
# everything that is written to the console is send back to aqua
echo "script is running"
 
# Access variable named VAR1
echo "$AQUA_VAR1"
 
# files that are stored in subfolder toAttach are send back to aqua (below are two examples)
# Example 1: Attach a file named test.txt to the execution (touch creates a new file in subfolder named -toAttach-)
touch ./toAttach/test.txt
 
# Example 2: in order to upload files, you can also copy a file to be uploaded to the subfolder -toAttach-
# Syntax: cp <filePath> ./toAttach
cp /tmp/screnshot.png ./toAttach
 
# Return the execution result: 0 means Passed. Everything else means Failed
exit 0
##################
 

When you are done with your script, you can save and run your test case.

For execution, a new subfolder is created in temp-Folder of the agent. In this subfolder, another subfolder toAttach is created automatically so that you are able to upload attachments as given in the example. If you want to see the temp-Folder after execution, please set deleteTempFiles=false in file agent.properties and restart your agent.

Limitations

• Images can be uploaded as attachments. However, uploading images so that they are directly visible in the aqua execution log is not possible so far.

• Complete output of the console is written to the last step in the execution log and not written as multiple execution log entries.

• As a consequence of limitation 2, you can not control the log level of a single execution log message.