Squash TF Execution Server

Administration

Execution Server - Administration

Execution Server installation

Warning

In 2.3.0-RELEASE version of the server, we updated Jenkins to 2.190.1 version. Since 2.165 and newer version, Jenkins no longer supports the old (-remoting) mode in either the client or server. If you have installed a 2.3.0-RELEASE of the server and want to install an agent, you need to download 2.3.0-RELEASE (or newer) version of the agent.

Headless install

Linux procedure

Pre-requisites

• A version of the java 8 jdk must be installed on the system.

• The bin directory from this JDK must be included in the PATH shell variable. If necessary, run the following command in the shell you’ll be using :

  export PATH=</path/to/the/JDK>/bin:$PATH
  

Procedure

To perform a headless server installation under linux, you need to perform the following steps :

• Create the installation parameter file.
• Launch the installer from the command line with the installation paramameter file path as argument.

> Installation parameter file

The parameter file can be generated from the attached template. Please make sure to adjust the following parameters to the real values on your system :

• jdkPath : Path to a java 8 JDK that will be used to run the server.
• installPath : Target installation path for the Squash TF server

linux-headless-install-parms-template.xml

> Installer execution

To actually install the Squash TF server, please run the following command :

java -jar <path/to/the/>squash-tf-execution-server-bundle-<version>-linux-installer.jar <path/to/the/xml-installation-parameter-file>

Note

You can now access to your execution server at : <host_url>:8080/jenkins

The default login is : admin / admin

Windows procedure

Pre-requisites

• A version of the java 8 jdk must be installed on the system.

• The bin directory from this JDK must be included in the PATH shell variable. If necessary, run the following command in the shell you’ll be using :

  set PATH=<\path\to\the\JDK>\bin;%PATH%
  

Procedure

To perform a headless server installation under linux, you need to perform the following steps :

• Create the installation parameter file.
• Launch the installer from the command line with the installation paramameter file path as argument.

> Installation parameter file

The parameter file Can be generated from the attached template. Please make sure to adjust the following parameters to the real values on your system :

• jdkPath : Path to a java 8 JDK that will be used to run the server.
• installPath : Target installation path for the Squash TF server
• programGroup : Title for the Squash TF server submenu.

squash-tf-execution-server-auto-install-windows.xml

> Installer execution

To actually install the Squash TF server, please run the following command :

java -jar <path\to\the\>squash-tf-execution-server-bundle-<version>-win64-installer.jar <path\to\the\xml-installation-parameter-file>

Note

You can now access to your execution server at : <host_url>:8080/jenkins

The default login is : admin / admin

---

GUI install

Pre-requisites

• A version of the java 8 jdk must be installed on the system.

• The bin directory from this JDK must be included in the PATH shell variable. If necessary run the following command in the shell you’ll be using :

  • On Linux :

    export PATH=</path/to/the/JDK>/bin:$PATH
    

  • On Windows :

    set PATH=<\path\to\the\JDK>\bin;%PATH%
    

• Download the desired installer version of Squash TF Execution Server here

Procedure

1. Launch the graphical installer by a double click on the Squash TF Execution Server jar file, or launch it with the following command line :

   java -jar <desired-squash-tf-version>.jar
   

   Then you should have the language selection screen :

   

   • Choose the desired language for the installer then click on OK
   
   

2. The Welcome screen appears :

   

   • Click on Next
   
   

3. The JDK Path screen appears. This screen allows you to define the path where you java jdk is installed.

   

   • Choose the path where your jdk is installed.
   • Then click on Next
   
   

4. The Target Path Screen appears. It allows you to define the installation directory.

   

   • Define the installation directory (or keep the one proposed by default)
   • Then click on Next
   
   

5. The Select Installation Packages appears. It allows you to choose which package you want to install. Currently, you only have the choice to install or not the sahi proxy.

   

   • Do your choice
   • Then click on Next
   
   

6. The licenses information screen appears. It gives you all the informations concerncing the license of the product embedded

   

   • Click on Next
   
   

7. The Setup Shortcuts screen appears. It allows you to define your preferences concerning the shortcuts to create.

   

   • Click on Next
   
   

8. The installation tracking screen appears. This screen show you the progression of the installation.

   

   • When the installation is finished, click on Next
   
   

9. The Installation Finished screen appears :

   

   On this screen there is a button Generate an automatic installation script. It offers you to save an xml file which you could use to reproduce the same installation (with the same configuration you chose in the previous screens). See the headless installation procedure for explanations on how do a new installation using this xml file.

   • Then click on Done

Note

You can now access to your execution server at : <host_url>:8080/jenkins

The default login is : admin / admin

Congratulations ! You have installed the Squash TF Execution Server

---

Docker

With version 2.0.0 and above, Squash TF Execution Server also comes with docker images.

Since version 2.2.0 those images are also available on dockerhub : https://hub.docker.com/r/squashtest/squash-tf-execution-server

However, our images are still available as tarball in our repo (download at squashtest.com).

These images are fully parameterized execution servers ready to be deployed.

Below is the procedure to do so.

1. Retrieve the Docker image

   >> Retrieve from dockerhub

   docker pull squashtest/squash-tf-execution-server:{version}
   

   where {version} is the downloaded server version.

   >> Retrieve from our artifacts repository

   • Download the Docker image of the execution server here

   • Load the image on your Docker setup with the command :

     docker load -i squash-tf-execution-server.docker.{version}.tar
     

   where {version} is the downloaded server version.

   
   
   

   Warning

   Do not execute the “docker import” command on the image archive as it will flatten it and result in the loss of all context data such as entry points.

2. Use the following command to check the correctness of the previous load :

   docker images
   

   On successful load the output looks like :

   
   
   

3. Create a running container of the image using the “docker run” command

   >> Image from dockerhub

   docker run --publish 1234:8080 --name squash-tf-execution-server squashtest/squash-tf-execution-server:{version}
   

   >> Image from our artifacts repository

   docker run --publish 1234:8080 --name squash-tf-execution-server squash/squash-tf-execution-server:{version}
   

   Warning

   The difference between the 2 run command is in the image name. The dockerhub one is squashtest/squash-tf-execution-server:{version}, the other is squash/squash-tf-execution-server:{version}

   • The --publish option binds a port of the physical machine to the one of the soon to be created container. Here it binds the 1234 port of the physical machine to the 8080 port of the container. This is mandatory since the Jenkins installed on the image will listen to the 8080 of the container. If a Master/Slave architecture is planned you can open as many tcp port of the container as you wish by repeating the –publish option.
   • The --name option is optional, but quite handy since it allows one to give a non arbitratry name to the container about to be be created.
   

Note

You can now access to your execution server at : <host_url>:<host_bound_port>/jenkins

The default login is : admin / admin

Congratulations ! You now have a Squash TF Execution Server running inside a Docker container and ready to execute its first tests.

---

Once the container is properly created and running, use the docker stop command to shut it down :

docker stop squash-tf-execution-server

---

Use the docker start command to restart your server properly and retain your previous configuration and non-volatile data :

docker start squash-tf-execution-server

Execution Server - Update

Execution Server - Generic Update

Overview

This page will help you upgrade your Squash TF Execution Server and your job collection to the latest version available.

Its instructions are generic and need to be followed for each update; however the process can have additionnal steps for some versions.

These specific instructions are documented in their own sections of this guide.

Note

The following procedure is identical whether your Execution Server runs on a Windows or a Linux computer.

Warning

We recommend updating step-by-step from your current version of Squash TF execution server to the next until you reach the latest.

If you wish to jump ahead to the latest release please read carefully the instructions dedicated to each version of the Execution Server you pass by.

The guide is divided in 3 major parts :

• First the process to update a physical install of Squash TF Execution Server on a local system.
• Second the process to update a Docker install.
• Third the various configurations to update in Jenkins. This part is necessary for both install.

---

Physical Server update

Setup

1. Download the version of Squash TF you wish to install here.

---

2. Stop your current server.

---

3. Install the new TF Execution Server in a separate location as a classic new installation.

---

Server & jobs migration

4. Check the page dedicated to updating to the chosen version of the server and follow the specific instructions in the Before migrating jobs section.

---

5. Copy your custom jobs from {current_server_path}/execution_home/jobs/ to {new_server_path}/execution_home/jobs/

Warning

Do not copy Squash TF templates (beginning by 00) and SquashTAConditionSweepJobs, so avoid copying the whole jobs directory.

---

6. Copy and replace all .xml files from {current_server_path}/execution_home/ to {new_server_path}/execution_home/

---

7. Copy and replace the file server.xml located in {current_server_path}/apache-tomcat-8.5.16/conf/ to {new_server_path}/apache-tomcat-8.5.16/conf/

---

Optional steps

8. If you wish you can copy and replace the users directory from {current_server_path}/execution_home/ to {new_server_path}/execution_home/

Tip

If this step isn’t done the only user will be the administrator. By default -> login : admin // password : admin

---

9. If you wish you can copy Jenkins plugins you personally installed from {current_server_path}/execution_home/plugins/ to {new_server_path}/execution_home/plugins/

Caution

Be sure to not overwrite one of the plugins we provide with a newer or older version to ensure compatibility. You could also re-install your plugins using the Jenkins interface later.

---

TF - TM connection update

10. Copy and replace the file ta.linkConf.properties from the root of your old execution server to the root of your new one

---

Docker update

If your Squash TF Execution Server is deployed in a Docker container the updating procedure is slightly different.

In order to keep your Jenkins jobs parameterized and your custom Jenkins configuration, you will need to extract data from you old container (default name : squash-ta-server) and provide it to your new one.

Warning

We recommend creating a backup of your current Execution Server container before beginning the update process to prevent the loss of data.

Tip

The files to keep during the update are the same as those transferred during a physical install.

If you are an experimented Docker user you can choose your preferred method to access and move the data between your containers.

Simply follow the physical server update process to know what files and directories to keep and transfer over.

Note

In this guide we will assume the name of the container running Squash TF Execution Server and the path to the server’s files are the default (i.e. respectively squash-execution-server and /opt/squash-ta-server).

---

In this guide we will use the docker cp command exclusively to keep things simple but you could also use Docker Volumes or other means to access data from your containers.

The cp command can be used on a running container but we recommend stopping the Squash TF Execution Server container during the update process.

1. Copy the content of /opt/squash-ta-server from the container to the host system :

   docker cp squash-execution-server:/opt/squash-ta-server {path_of_choice}/squash-server-copy

---

2. Check the page dedicated to updating to the chosen version of the server and follow the specific instructions in the Before migrating jobs section.

---

3. Filter the execution_home directory located in squash-server-copy :

   • Keep the jobs and users directories and all .xml files before deleting all the other files and directories in execution_home. If you use Jenkins Agents, you can also keep the nodes directory. To do so, use the following command :

     rm -r {path/to/squash-server-copy}/execution_home/!(\*.xml|"jobs"|"users"|"nodes")
     

   • Delete the templates provided (beginning by 00 and SquashTAConditionSweepJobs) in the jobs directory.

---

4. Stop (if it was not already done) and rename your old Squash TF container to avoid naming conflict with the new one you will be creating shortly.

---

5. Download the newest version of Squash TF Execution Server Docker image from this page or on DockerHub.

---

6. Follow these instructions to launch the new Squash TF Execution Server.

---

7. Stop the new container for now :

   docker stop squash-tf-execution-server

---

8. Copy the content of {path/to/squash-server-copy}/execution_home to the execution_home directory in the new container :

   docker cp {/path/of/your/choice/squash-server-copy}/execution_home/. squash-execution-server:/opt/squash-ta-server/execution_home

---

9. Copy the server.xml file from {path/to/squash-server-copy}/apache-tomcat-8.5.16/conf/ in the /opt/squash-ta-server/apache-tomcat-8.5.16/conf/ in the new container :

   docker cp {/path/of/your/choice/squash-server-copy}/apache-tomcat-8.5.16/conf/server.xml squash-execution-server:/opt/squash-ta-server/apache-tomcat-8.5.16/conf/

---

10. Copy any other data you wish to transfer over to the updated execution server.

---

11. If you wish you can follow step 9 or 10 of the physical update process to keep any Jenkins plugins you may have installed and/or update your connection with Squash TM .

---

12. Use the docker start command to restart your server properly :

docker start squash-tf-execution-server

---

Jenkins configuration update

1. Start the new Execution Server and access the corresponding Jenkins page (login with an administrator account).

---

2. Go to Manage Jenkins followed by Configure system :

   • Find the section Global Pipeline Libraries and the subsection Source Code Management.
   • In the field Repository URL replace the path of your old version with the new one (everything before /execution_home/pipeline-libs/.. ).
   • Check that the Jenkins url is the right one for your new execution server (TM-TF link).
   • Click on Save.

---

3. Go to Global Tool Configuration :

   • Find the Maven section and click on Maven installations… if the section is empty.
   • In the field MAVEN_HOME replace the path of your old version with the new one (everything before /apache-maven-3.5.0).
   • Click on Save.

Empty Maven section

New path

---

4. If you have some of your own Jenkins plugins that you didn’t copy to the new plugin directory in the new execution server you can download them again at this time in the process.

---

5. In case of a TM-TF link remember to also check Jenkins url in Squash TM (Administration then Automation Servers) :

---

6. Check the page dedicated to updating to the chosen version of the server and follow the specific instructions in the After migrating jobs section.

---

7. Finally test your migrated jobs to confirm the update was successfull and your previously working jobs still behave as you want them to.

---

Jenkins Agents update

See here

Specific migration from 2.0.0 to 2.1.1

Before migrating jobs

Updating Jenkins users

Due to security updates on Jenkins LTS 2.107 and 2.138 your users will have to be updated prior to starting the 2.1.1 version of Squash TF Execution Server.

1. Delete the users directory from {new_server_path}/execution_home/
2. Copy the users directory from {current_server_path}/execution_home/ to {new_server_path}/execution_home/ (keep a backup copy somewhere)
3. Check that there is NO users.xml file at the root of the new users directory. It will automatically be created later.

The users’ updating process should automatically be done by Jenkins at the first start of the server, later in the generic process. You can comme back at this time to ensure the users’ update was successful :

• All the users are visible on the people page on Jenkins.
• A users.xml file should appear in the users directory of your new Squash TF Execution Server with the list of all your users.
• Each directory corresponding to a user should have a number following the user’s name.

For more details about this process visit the Jenkins upgrade guide for versions 2.107 and 2.138

Warning

This auto update is entirely managed by Jenkins. If you encounter any problem with your users (missing entries, bad API token or credentials…) we recommend retrying the process by stopping the server and doing steps 1 to 3 of this guide again.

Note

You could also recreate all the users from scratch. To do so, keep the users directory provided in a new install of the Squash TF Execution Server 2.1.1 instead of deleting it at step 2. Start the server to connect to Jenkins with the default administrator account (login : admin // password : admin) and recreate all your users from there.

Go back to the generic update procedure for now.

---

After migrating jobs

Verify users update

Prerequisites : You have followed the earlier instructions (in the Before migrating jobs section) to update Jenkins users.

Start your Squash TF Execution Server 2.1.1 and connect to Jenkins as administrator.

Go to Manage Jenkins then to Manage Users and check that all your users appear in the list :

If some of your users are missing you should stop the server, delete the users directory in execution_home (v 2.1.1) and copy again the old user directory (v 2.0.0) in its place (See **Before migrating jobs**).

Go back to Manage Jenkins then to Configure Global Security :

Check the authorization strategy used and verify the rights of each user in case of a matrix-based strategy.

If there is an error at this point you should retrieve a backup version of the 2.0.0 version of execution_home ( {old_server_path}/execution_home ) and copy the config.xml file to {new_server_path}/execution_home/.

(This config file is where the Jenkins authorization strategy is recorded).

Use an environment variable to define the maven local repository path

Overview

Previously, the local maven repository path was hardcoded by the installer during the installation process.

Starting from version 2.1.1 this path is define by using an environment variable. This change is not take into account by the generic migration and you have to do it yourself after.

Update the Maven Global Settings

Prerequisites : The generic migration should have been done.

Start your Squash TF Execution Server 2.1.1 and connect to Jenkins as administrator.

Go to Manage Jenkins then to Config File Management :

Open the file TF_MavenGlobalSettings and find the property <localRepository>.

Replace the line by :

<localRepository>${env.SQUASH_TA_HOME}/repository</localRepository>

and submit the changes.

Repeat this procedure for the file TF_Runners_MavenGlobalSettings.xml and submit again.

---

New reports publication settings

Overview

The jobs template settings for the reports publication have changed in Squash TF Execution Server 2.1.1. This change is due to a problem in the report publication url in Jenkins which was breaking the TM-TF link

This change have been made to all the templates.

Already existing jobs will have to be updated manually.

Note

These new reports publication settings are mandatory in case of a TF-TM link configuration and highly recommended in other cases.

Update existing jobs

In your job, go to Post-build Actions :

• Replace all the spaces in the Report title fields for each report generated by the job.
• Click on Publishing options under each report form.
• The checkbox Escape underscores in Report Title now needs to be unchecked.

Report forms before corrections

---

Report forms after corrections

---

Final step

When all the procedures have been done you should restart your Execution Server, then reconnect to Jenkins and check that all the corrections have been successfully implemented.

Specific migration from 2.1.1 to 2.2.0

Before migrating jobs

No particular task needs to be done at this point for this update. Go back to the generic update procedure for now.

---

After migrating jobs

New reports publication settings

Overview

Since Squash TF Execution Server 2.2.0, we have changed our jobs template settings for the reports publication. Now the publication is done according to the operation executed :

• If it’s a “list” operation, then we publish the tests list report.
• If it’s a “run” operation, then we publish the tests execution report.

The change have been made to these templates :

• 00Squash-TA_Template.
• 00Squash-TF-Java_JUnit_Runner_Template.

Already existing jobs will have to be updated manually

Note

This new reports publication settings is mandatory for tests projects using :

• Squash TFJava Junit Runner  : all versions.
• Squash TFKeyword framework (SKF)  : for version 1.13.0 and above.

Update existing jobs

Prerequisite

The Flexible publish plugin should have been installed in Jenkins (done in Squash TF Execution Server 2.2.0).

In your job, go to Post-build Actions and add a post-build action :

Select Flexible publish :

Configure the conditional action for the goal list as shown in the screen below :

Then add another conditional action and do the same for the goal run :

For jobs which run tests using Squash TFJava Junit Runner, also add the “Squash_TF_HTML_Debug_Report” in the goal run  :

Finally delete all previous post build actions for publication.

Note

As explain in the specific update documentation from 2.0.0 to 2.1.1, the report title should contain “_” (and not a space), and Escape underscores in Report Title should be unchecked.

---

Rename job execution according to the executed operation

Overview

In Squash TF Execution Server 2.2.0, we introduce the renaming of a job execution (according to the executed operation). To do so, we use the Jenkins Build Name and Description Setter plugin. This plugin sets the display name of a build to something other than #1, #2, #3, … so that you can use an identifier that makes more sense in your context (see image).

Update existing jobs

Prerequisite

The Build Name and Description Setter plugin should have been installed in Jenkins (done in Squash TF Execution Server 2.2.0).

In your job, go the Build Environment section and check the box Set Build Name.

In the Build Name, just add :

#${BUILD_NUMBER}-${operation}

Execution Server - Troubleshooting

Insufficient Cache warnings in catalina logs

During the launch of the execution server, you might encounter a warning message stating that a resource could not be added because there was insufficient free space available in your cache memory (see the full message in the example below) :

08-Jul-2019 16:04:23.575 AVERTISSEMENT [Loading plugin Environment Injector Plugin v2.1.6 (envinject)] org.apache.catalina.webresources.Cache.getResource Unable to add the resource at [/WEB-INF/classes/org/jenkinsci/plugins/envinject/Messages_en.properties] to the cache for web application [/jenkins] because there was insufficient free space available after evicting expired cache entries - consider increasing the maximum size of the cache

In order to fix this problem, you have to increase the cache max size. To do so, go in the Apache Tomcat Folder of your execution server and then go to the ‘conf’ folder.

Open context.xml and in the context block, add the following property :

<Resources cachingAllowed="true" cacheMaxSize="100000"/>

Execution Agent - Administration

Execution Agent installation

Squash TF Execution Server is Jenkins based. As such one can setup a master/slave architecture with clear separation of concerns. The Jenkins master schedules test related tasks whereas slave agents are solely responsible for their executions.

As the setting up of such architectures may be somewhat cumbersome, graphical agent installers are supplied as well as ready to run docker images.

Warning

In 2.3.0-RELEASE version of the server, we updated Jenkins to 2.190.1 version. Since 2.165 and newer version, Jenkins no longer supports the old (-remoting) mode in either the client or server. If you have installed a 2.3.0-RELEASE of the server and want to install an agent, you need to download 2.3.0-RELEASE (or newer) version of the agent.

Physical install

The graphical agent installers are meant for GNU-Linux-64 or Windows-64 environments. They will install and configure self-contained Jenkins Jnlp agents with Squash TF runners handling capabilities. More precisely they will :

1. Declare on the Jenkins master a new Jnlp node.
2. Retrieve the name and the secret of the created node.
3. Install the self contained agent and create a launch script.
4. Configure, on the Jenkins master, the newly created node properties such as the location of the embedded Maven.

Pre-requisites

The following pre-requisites are needed in order to perform the installation :

1. An open port on the Jenkins Master (Squash TF Execution Server) that can be used by the agent to connect to the master.
2. A Java Development kit 1.8 since, for licensing reasons, it is not possible to ship a our product with an embedded JDK.
3. A Java Virtual Machine with the corresponding environment variables JAVA_HOME, JRE_HOME and PATH set to launch the installer.
4. A Code source management client for the agent to retrieve tests sources code.
5. If GUI tests are in order, provide a way to keep active the graphical session. This may be a technical user account with the correct rights on Windows machines, or a X11 virtual frame buffer on GNU-Linux machines.

Procedure

Both Windows and GNU-Linux installers work the same. We display here below the common procedure :

1. The installers come as executable jar. So either double-click on the the jar or run the usual command :

   java -jar squash-tf-execution-agent-{version}-{os}.jar
   

   where {version} is the actual version of your execution server and {os} the operating system the agent will run on. One is then greeted by the following screen. Select the desired language and click on the OK button.

   

2. Fill in the installation directory and click on the next button.

   

3. Go through various non-ambiguous steps until you’re prompted to fill in the URL of your execution server.

   WARNING : Before going any further the Jenkins master should be configured so it allows “anonymous read access”. Indeed at this step the installer will try to interact with the Jenkins API. If anonymous reading is not allowed, the installer will consider that the given URL is false. To configure it :

   1. Log in administrator mode into Jenkins.
   2. Navigate to “Administer Jenkins/Configure global security”.
   3. In the “Autorisations” section, allow anonymous access reads.
   

   Once this is done, come back to the installer screen and fill in the Jenkins URL.

   

4. Fill in Jenkins administrator credentials, and verify the correcteness of the pair URL/credential by clicking the “Test” button.

   

5. Next the installer will perform the actual remote declaration of the node on the Jenkins master. Hence, the latter must be configured to accept remote control :

   1. Navigate to “Administer Jenkins/Configure global security”

   2. Autorise (temporarily) remote access to Jenkins CLI.

      

   3. Fill in the port onto which Jnlp agents can connect.

      

   4. Click the “save” button. An alert message should then appear stating that allowing remote access to the CLI is not safe. That’s normal. Just think to disable it after completion of this procedure.

      

   Once this is done, come back to the installer screen and click “next”. The following screen states that everything went well.

   

6. Go through the following steps until installation is finished.

7. The newly created agent node is now visible in the left Jenkins menu. It appears as disconnected. This is perfectly normal. Indeed the slave has not been launched yet.

   

8. Launch the agent by executing either {install-dir}\scripts\lauch.cmd on Windows or {install-dir}/scripts/launch.sh on GNU-Linux, where {install-dir} is the directory one chose to install the agent. “INFOS: Connected” is then displayed on the console signaling that the agent is launched properly.

   

   On the Jenkins master the created node appears now as at “rest”.

   

The procedure is reproducible for each agent node one wants to create. For security purposes, please ensure , once this is complete, to finally disable remote access to Jenkins CLI.

---

Docker setup

With version 2.1.0 and above, various Docker images of Squash TF Execution Agents are available.

Since the 2.2.0 version, our docker images are available from dockerhub : https://hub.docker.com/u/squashtest

However, our images are still available as tarball in our repo (download at squashtest.com).

Those come in three “flavors” :

• squash-tf-execution-agent : The base image.

  It brings the tools needed to be ran as a Jnlp agent and run headless Squash TF test. The image is built on the the open-jdk image and is thus Debian based. The image includes a JDK, a Maven, a Git client, a Mercurial client. And last but not least it contains the jars and configured entry-point to run it as a Jnlp agent.

• squash-tf-chrome-ui-execution-agent : Chrome-GUI testing specialized image.

  This specialization provides additionally a working graphical session and comes equipped with a guaranteed compatible Chrome/Chromedriver couple. The graphical stack is built using Xvfb as a fully in-memory X-11 server. Hence no graphical components should be needed on the underlying machine servicing the Docker host and running the images.

• squash-tf-firefox-ui-execution-agent : Firefox-GUI testing specialized image.

  Same as the chrome-ui image but comes with a guaranteed compatible Firefox/Geckodriver couple instead.

Credits : The docker images with in-memory X-server implementation is heavily based on work done by Stephen Fox.

Pre-requisites

The following pre-requisites are needed in order to perform the installation :

• A Jnlp open port on the Jenkins Master (Squash TF Execution Server) that can be used by the agent to connect to the master.
• A Docker compatible operating system on the machine(s) where the images will be running.
• A valid Docker installation with a Docker host.

Procedure

The setup procedure is flavor independent [1]. For the sake of example, screenshots displayed below are those from a Squash TF Chrome-ui agent setup.

1. The first step is to declare a new node in Jenkins administration section. Go to “Manage Jenkins/Manage Nodes” and click on “New Node” on the left panel.

   

---

2. Fill in wanted agent name and select Permanent agent radio button.

   

---

3. The images are built to use /home/jenkins/agent as the working directory. Thus fill in distant working dir section and Remote root directory with “/home/jenkins/agent”.

---

4. Add as many labels as you wish and a description if wanted. As the Jenkins documentation states : Labels (or tags) are used to group multiple agents into one logical group (..) Labels do not necessarily have to represent the operating system on the agent; you can also use labels to note the CPU architecture, or that a certain tool is installed on the agent.

   

---

5. The agent may not share with the execution server vital – for Squash TF tests executions – tools locations. The aforementioned locations can be overridden using the dedicated section and the following values :

   1. JDK home : /docker-java-home
   2. Maven home: /usr/share/maven
   

   To further clarify tools locations Mercurial and Git are to be found at :

   3. Mercurial : /usr/bin/hg
   4. Git : /usr/bin/git

---

6. The agent may not share with the execution server vital – for Squash TF tests executions – environment variables. Yet, the aforementioned variables are already set in the dockerfile. Hence, there is no need to redefine them in the concerned section. Nonetheless, for information purposes, here are the values of a few of these variables :

   1. JENKINS_HOME : /home/jenkins/agent
   2. SQUASH_TA_HOME : /home/jenkins/agents
   3. MAVEN_HOME : /usr/share/maven
   4. MAVEN_CONFIG : /home/jenkins/.m2
   5. JAVA_HOME : /docker-java-home

---

7. Click on the “save” button and note the secret of your newly declared node. The newly declared node should now appear as offline in the left panel.

   

   Click on the newly created node to retrieve its “secret” phrase. It will prove necessary when launching the agent.

   

---

8. You’ve finished the node declaration. Now you now have to download the agent docker image. Two possibilities :

   • using a docker images from dockerhub.
   • using a docker images package as tarball from our artifacts repository.
   
   

   >> Download the agent image from dockerhub

   To donwload the desired image :

   docker pull squashtest/squash-tf-{flavor}-execution-agent.docker.{version}
   

   where {flavor} corresponds to the type of agent you’re interested in and {version} is the version of the agent. We recommend you to choose the version corresponding to your Squash TF execution server for full compatibility. For the sake of information, the Jnlp agent jars used to build the base image are the one provided by Jenkins itself.

   
   

   >> Download the agent image from our artifacts repository

   1. Download the desired image here. Alternatively one can access the image directly from our repository using :

      wget http://repo.squashtest.org/distribution/squash-tf-{flavor}-execution-agent.docker.{version}.tar
      

      where {flavor} corresponds to the type of agent you’re interested in and {version} is the version of the agent. We recommend you to choose the version corresponding to your Squash TF execution server for full compatibility. For the sake of information, the Jnlp agent jars used to build the base image are the one provided by Jenkins itself.

   2. Load the downloaded docker image in your set up using the following command :

      docker load -i squash-tf-{flavor}-execution-agent.docker.{version}.tar
      

      where {flavor} corresponds to the type of agent you’re interested in and {version} is the version of the agent.

      It is to be noted that one should “NOT” use the docker import command as it will flatten all layers and will render unusable the image.

   The image should now be visible in your available docker images. This can be checked using :

   docker images
   

   

---

9. Finally run the docker image using :

   >> For the image from dockerhub

   docker run --name demo-tf-agent --user jenkins --env "JENKINS_AGENT_NAME={agent_name}" --env "JENKINS_SECRET={secret}" squashtest/squash-tf-{flavor}-execution-agent:{version} -url http://{jenkins_url}
   

   The command should be understood as following :

   1. docker run : Runs a docker container.
   2. –name demo-tf-agent : The nickname of the container that will be created. Can be chosen to one’s liking. If not set a random name will be assigned to the container.
   3. –user jenkins : The technical user with proper rights to run Jenkins.
   4. –env “JENKINS_AGENT_NAME={agent_name}” : Enables one to specify the name of the declared node in Jenkins. Modify {agent_name} accordingly.
   5. –env “JENKINS_SECRET={secret}” : Enables one to specify the secret of the declared node in Jenkins. Modify {secret} accordingly.
   6. squashtest/squash-tf-{flavor}-execution-agent:{version} : Selects the image one wants to run, where {flavor} is the type of image one is interested in and {version} the version targeted.
   7. -url http://{jenkins_url} : Enables one to specify the URL of the Jenkins master server.

   >> For the image from our artifact repository

   docker run --name demo-tf-agent --user jenkins --env "JENKINS_AGENT_NAME={agent_name}" --env "JENKINS_SECRET={secret}" squash/squash-tf-{flavor}-execution-agent:{version} -url http://{jenkins_url}
   

   The command should be understood as following :

   1. docker run : Runs a docker container.
   2. –name demo-tf-agent : The nickname of the container that will be created. Can be chosen to one’s liking. If not set a random name will be assigned to the container.
   3. –user jenkins : The technical user with proper rights to run Jenkins.
   4. –env “JENKINS_AGENT_NAME={agent_name}” : Enables one to specify the name of the declared node in Jenkins. Modify {agent_name} accordingly.
   5. –env “JENKINS_SECRET={secret}” : Enables one to specify the secret of the declared node in Jenkins. Modify {secret} accordingly.
   6. squash/squash-tf-{flavor}-execution-agent:{version} : Selects the image one wants to run, where {flavor} is the type of image one is interested in and {version} the version targeted.
   7. -url http://{jenkins_url} : Enables one to specify the URL of the Jenkins master server.

   Warning

   The difference between the 2 run command is in the image name. The dockerhub one is squashtest/squash-tf-{flavor}-execution-agent:{version}, the other is squash/squash-tf-{flavor}-execution-agent:{version}

   Once done, the node should appear as online on the Jenkins interface and its build queue should be in “idle”.

   

   The agent is now ready to execute its first Squash TF tests.

Particularity of graphical session providing docker images

The docker images with X11 have some particularities :

1. The latter images can be ran in “debug mode” using the –x11 vnc-debug option. In such a mode a VNC (Virtual Network Computing) server is also launched allowing remote access to the graphical session of the running container. If launched the server listen on port 5900. One should thus bind the container 5900 port to a physical port of the machine hosting Docker. The full command is then :

   docker run -p 5900:5900 --name demo-tf-agent --user jenkins --env "JENKINS_AGENT_NAME={agent_name}" --env "JENKINS_SECRET={secret}" squash/squash-tf-{flavor}-execution-agent:{version} -url http://{jenkins_url} --x11-vnc-debug
   

   Once the container launched in debug mode, its graphical session can be accessed using a VNC client targeting the Docker hosting machine on the binded port. For example using vncviewer :

   
   

---

2. Due to Chrome own limitations the user running it shoud be “Privileged”. This can be set using the –privileged options in the docker command. The command to run the Chrome flavor of the agent is then :

   docker run --name demo-tf-agent --user jenkins --privileged --env "JENKINS_AGENT_NAME={agent_name}" --env "JENKINS_SECRET={secret}" squash/squash-tf-chrome-ui-execution-agent:{version} -url http://{jenkins_url}
   

Both of these options can be run simultaneously.

Troubleshooting

Here is a non exhaustive list of possible slight configuration/integration issues.

1. Problems linked to tools : Java, Maven, git, mercurial is not found, problems while checking out project, etc… Jenkins master tools configuration may be interfering with the agent one. Try overriding their location using the “tools location” section in the node configuration page on Jenkins.

   

---

2. Something is wrong with the environment, cannot find any parasable pom, working directory is weirdly set. Jenkins master environment variables configuration may be interfering with the agent one. Try overriding their values using the “environment variables” section in the node configuration page on Jenkins.

   

---

3. Jenkins is not reachable since it is behind a firewall. Use the Jenkins anticipated mechanism and specify the environment variable –env “JENKINS_TUNNEL : HOST:PORT” for a tunnel to route TCP traffic to Jenkins host, when jenkins can’t be directly accessed over network

---

4. Our own tests revealed that too many layers of virtualization may render the use of the images unstable. For instance we found that on our setup, trying to run the images on the “virtualization sandwich” Windows 10/Virtualbox/Debian 9/Docker results in an immediate crash of the container without any further ado.

---

5. Time problems in reports. By default our containers are in UTC. This could lead to unexpected time value in the produced reports. You could solve this problem by specifying a timezone in your docker run command line. Example :

   --env "TZ=Europe/Paris"
   

---

6. When you execute a test with a job using the Chrome agent which fails when it tries to open Chrome, and you have an error stack which looks like :

   org.squashtest.ta.framework.exception.InstructionRuntimeException: Junit test execution for [engine:junit-jupiter]/[class:XXX]/[method:YYY] failed on error : unknown error: Chrome failed to start: crashed
   (unknown error: DevToolsActivePort file doesn't exist)
   (The process started from chrome location /usr/bin/google-chrome is no longer running, so ChromeDriver is assuming that Chrome has crashed.)
   

Then have you run your container in privileged mode as explain in the doc ? See : Particularity of graphical session providing docker images

---

[1]	No evident link has been found with Quantum Chromodynamics. Yet, we let the demonstration of the invariance under SU(3) transformations as an exercise to the reader.

Execution Agent - Update

Overview

Using a master-agent architecture to run your jobs in Jenkins can be done in a few combinations : depending on the platform on which your Execution Server runs (Windows, Linux, docker container) and on which the Execution Agents you wish to update will be, the procedure can be slightly different.

As such this guide will have a two parts structure :

• Tranferring nodes directory
• Jenkins configuration update

Each step in these parts will specify if it concerns the server or the agent, and each type of install (Windows, Linux, docker container) will be explained if there are differences.

---

Prerequisites

A Squash TF Execution Server up to date with the version you will update your agent to.

---

Transferring nodes directory

Tip

If you followed the Execution Server update process (physical or docker) you may have already transferred the nodes directory from the old Execution Server to the new one.

In that case you can skip ahead to the 4th step.

1. Stop your current Squash TF Execution Server and the Jenkins Agent you wish to update :

   • Using your method of choice in a physical install of the Execution Server (Linux or Windows).
   • Using the docker stop command in case your Execution Server is running in a docker container.

---

2a. On a physical install of the Execution Server simply copy the nodes directory from {current_server_path}/execution_home/ to {new_server_path}/execution_home/

---

2b. On a docker install of the Execution Server use the docker cp command to copy the nodes directory from your old container to the host system, then from the host system to the new container.

docker cp {old-container}:/opt/squash-ta-server/execution_home/nodes/. {path_of_choice}/nodes-backup
docker cp {path_of_choice}/nodes-backup/. {new-container}:/opt/squash-ta-server/execution_home/nodes

---

3. Restart your new Execution Server :

   • Using your method of choice in a physical install of the Execution Server (Linux or Windows).
   • Using the docker start command in case your Execution Server is running in a docker container.

---

4. Choose and download the version of the Squash TF Execution Agent you wish to install on this page.

---

5a. If you downloaded a physical installer of the agent :

Launch the installer of your new Squash TF Execution Agent and follow the setup procedure.

---

5b. If you chose to use our docker image :

• With the new Execution Server running connect to Jenkins as an administrator and click on the name of your old agent on the left of the screen.
• Recover the secret of the node and keep it for later.

---

Jenkins node update

For this section the new Execution Server should be running, either on your machine (Windows or Linux) or in a docker container.

You should also be connected to the corresponding Jenkins as an administrator.

The rest of the procedure will distinguish between a physically installed Agent and a an Agent in a docker container. The type of install of the Execution server is no longer important in this part.

Physical installer

1. Go to Manage Jenkins then to Manage Nodes.

---

2. Click on the cogwheel icon on the right of the agent of the agent your are updating to access its configuration screen.

---

3. In the field Remote root directory replace the path of your old version with the new one (everything before /workspace).

---

4. On the same screen find the section Node Properties and the sub-section List of tool locations.

---

5. In the field Home under (Maven) maven_ta replace the path of your old version with the new one (everything before /apache-maven-3.5.0).

---

6. Check that all your custom configurations are correct then click on Save.

---

7. Restart your Squash TF Execution Server and launch the agent, then run your jobs to make sure the update was sucessfull.

---

Docker image

1. Follow step 9 and step 10 from these setup instructions to link the agent container to the server container (you can read steps 1 to 8 for context).

---

2. Run your jobs on the updated Jenkins agent to make sure the update was successfull.

Use Squash TF Execution Server

Create a job in Squash TF Execution Server

NB : this procedure requires authentication with a user account with job creation rights

Choosing the template

The Squash TF Execution Server offers various templates, depending on the test you want to run.

You may make your choice according to the following table :

Test project	Template
Junit 4 based test project (including Selenium)	00Squash-TF-Java_JUnit_Runner_Template
Junit 5 based test project (including Selenium)	00Squash-TF-Java_JUnit_Runner_Template
Test project managed from Squash TM’s Gherkin Test cases	00Squash-TF-Cucumber_Template
Robot Framework test project	00Squash-TF_Robotframework_Template
Keywork Framework [1] test project	00Squash-TA_Template
Keywork Framework [1] test project with two execution phases [2]	00Squash-TA_Template-pipeline

Creating the job

Once you have chosen the appropriate template, create your job from this template through the New Item menu.

1. Enter a name for your test job

2. Type the name of the template in the Copy from field at the bottom of the new item page. Once you’ve begun to type auto-completion will trigger and you’ll be able to choose from existing templates, then click on the OK button to finish job creation.

   

Setting the job up

After creating the job, you have to set it up.

Setting a Squash TF job up (general case)

1. The main required settings for a Squash TF job are the Source Code Management parameters. The job needs to known how to get the test project sources. The illustration below shows the setup of a mercurial hosted project, but any SCM will do as long as it is supported in jenkins. Once you’ve entered the SCM parameters, hit the Save button.

   

2. The next - and last - step is to enable the job by clicking on the Enable button.

   

Setting a Robot framework job up

1. First you have to follow the general case setup describe below

2. For a job based on the Squash TF Robot Framework job template, one more configuration step is needed. As Robot Framework tests needs an execution environment with python, then by default the job is configured to only run on an executor which have the label robotFW. Out of the box Squash TF Execution Server doesn’t have any executor with this label. So before launch a Robot framework job you need to :

   • Have an execution environment with python and robot installed on it (on the master or on an agent) (see Squash TF Robot Framework Runner prerequisites for more details)
   • Give to this executor the label robotFW. To do so :
     • Click on Manage Jenkins (left menu)
     • Click on Manage Nodes (left menu)
     • Select the desired Node
     • Click on Configure (left menu)
     • In the Labels field add robotFW (multiple labels are separated by a space)
     • Click on the Save button

   You’re now ready to execute a RobotFramework job

   Note

   You may need to wait few minutes before Jenkins recognize this node as having the robotFW label.

Setting a two-phased Keyword Framework job up

Most parameters for the two-phased Keyword DSL pipeline are setup through the Environment injector plugin.

1. SCM parameters

   The first thing you’ll want to set is the SCM part.

   

   • SCM_CLASS : This first version of the pipeline only supports the use of the mercurial SCM. We plan to support other SCM providers compatible with the jenkins CSM plugin in the future : as they come up, you’ll be able to select other values for the SCM_CLASS parameter.

   • SCM_URL : As shown, you may specify a repository URL through the SCM_URL parameter (the pipeline pulls from branch default).

   • SCM_CREDENTIALS : This parameter holds a credential identifier. The value must match the ID of a registered jenkins credential record (see below).

     

2. SQL condition parameters

   The trigger of the second test execution phase is a SQL query. Here is how you may set this condition up :

   

   • SQL_CONDITION_TARGET : this parameter must match the name of a target defined by the Keyword Framework [1] test project.

     

   • SQL_CONDITION_QUERY : this parameter defines the SQL Query executed when evaluating the condition. It may be any SQL query that selects a unique value (one column, one row). More columns and rows may be fetched but they will be ignored. We advise you to avoid this and only fetch the expected value for clarity.

   • SQL_CONDITION_EXPECTED_VALUE : this parameter is compared to the query result. If they match, the condition is considered fulfilled and test execution resumes for phase two.

3. Selection of phase I and phase II tests Phase I and phase II tests are chosen among tests triggered by the received Squash TM execution order. They are picked using two filters. The default filters are, respectively :

   Phase	Filter definition	Selected tests
   I	**/sql-trigger/*precond.ta	Any test in a sub-directory named sql-trigger with a name ending with precond.ta
   II	**/sql-trigger/*postcond.ta	Any test in a sub-directory named sql-trigger with a name ending with postcond.ta

   As of now [3] , the only way to change this is to search the pipeline code for the **/sql-trigger/*precond.ta and **/sql-trigger/*postcond.ta strings, (each exists in one place only) and edit them. They follow the ant-like wildcard format, where * means ‘anything but the file separator, including an emtpy string’, and ** means ‘any thing, even path separators’.

   

[1]	(1, 2, 3) The Keyword Framework is the new version of our testing framework derived from the Squash TA DSL framework.

[2]	This pipelined job class allows an asynchronous wait between two test phases. Between these two test phases, the pipeline is active but no executor is allocated. The trigger for phase II is a SQL query. The current version only allows tests triggered from Squash TM.

[3]	changing the phase test filters will be made easier in the near future. This enhancement is planned for version 2.1.0-RELEASE, which should be published around April 2019.

Use a job based on Java Junit runner job template

Selecting the job

Once you’ve created a job using the Squash-TA Template, select it in the list of jobs available :

On the job’s page, you’ll be able to launch a build, access various informations regarding the job or make modifications.

Note

You’ll have to be logged in as an administrator to modify your job (rename, delete or configure) or to launch a build.

To launch a build, click on ‘Build with Parameters’ :

Setting the parameters of the build

You can then configure some of the parameters of the build :

Operation and TestList

You can specify two types of goals to execute in the ‘operation’ field: list or run.

> list : This will generate a json file listing all the tests present in your project.

This file is used by Squash TM in the context of the TM-TF link to determine the tests that can be executed.

> run : This will run all the tests specified in the ‘testList’ field or in a user created json file.

If you are using the TM-TF link, Squash TM will generate and transmit to Squash TF a testsuite.json file containing the list of tests to execute. In that case you don’t have to alter the field ‘testList’ or specify a json file.

Otherwise, if you want to provide manually to your run the list of tests to execute, you can procede in two ways :

• Enter the path to the tests you wish to execute (see this page for details on Junit tests naming scheme), separated by a semicolon (and no space after the semicolon), in the ‘testList’ field. You can also have the build execute all the tests present in you project, using : **/*.

• Provide a json type file (by clicking on the ‘Choose File’ button on the ‘testsuite.json’ line) containing the list of tests you wish to execute, and fill the ‘testList’ field with : {file:testsuite.json}.

  Exemple of each method :

  

Executor

If you want to launch the build on an Squash TF agent located on a distant machine and properly configured (see this page for the agent installation), enter the exact name of the agent, or its label, in the ‘executor’ field. Click on the ‘Show nodes’ button on the bottom right of the field to validate that you’ve entered a correct name :

Launching a build

Once you’ve specified the parameters of your build, click on the ‘Build’ button to launch the build.

Clicking on the dot (grey, red or green depending on the status of the build) next to the build name in the ‘Build History’ window will show the console output.

Build outputs

Test list

After the first list build has been performed, the generated ‘Test_list’ of the last list build executed will be available on the job’s page :

This is the json file fetched by Squash TM if using the TM-TF link.

HTML reports

In the same manner, the generated ‘Squash_TF_HTML_Report’ and ‘Squash_TF_HTML_Debug_Report’ of the last run build executed will be available on the job’s page :

If you click directly on a run build’s name, you’ll have access to its page with the corresponding run’s HTML reports :

---

Note

For more indepth details about the Junit runner, please consult its dedicated section.

Use a job based on Cucumber runner job template

Selecting the job

Once you’ve created a job using the Squash-TA Template, select it in the list of jobs available :

On the job’s page, you’ll be able to launch a build, access various informations regarding the job or make modifications.

Note

You’ll have to be logged in as an administrator to modify your job (rename, delete or configure) or to launch a build.

To launch a build, click on ‘Build with Parameters’ :

Setting the parameters of the build

You can then configure some of the parameters of the build :

Operation and TestList

You can specify two types of goals to execute in the ‘operation’ field: dryrun or run.

> dryrun : This will check if the tests specified in the ‘testList’ field or in a user created json file are runnable by Cucumber (meaning that they are implemented).

> run : This will run all the tests specified in the ‘testList’ field or in a user created json file.

If you are using the TM-TF link, Squash TM will generate and transmit to Squash TF a testsuite.json file containing the list of tests to execute. In that case you don’t have to alter the field ‘testList’ or specify a json file.

Otherwise, if you want to provide manually to your run the list of tests to execute, you can procede in two ways :

• Enter the relative path (to the root of your project) of a single test (.feature type file) you wish to execute in the ‘testList’ field. Alternatively, you can specify the path of a folder containing several test files. You can also have the build execute all the tests present in you project, by leaving the ‘testList’ field blank.

• Provide a json type file (by clicking on the ‘Choose File’ button on the ‘testsuite.json’ line) containing the list of tests you wish to execute, and fill the ‘testList’ field with : {file:testsuite.json}.

  Exemple of each method :

  

Executor

If you want to launch the build on an Squash TF agent located on a distant machine and properly configured (see this page for the agent installation), enter the exact name of the agent, or its label, in the ‘executor’ field. Click on the ‘Show nodes’ button on the bottom right of the field to validate that you’ve entered a correct name :

Launching a build

Once you’ve specified the parameters of your build, click on the ‘Build’ button to launch the build.

Clicking on the dot (grey, red or green depending on the status of the build) next to the build name in the ‘Build History’ window will show the console output.

Build outputs

HTML report

After the first build (dryrun or run) has been performed, the generated ‘Squash_TF_HTML_Report’ of the last build executed will be available on the job’s page :

The content of the HTML report will differ according to the type of build (dryrun or run) that has been executed.

If you click directly on a build’s name, you’ll have access to its page with the corresponding HTML report :

---

Note

For more indepth details about the Cucumber runner, please consult its dedicated section.

Use a job based on Robot Framework runner job template

Execute a job

Launching a build

Once you’ve created a job using the Squash TF Robot Framework job template, select it in the list of available jobs.

On the job’s page, you’ll be able to launch a build, access various informations regarding the job or make modifications.

To launch a build, click on Build with Parameters :

Setting the parameters of the build

You can then configure some of the parameters of the build :

> Operation and TestList

You can specify two types of goals to execute in the operation field : list or run.

• list : This will generate a json file listing all the tests present in your project. This file is used by Squash TM in the context of the TM-TF link.

• run : This will run all the tests specified in the testList field or in a user created json file. If you are using the TM-TF link, Squash TM will generate and transmit to Squash TF a testsuite.json file containing the list of tests to execute. In that case you don’t have to alter the field testList or specify a json file.

  Otherwise, if you want to provide manually to your run the list of tests to execute, you can procede in two ways :

  • Enter the path to the tests cases you wish to execute, separated by a semicolon (and no space after the semicolon), in the testList field. For the path, use the test suite and test case name provided in the json test list (generated by the list goal) to prevent problems. You can also execute all the tests present in you project by using in the testList field : **/*.
  • Provide a json type file (by clicking on the Choose File button on the testsuite.json line) containing the list of tests you wish to execute, and fill the testList field with : {file:testsuite.json}.

> Executor

If you want to launch the build on specific Squash TF agent executor, enter the exact name of the agent, or its label, in the executor field. In this robot framework template job, a default label robotFW is set by default (see Robot Framework job setup for explanation on this default label). Click on the Show nodes button on the bottom right of the field to validate that you’ve entered a correct name :

Start the build

Once you’ve specified the parameters of your build, click on the ‘Build’ button to launch the build.

Clicking on the dot (grey, red or green depending on the status of the build) next to the build name in the ‘Build History’ window will show the console output.

Build outputs

Test list

After the first build of type list has been performed, the generated Test_list of the last list build executed will be available on the job’s page :

This is the json file fetched by Squash TM if using the TM-TF link.

HTML reports

In the same manner, the Squash_TF_HTML_Report generated by the last run build executed will be available on the job’s page :

Those run html reports are also accessible directly in the run build’s page ( which is convenient for the historization) :

---

Note

For more indepth details about the Robot Framework runner, please consult its dedicated section.

Use a job based on TA / SKF job template

Selecting the job

Once you’ve created a job using the Squash-TA Template, select it in the list of jobs available :

On the job’s page, you’ll be able to launch a build, access various informations regarding the job or make modifications.

Note

You’ll have to be logged in as an administrator to modify your job (rename, delete or configure) or to launch a build.

To launch a build, click on ‘Build with Parameters’ :

Setting the parameters of the build

You can then configure some of the parameters of the build :

Operation and TestList

You can specify two types of goals to execute in the ‘operation’ field: list or run.

> list : This will generate a json file listing all the tests present in your project.

This file is used by Squash TM in the context of the TM-TF link to determine the tests that can be executed.

> run : This will run all the tests specified in the ‘testList’ field or in a user created json file.

If you are using the TM-TF link, Squash TM will generate and transmit to Squash TF a testsuite.json file containing the list of tests to execute. In that case you don’t have to alter the field ‘testList’ or specify a json file.

Otherwise, if you want to provide manually to your run the list of tests to execute, you can procede in two ways :

• Enter the relative path (to the ‘tests’ folder of your project) of the test files you wish to execute, separated by a comma (and no space after the comma), in the ‘testList’ field. You can specify the path of a folder containing test files, using : path/to/tests/*. You can also have the build execute all the test files (.ta, .txt or .test) in all the subfolders of the ‘tests’ folder of you project, using : **/*.{ta, txt or test}.

• Provide a json type file (by clicking on the ‘Choose File’ button on the ‘testsuite.json’ line) containing the list of tests you wish to execute, and fill the ‘testList’ field with : {file:testsuite.json}.

  Exemple of a user created json file :

  

Executor

If you want to launch the build on an Squash TF agent located on a distant machine and properly configured (see this page for the agent installation), enter the exact name of the agent, or its label, in the ‘executor’ field. Click on the ‘Show nodes’ button on the bottom right of the field to validate that you’ve entered a correct name :

Launching a build

Once you’ve specified the parameters of your build, click on the ‘Build’ button to launch the build.

Clicking on the dot (grey, red or green depending on the status of the build) next to the build name in the ‘Build History’ window will show the console output.

Build outputs

Test list

After the first list build has been performed, the generated ‘Test_list’ of the last list build executed will be available on the job’s page :

This is the json file fetched by Squash TM if using the TM-TF link.

HTML report

In the same manner, the generated ‘Squash_TA_HTML_Report’ of the last run build executed will be available on the job’s page :

If you click directly on a run build’s name, you’ll have access to its page with the corresponding run’s HTML report :

---

Note

For more indepth details about the Squash Keyword Framework, please consult its dedicated section.

Create a job

Use a job based on:

• Java Junit runner job template
• Cucumber Java runner job template
• Robot Framework job template
• SKF / TA job template

Associate Squash TM and Squash TF

Overview

Squash TF could be used as Squash TM automated test execution server.

The process is as follows:

• In Squash TM, select a list of test case and launch the execution
• Squash TM ask Squash TF to execute a list of automated tests
• Squash TF execute the list of test
• Squash TF generate a report
• Squash TF send back status and report to TM
• Results are then available in TM

Of course as prerequisite, you should have created the automated tests and associate them to the Squash TM test cases you request the execution.

Before using this process some configuration is needed on both part

Configure the TM - TF Link

Configure TF

Create a user with the rights to launch job execution remotely

On Squash TF Execution Server you have to create a user (ex : tmLauncher) able to launch remotely the execution of the job(s) who handle the tests.

• Login with a user having admin rights on your Squash TF Execution Server

• Go to Manage Jenkins \ Manage Users

• Click on Create User in the left menu

• Fill the field :

  

• Click on the button Create User

Note

This user credentials will be needed when you will define this automation server in Squash TM. Keep them near you.

Warning

By default Logged-in users can do anything strategy is selected for access control in Jenkins. You may want to use another access control strategy. To do so, go to Manage Jenkins \ Configure Global Security section Access Control. In such a case, don’t forget to give the rights to launch job execution remotely to the user we’ve just created.

Configuring Squash TM callback

When Squash TM asks the execution of automated tests to Squash TF Execution Server, the Squash TM request also contains it’s callback URL.

Squash TF Execution Server use this callback URL in two ways :

• As base url to send to Squash TM feedback about the progress of the execution
• To retrieve the right credentials to use to send feedback to Squash TM

On Squash TF Server side, the association between the callback URL and the credentials is done in a properties file. To modify this file:

• In your jenkins interface go to Manage jenkins / Managed files
• Edit the file taLinkConf.properties

• In this file, you should define an endpoint for each TM Server using this Squash TF Execution Server. For each endpoint you have to define the Squash TM callback URL and the credentials of a Squash TM User authorized to send feedback to Squash TM. For example a TM Server which callback URL is : http://myServer:8080/squash and the credentials are tmFeedbackLogin / tmFeedbackPassword then you should define the three properties below:

  endpoint.1=http://myServer:8080/squash
  endpoint.1.login=tmFeedbackLogin
  endpoint.1.password=tmFeedbackPassword
  

Note

The credentials associated to the callback URL are those of a user define in Squash TM. This Squash TM user should belong to the Test Automation Server group in order to have right to send feedback to Squash TM. See the TM configuration page for more details.

Warning

The callbackURL define in Squash TM configuration file should perfectly match the one define in your endpoint. If you wonder why, the answer is Squash TM put the callbackURL from its configuration file in the execution request it sends to Squash TF Execution Server. And this last one, use it to retrieve the good endpoint. So if they not match, no endpoint is found.

Configuring JENKINS_URL

Squash TF provides the URL of the execution report to Squash TM. To do so, the JENKINS_URL variable should be set as follows:

• Go to “Manage Jenkins / Configure system”
• In the “Jenkins location” section, set the correct value for the “Jenkins URL” property
• Click on “Save” or “Apply”

Note

When you first start Jenkins, even if the “JENKINS_URL” field contains the right value, you have to click on “Save” or “Apply”. Otherwise the JENKINS_URL property won’t be set.

Configure TM

Configure Squash TM properties

1. Open the squash.tm.cfg.properties file located in the conf folder of Squash TM installation folder (ex: C:\Squash-TM\conf).
2. Find the line with tm.test.automation.server.callbackurl and uncomment it
3. Add the url of Squash TM (ex: http://192.168.2.138:8080/squash). This url will be used by Squash TF Server to notify Squash TM of the execution progress.
4. Restart Squash TM.

Warning

The Squash TM URL used in this configuration should be accessible from Squash TF Server location

Warning

If you update this Squash TM callback URL, then don’t forget to update all the Squash TF execution server using this endpoint

Create a Test Automation Server user

In Squash TM there is a special user group called Test Automation Server which has the right to send automated test execution feedback to TM from the outside. To link a Squash TM server with a Squash TF server, you have to create a user which belong to this special group. To do so :

1. In Squash TM, click on the link [Administration] (in the upper corner) then click on [Users].

2. Add a new user with the button [Add New User]. The [Add User] popup shows up :

   

3. In the Group ComboBox choose Test Automation Server.

4. Fill the Login field with the login you have configured in the Squash TF conf.properties file.

5. Fill the Password field with the password you configured in the Squash TF conf.properties file.

Warning

The credentials of this user is used on Squash TF side to define the endpoint in the conf.properties. If you update the credentials of this user, then don’t forget to update the execution server endpoint which use it.

Add a Squash TF Execution Server to Squash TM

1. In Squash TM, click on the link [Administration] (in the upper corner) then click on Automation servers

2. Add a new server with the button [Add a server]

3. The [New test automation server] popup shows up :

   

4. Fill the URL field with the Squash TF url (ex : http://192.168.2.138:9080/jenkins).

5. Fill the Login field with the login of the user in Squash TF dedicated to automation.

6. Fill the Password field with the password of the user in Squash TF dedicated to automation.

7. If you use a Master server with slave(s), you can check the Manually choose the server at execution lanching (Implies this server is a master one) checkbox. This option will allow you to choose, each time you run your tests, on which agent they run.

8. If you want to add another server, click [Add another] and repeat steps 4-8, otherwise click [Add].

   Attention

   Login must be unique for each URL.

Configure a Project to use automation

> Link an Automated Server to a Project

1. Click on the link [Administration] (in the upper corner) then click on [Projects].

2. Select an existing project, scroll down to Test automation management.

   

3. Click on No server. You’ll see the list of available servers.

   

4. Choose the server and [Confirm].

5. In the Test automation management you should see a new part called Jobs.

> Link a Squash TF job to a Squash TM project

1. Click on the link Administration (in the upper corner) then click on Projects.

2. Select an existing project with an automation server associated, scroll down to Test automation management.

   

3. Click on [+]. The New job popup will shows up with all the jobs you have in Squash TF.

   

4. Select the job(s) you want to add. You can change their label in Squash TM (by default the name are the associated Squash TF job name).

   

   Attention

   Job’s name can’t be blank and must be unique.

5. Click [Confirm].

6. You can edit your job (pencil button) if you want to further configure it.

   

7. In the field Possible execution servers, you can choose which slaves servers can be used for this job. Type their name separated with semicolon (ex: SlaveServ1; SlaveServ2).

   Attention

   The Possible execution servers field is only for SLAVES servers, the master will alway be displayed in the list of possible servers.

> Enable Gherkin execution for a job

When you linked a Squash TF job to a Squash TM project, by default in the job configuration in TM, the Can run Gherkin option is set to No. In order to this job can run gherkin you have to enable it.

1. In the project administration page section Test automation management, edit your job (pencil button) :

   

2. Check the box Can run gherkin

   

3. Click on Confirm

   

Now the project is related to Squash TF server. In this project you can relate automated test script to TM test cases. You can then execute these automated tests from the campaign space and read their execution results.

• Configure Squash TF: Configure TF
• Configure Squash TM: Configure TM

Overview

Squash TF Execution Server is our server to execute test on distributed environments

It use the master - agents architecture :

• the master: It’s the scheduler which handle the jobs to execute.
• the agents: The handle execution on multiple environments or technologies:
  • environments: development, acceptance, integration, …
  • technologies:
    • OS : windows /linux
    • Browser : chrome/firefox/…

---

Your jobs are on the master. We provide some sample jobs you can duplicate to create your project job according to the type of execution you want to do. See usage part of the documentation for more information on job creation. In this job we define :

• Your job parameters
• The way to retrieve your automated tests project sources
• The command line to execute your test
• The post action to publish the reports

---

Squash TF is based on jenkins which bring us all its ecosystem capacity:

• scm connectors (git, mercurial, svn, …) to retrieve tests project sources
• distributed execution through master agent architecture
• pipeline
• report publishing
• API Rest for job remote launch