Module 6 – Using Source Code Control to Manage Our Test Artefacts

In this final module we’re looking how we can best control all of our test resources and files. We’ve created Selenium, SoapUI and JMeter tests. The files for all of these tests are now scattered all over our distributed test automation environment. Not great for colloaboration, maintaining versions and backups. Down right dangerous really.

What we need to do is pull all of our files together into one central repostiory. Well, with the tool we’re using, Git, it’s more a central distributed repostiory. ‘Central distributed repository’ sounds like a bit of a contradiction. We’ll explain that contradiction as we go through this.

Anyway, we’ll be running up an Amazon Liniux instance and installing the source code management tool, Git. Then on all our client machines and our master Windows machine we’ll install the Git client. This will enable us to store and maintain all our test files across our automation network.

To configure this we’ll need to cover 5 key areas:

  1. Setting up and configuring our Git Source Code Control server
  2. Configuring our Source Code Control clients (both Windows and Linux)
  3. Adding our test files to our Git Source Code Control repository
  4. Updating our Jenkins jobs to use test files from the Git repository
  5. Modifying our test files and updating files in our Git repository

With all of this in place we’ll have the last piece of our jigsaw complete. We’ll have the Git component implemented as shown in our schematic here:

Test Automation Framework

The important concept to grasp here is that we’re managing our ‘test’ source code. We’re not managing our ‘development’ source code. The development source code is managed by our development team. We need to meet the same levels of good development practice that our dev team employ. And that means we’re responsible for managing our test artifacts and source code properly.

What You’ll Learn

The aim is to pull all our test files together and manage them effectively from one location. That means pushing any changes to this central location or “repository” as it’s better known. This means getting our Jenkins jobs to automatically use the test files stored in this repository. And it means learning to collaborate on changes to test files by making those changes easily accessible to everyone in your team.

The concept then is that every test file we create needs to be stored in our Git source code repository. That means, from our SoapUI, JMeter and Selenium development environments any code we write needs to be ‘pushed’ and stored on our Git server. When ever Jenkins comes to run a job it will be responsible for ‘pulling’ this source from Git server. This way the Jenkins server will always be picking out the latest test source files that anyone in our test team has checked into the Git repository (assuming our test team are diligent about pushing their changes to the Git repository that is).

What Jenkins actually does, when it initiates the jobs on the remote machines, is get it’s Jenkins slaves to pull the latest version of the test files from the Git repository. So whilst we’ll configure the jobs on the Jenkins server to use Git it’s actually the Jenkins slaves that are responsible for pulling our test files from the Git server.

All that we’re aiming for though is making sure everyone, including Jenkins, is using the right files from the right location. To goal to ensure that we are developing our tests in a collaborative environment where we’re using the right versions of the test files in our test environment and we have all of our test artifacts and files safely stored and backed up.

The SCM Tool We’ve Chosen

As we’ve already mentioned we’ve chosen Git. Git isn’t an “unpleasant or contemptible person” as the dictionary definition points out. Git is version control system that will store all our test artifacts or files. Git maintains a changes to those files over time so that we can revert to previous versions if we need to. All our changes are tracked so that we can see what changes were made, when and by who. Why’s this important?

Well take that scenario where your colleague makes a small innocuous change to a Selenium script. Nothing radical but when you come to run the latest version of the this automation script nothing works anymore. Well with Git we can see exactly what the change was and revert back quickly to the working version.

Why have we chosen Git in particular? Well it’s the de facto open source, source code repository tool. It’s one of, if not ‘the’, most popular source code control tool in use today. It’s an open source project that’s still actively maintained even though it was started back in 2005. Not only that, but there’s a massive amount of material (free books, free videos, etc) on the web to help you learn more once you’ve finished learning the basics here.

Prerequisites

Make Sure you have your Private key (.pem file)

Back in Module 1 we created our public and private key pairs? Well at that stage you should have saved your private key pair .pem file (e.g. FirstKeyPair.pem) file. You’ll need this private key when configuring Jenkins later.

If you don’t have have this private key you can go back and create a new key pair. Much easier if you can find the one you created in Module 1 though.

If you’ve followed upto Module 4 so far you should already have your Amazon Virtual machine environment up and running along with Jenkins, Selenium and SoapUI. This existing setup gives us the 2 machines we’ll need to use in this module.

  1. Windows Master machine: this is running Jenkins and controls all our other machines (including the installation of the AUT and the execution of our Selenium tests). This machine will be responsible for kicking off our SoapUI API tests
  1. Linux Client machine: this Ubuntu linux machine is run up on demand by Jenkins and then has the AUT (Rocket Chat) automatically installed on it. This machine provides the web interface for the Rocket Chat application and the API for the Rocket Chat application.

Check the Status of your AWS Machines

Your Windows Master machine should already be running. The Linux machine (running the Rocket Chat application) may or may not be running. The Linux machine is run up automatically by Jenkins so it’s fine if it’s not running right at this moment. Whatever the state of the linux machine you should see the Windows machines status in the AWS console as follows:

 

 

Open an RDP Terminal Session on the Windows Master Machine

With these Windows machines running you’ll need to open an RDP session on the Windows Master machine. This is where we’ll configure Jenkins.

 

 

Then enter the password (you may need your .pem private key file to Decrypt the password if you’ve forgotten it) to open up the desktop session.

Start the Linux Client Machine

IF the Linux machine isn’t running with the AUT installed then we need to start it. We can get Jenkins to do this for us. Once you have an RDP session open to your Windows Master machine you should have the Jenkins home pages displayed. If not open a browser on this machine and go to this URL:

 > http://localhost:8080/

From here you can start the ‘BuildRocketChatOnNode’ job and start up the AUT.

 

Once RocketChat is up and running we’ll need to know the host name that Amazon has given our new Linux instance. We save this in our ‘publicHostname.txt’ file that is archived as part of our build job. So if you go to this directory using Explorer

C:\Program Files (x86)\Jenkins\jobs\BuildRocketChatOnNode\builds\lastSuccessfulBuild\archive

You should find this publicHostname.txt file…

 

Open this with notepad and make a note of the hostname. We’ll need this while we configure our performance tests.

At this point you should have…

  1. A copy of your your Private key (.pem file)
  2. An RDP session open to your Windows Master machine
  3. Your Linux Ubuntu machine running with Rocket Chat installed

From here we’ll setup a new Linux/Unix Ubuntu machine that will hold our Git repository.

Part 1: Sart a Unix Ubuntu Git SCM Server

First we need a Linux AWS server that will run our Source Code Management (SCM) tool Git. We’ve done this a few times before now so we’ll step through the AWS Linux server configuration quickly.

The other Linux machines we’ve setup in this course are designed to be started automatically by Jenkins on demand. Slightly different with this Linux machine. We need a machine that’s not started by Jenkins, that’s always on, has ??? storage (not emphiperal?) and is protected from being shut down.

  1. In the Amazon AWS interface launch a new instance (click on a Launch Instance button). Select the ‘Free tier only’ option and configure this new AMI with the following parameters:

STEP 1 : Amazon Machine Image
AMI ID: ami-9abea4fc *1

STEP 2 : Instance Type
Instance Type: T2Micro

STEP 3 : Instance Details
Select all the defaults and
Protect against accidental termination: <checked> *2

STEP 4 : Storage
Type: Root
Size: 8GiB
Volume Type: General Purpose SSD
Delete on Termination: <checked>

STEP 5 : Tag Instance
Key: Name
Value: Unix-Git

STEP 6 : Security Groups
Select an existing security group: <checked>
Security group names: Unix-AUT, default

*1 – note that the AMI may be different for you. This depends on which AWS region you’re using. Of course Amazon may just have removed this AMI and added a new one with a different AMI ID. You’ll need to search in your AWS console for something similar to “Ubuntu Server 14.04 LTS (PV),EBS General Purpose (SSD) Volume Type. ”

*2 – on Step 3, ‘Configure Instance’ details you’ll see a parameter that allows you to enable termination protection. Just need to make sure this is checked so that you prevent anyone terminating our server. It’s going to be holding all our test source which is critical to everything.

Once you’ve clicked the ‘Review and Launch’ button you should see a configuration summary page like this:

When you ‘Launch’ this instance you’ll need to configure the SSH security key pairs.

  1. Configure the SSH security key pairs by selecting:

Choose an existing key pair
<select your SSH key pair>

So back in module 1 we created an SSH security key pair. You should have this saved safely somewhere (see the Prerequisite section in this module for more info on your Key Pairs). As you need to select it on this dialogue box:

This is the key pair AWS created for us back in module 1 and that AWS stores and uses. We need to have access to the .pem file that was created as part of the initial setup back in module 1. The important point, as AWS put it, is:

“I acknowledge that I have access to the selected private key file (*.pem), and that without this file, I won’t be able to log into my instance.”

You just need to make sure you can find your copy of your *.pem file. Assuming you have it check the ‘acknowledge’ check box and click the ‘Launch Instance’ button.

  1. Check your new Linux instance is running.

Back on the AWS EC2 dashboard you should see your new instance running. You can search based on the name you gave the instance if you like.

 

 

Once this is running we can check the security groups and make a connection using SSH.

Part 2: Setup the Security Group and SSH Connection

Now we have our Unix-Git Source Code Control (SCC) machine running we need to make sure the AWS security settings will let us connect to it and configure an SSH terminal connection.

  1. First then the AWS Security Group Configuration.

Set up the security group by first checking that this linux machine has the right security group assigned to it. You can do this by selecting the host in the AWS EC2 console.

 

 

Click on the ‘Unix-AUT’ link which will take you through to the security groups page for this specific group. Then click on the ‘Inbound’ tab.

 

At this point we can ‘edit’ the security group and add a new rule:

 

 

This rule we’ll configure with the SSH port from our local laptop/desktop machine. So select these parameters:

Type: SSH
Protocol: TCP
Port Range: 22
Source: My IP

Which should give us something like this

 

 

Once we have this we’ll have access to our Linux machine direct from our laptop/desktop using the AWS Java SSH Client (MindTerm).

  1. Second we need to connect using an SSH terminal.

We’ll make this connection using an in-built SSH client (MindTerm) that is integrated with the AWS management console. To connect using this method, first go back to your list of AWS instances and then right click to select ‘Connect’

 

 

Once you see the connection dialogue box you should select this option:

A Java SSH Client directly from my browser

You will of course need Java installed on your laptop/desktop machine in order to follow through with this. Once you have selected this you just need to find the ssh key you created way back in Module 1. Should be a file you saved with a name like ‘FirstKeyPair.pem’. Everything else can be left as defaults giving you something like this:

 

 

Once you click on the ‘Launch SSH button’ you should see a window like this open up

 

 

Of course this is the first time we’ve connected to this linux server from our laptop/desktop machine. So SSH on the Linux machine warns us that we’re not a ‘Known Host’ and looks for confirmation that we want to add our laptop/desktop as a ‘known host’. We just need to click ‘Yes’ for this.

If you run into any error messages or have trouble connecting at this stage just close the terminal window and open it again. Second time round the connection usually works without any problems.

Now we have the Unix-Git machine running and we have a shell SSH connection. Next step is to configure our Git server that will run on this machine. Once configured we’ll be able to store our test cases on this server.

Part 3: Install Git

We have our server up and running with an SSH shell connection open. Just need to install Git now. Pretty straightforward. Just run this command:

sudo apt-get install git

Select all the defaults as you are prompted.

 

 

This should complete cleanly having installed all the required packages:

 

 

And that’s it. Simple.

Just need to configure a Git user account and set the Git server up.

Part 4: Configure the Git User Account

To configure our Git server we’ll need to run through a few steps.

  1. configure a Git user
  2. set up ssh for that user
  3. create and store this users SSH key pair
  4. copy the private key pair somewhere safe
  5. install the private key on the Windows Master machine
  6. install the private key on the Windows Client machine

What are going to have is a user defined on our new Git server. This user (called ‘ae’ for automation engineer) will be setup with SSH (Secure Shell) access. We’ll be able to have all our clients of this Git repository running with the SSH private key so that they can login to this Git server without having to authenticate with username and password details. When these client machines have direct access they will be able to check out and check in code (e.g. our Selenium, JMeter and SoapUI scripts) directly to this Git server. In order to do this we need to setup this user and SSH. The next 5 steps take you through this process.

  1. First then, let’s configure a Git user from our SSH terminal that’s running. Enter the following commands which will create a new unix user ‘ae’ (which stands for automation engineer):

sudo adduser ae

Enter a password (one that you can remember) so that you have the following in your SSH terminal

 

 

  1. Then we can configure SSH by entering the following commands:

su ae
cd
mkdir .ssh
chmod 700 .ssh
touch .ssh/authorized_keys
chmod 600 .ssh/authorized_keys

Once you’ve run through these commands your SSH terminal should look something like this:

 

 

What this set of commands does is create the directory that SSH will need for our Git connections. Then, with the ‘chmod’ command it makes sure the permissions for the SSH director are set for only the user (ae) to have access. SSH is very sensitive about permissions.

Then we create a new file called ‘authorized_keys’ which is where we’ll store our authorized key for this ‘ae’ user. Again we modify the permissions of this file so that only the ‘ae’ user has access to it.

  1. Now we can create an ssh key for this user. The command we use for this is ‘ssh-keygen’:

ssh-keygen -t dsa

This takes you through a set of questions that are need to create this ssh key pair.

Enter file: <accept the default>
Enter passphrase: <your passphrase> *1
Enter same passphrase: your passphrase>

The passphrase you choose is used to protect the private component of the ssh key pair. Remember that an SSH key pair comprises of private and public components. The private component you keep safe, never reveal and never send over the internet.

Once you’ve completed this step you should see the following:

Your identification has been saved in /home/ae/.ssh/id_dsa.
Your public key has been saved in /home/ae/.ssh/id_dsa.pub.

What we need now is to copy the private component back to our own laptop/desktop. We’ll need to install this private key on our Jenkins Windows master machine later. This way our Jenkins machine will be able to use this user account with the SSH connection to get all our source code from this Unix-Git machine.

  1. We now need to add the public key (id_dsa.pub) to our authorized keys file.

We can add this key with the following commands

cd ~/.ssh
cat cat id_dsa.pub > authorized_keys

This cat command kind of prints the id_dsa.pub file but sends that print out to the authorized_keys file. With this public key installed any machine connecting that has the private key installed will be allowed to authenticate directly with this machine.

Next then we need to store a copy of our private key pair so that we can use it later.

  1. Display the private key and copy it somewhere safe.

If we use the Unix ‘cat’ command to read and display our private key we can then copy the text locally. So run this command:

cat /home/ae/.ssh/id_dsa

You should see something like this

—–BEGIN DSA PRIVATE KEY—–
Proc-Type: 4,ENCRYPTED
DEK-Info: AES-128-CBC,3A4052FF706445E55E0BE77A36560A28

2wqLvMXmVhctPSXasdfqerueTrEOB00V/b3Lv5aCdXLO6DSD3KCoNItkOhcW0ghzy
skFYV8nhF37ZkZmAj+//x8HKLA0xMerqewreqwrdso1nxELEh4ZWCPhGf9kzP5+PN
XoaLjuBviaQUMH8rhIHbbk+WobMCO74lB9zzq9G7ppkTcsA0AICbALvt3B+C6z9r
oIY7L/nFtLfiIjaXfEW3Q8Wx/1E8hWBA1u+bPNYg30hKOUg0ucvzf5GOHSsZr17q
F8LR4UTRQC3/U97BHtc/LsvtN4bxl/qlQcgFnCgH5HWOtOB9hqfd3hAEQufBTclZ
oqAXIBHBhyRXwkQ2asdfaLWJa5LVBqZp+hptGwTJJWAAQvDckZ6hcGBr3tPQbaPp
JqeFgXmDUg18vzUT3eBfwsvHBpMfIs1buGUWHXoLmRZohDYZuyN29BE5b55GnQm1
525s6jPXKi+Xgr67adsfdOyZBFyJi6i6SSicyaH1STwc1GkTm6tx4EOalttpR0cd
S2so71kldWWGXreJbqsZqqweref0hXErLuEwga+W5G5x9Wd3cpHdknzeDwQa8CTo
w+4APOiCUbsSQ6hoInM6zQ==
—–END DSA PRIVATE KEY—–

Copy this text, paste it into Notepad (or any text editor) on your local laptop/desktop machine. Call the file something like:

aeKeyPair.pem

Save the file and please try not to lose it. We can get it again from this Ubuntu machine if we need but it’s easier if we save it somewhere safe. JUST DON’T foget the passphrase you used. That’s the most important point.

  1. Now we need to install this key on our Jenkins windows master machine.

Once we’ve installed this key our Jenkins windows master machine will have access to the ‘ae’ user and the Git repository that will store all our automation scripts. Next step then is to open the RDP session to the Windows master machine.

 

 

On the desktop of this master windows machine create a new text file.

 

 

Name the file:

 

aeKeyPair.pem

and open it in notepad…

 

 

Once opened we need to copy in our DSA private key details. Open the aeKeyPair.pem file that’s on your laptop/desktop (or on the Ubuntu server) and copy/paste the content into notepad on the windows master machine.

 

 

Save this file. We need to convert this into a format that Putty (our SSH client tool running on our Windows master machine), understands. So open “PuttyGen” from the start menu:
 


 

We need to import our .pem file into PuttyGen now:
 


 

And then select the aeKeyPair.pem file that we’ve just saved to the desktop. At which point you’ll need to enter your Passphrase … hope you can remember it!

 

 

Then click “Save Private Key” and save the new .ppk format file as:

aeKeyPair.ppk

Which should take you through this step:

 

 

Close PuttyGen and find the Putty Agent that should be running in your task try. Right click on this and select ‘Add Key’

 

 

At which point we need to select our new ‘aeKeyPair.ppk’ file:

 

 

Enter your Passphrase and we should be ready to configure our new Linux Ubuntu machine as a new Putty client. So open Putty again and select ‘New Session’ this time round:

 

 

Now we need to configure our new Unix-Git machine as a new Session in Putty. First you’ll need to find the ‘Private IP address’ from your AWS terminal:

 

 

Jot this IP address down and configure the following in Putty:

Connection -> Data -> Auto-login Username: ae

 

 

Session: <private ip adddress>
Saved Sessions: Unix-Git

 

 

You have to be careful here that you click save and not load. If you click load it loads up another sessions details, without warning, and you lose your new session details. So save this. Then click on the new ‘Unix-Git’ entry and select ‘Open’

 

 

Accept the security warning by selecting the ‘Yes’ button

 

 

At which point we should be in business. You should have a direct session open to our Unix-Git machine directly from our Windows Master machine

 

  1. install the private key on the Windows Client machine

Now we just need to take that aeKeyPair.ppk private key file, copy it to our Windows Client machine and install the key there too.

Make sure you have this file on you Windows Master machine desktop:

aeKeyPair.ppk

Once you’ve located it you’ll need to copy it

 

 

Then open an RDP session to the Windows client machine

 

 

You’ll need to go to your AWS console and get the Public DNS/IP value for this host if you can’t remember it. Once you have the Public DNS/IP value enter it in the RDP dialogue box and connect.

 

 

You shouldn’t need to authenticate with user and password details. It should connect immediately. We set up automatic authentication back in Module 3.

Once connected paste the ‘aeKeyPair.ppk’ file to the desktop of the Windows client machine.

 

 

Download the Putty SSH tools and install on the Windows client machine:

http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html

You need to select, download and install using the ‘putty-0.xx-installer.msi’ file:

 

 

Step through the instal wizard and select all the defaults. Start Putty Agent from the install directory:

C:\Program Files (x86)\PuTTY

 

 

Right click on Putty Agent in the task tray and select ‘Add Key’

 

 

At which point we need to select our new ‘aeKeyPair.ppk’ file:

 

 

Enter your Passphrase and we should be ready to add our new Linux Ubuntu machine as a new Putty client. So open Putty again and select ‘New Session’ this time round:

 

 

Now we need to configure our new Unix-Git machine as a new Session in Putty. First you’ll need to find the ‘Private IP address’ from your AWS terminal:

 

 

Jot this IP address down and configure the following in Putty:

Connection -> Data -> Auto-login Username: ae

 

 

Hot Name: <private ip adddress>
Saved Sessions: Unix-Git

 

 

You have to be careful here that you click save and not load. If you click load it loads up another sessions details, without warning, and you lose your new session details. So save this. Then click on the new ‘Unix-Git’ entry and select ‘Open’

 

 

Accept the security warning by selecting the ‘Yes’ button

 

 

At which point we should be in business and have a direct session open to our Unix-Git machine.

 

 

All of this is essential if we want our machines to be able to automatically check out code from our Git source code repository without having to authenticate everytime with a user name and password.

Now we’re ready to setup our Git source code repository and start saving all our test scripts (Selenium, JMeter and SoapUI) safely in this repository.

Part 5: Configure the Git Server

Git is already installed on our Ubuntu Linux server (we set this up earlier). We just need to run a handful of commands to configure Git as we need it. We can do this from either of the SSH shells we have access to. Either the Putty SSH shell running on the Windows Master machine or the SSH shell provided as part of the AWS management console. I’m going to use the SSH shell from Putty on our Windows master machine.

  1. Connect to the Linux Ubuntu machine using Putty

On the windows master machine from the Putty saved sessions select ‘Unix-Git’

This should take you straight into an SSH terminal with no authenticating required. And if you type ‘whoami’ you should see that you’re logged in as the ‘ae’ (automation engineer) account.

  1. Now we need to create a ‘bare’ (empty) Git repository

We’ll run these commands to create an empty directory for our Git repositories.

mkdir ~/git
mkdir ~/git/selenium
cd ~/git/selenium
git init –bare

Which should give you:

We’re creating a directory for our Selenium source code first. Then we’re changing to that Selenium directory and initialising a new git repository with the ‘git init –bare’ command. The ‘bare’ option just means create an empty Git project.

  1. Create repositories for our other projects

Now we know how to create bare repositories we can create them for the other JMeter and SoapUI source code we’re working with. Just run these commands:

mkdir ~/git
mkdir ~/git/jmeter
cd ~/git/jmeter
git init –bare

Which creates our JMeter repository. Just SoapUI left

mkdir ~/git
mkdir ~/git/soapui
cd ~/git/soapui
git init –bare

Now we have one Git source code repository (or Git project) for each of our test tools.

Next we need to make that initial commit of source code for the tools we’re using. We’re going to work through doing this for our Selenium code in the next few sections.

Part 6: Commit Our Selenium Source Code to the Git Server

First then we need a Git client running on our machines where we currently have our source code. For example we have developed our Selenium scripts on our Windows client machine. We’ll need to install a Windows Git client on our Windows master machine and our Windows client machine. That Git client can then commit our Selenium scripts to our Git server. Then all our machines (e.g. our Jenkins slave machines) will have access to this source when they need it.

Let’s install this Git client then. These steps need to be repeated BOTH on your Windows Master machine AND your Windows Client machine.

 

 

  1. In IE download Git

Open IE and go to this Url

https://git-scm.com/download/win

Fight your way through all the IE security warnings if you have to. Then click the ‘64-bit Git for Windows Setup’ link

 

 

If you run into download issues you may need to adjust your IE security settings

 

 

You’ll need to add these domains to the zone:

https://github.com
https://github-cloud.s3.amazonaws.com

That should allow you to download the installer once you click on the IE warning

 

 

  1. Install Git on your Windows Master machine

Then click run:

 

 

Accept all defaults in the install wizard EXCEPT for the ‘Choosing the SSH executable’ option. For this make sure you select ‘Use (Tortoise) Plink’ and enter the path to ‘plink.exe’

 

 

And that should be it. Next you should see the completion Window

 

 

  1. Check the Git GUI Starts

From here on the Start menu you should be able to start the Git GUI application

 

 

Which should give you:

 

 

You can click ‘Quit’ for now.

  1. Check the Git command line application

Also check your Git install works from your command line. So open a command windows:

 

 

And type this command:

git –version

This should confirm the Git command line tools work as you’ll see the version of Git that’s been installed.

 

 

From here we’re ready to start pushing our Selenium script to our repository.

Part 7: Commit our Selenium Script to our Git Repository

In the previous parts we initialised the Git repositories on the Linux Ubuntu machine and we installed the Git client application on our Windows machines. From here we need to use that Git client on our Windows client machine to “add” our Selenium code to the Git repository on the Linux Ubuntu machine.

Not surprisingly we’ll be using the Git ‘add’ command along with the Git ‘commit’ command. We’ll be doing all of this with the Git command we just ran from the Windows command prompt.

  1. Open an RDP session to the Windows Client machine

Then open an RDP session to the Windows client machine

 

 

You’ll need to go to your AWS console and get the Public DNS/IP value for this host if you can’t remember it. Once you have the Public DNS/IP value enter it in the RDP dialogue box and connect.

 

 

You shouldn’t need to authenticate with user and password details. It should connect immediately. We set up automatic authentication back in Module 3.

  1. Locate our Selenium scripts

Back in Module 3 we wrote and ran our Selenium scripts. We should find our Selenium script on our Windows Master machine on the Desktop

 

 

Not the best place to store them! Which is exactly why we’re setting up a Git source code repository to keep them safe.

  1. Create a new folder to store the Selenium script

In an Explorer window create a new folder ‘projects’

 

 

Followed by a sub directory ‘selenium’

 

 

So you should have this new directory path:

C:\Users\Administrator\Documents\projects\selenium

  1. Copy your Selenium script into this folder:

 

  1. Open a Git command prompt session

Right click in the Explorer window and select the ‘Git Bash Here’ option

 

 

At which point you should see a Git terminal open

 

 

From here we can copy (or check in) our Selenium scripts to our Git source code repository on the Linux Ubuntu server

  1. Commit your Selenium Script to Git

First we need to prepare Git so that it knows who and what needs committing to our souce code repository. We’ll need to run these commands:

$ git init
$ git config –global user.name “Automation Engineer”
$ git config –global user.email “ae@ae.com
$ git add .
$ git commit -m ‘initial commit’

This should give you a series of commands like this:

 

 

The init command setups Git in this directory (if you run the command ‘ls -la’ you’ll see a new hidden directory that contains all the Git data). Then the config command sets up the git user on this machine. You can’t do anything without setting up the git user as this information is tied closely to everything you checkin to git. Then we tell git that we want to ‘add’ this directory to our repository. Finally the commit command commits our files locally ready for them to be pushed to the Linux Ubuntu server.

To add the files to the Linux Ubuntu server we’ll need to run these final two commands:

$ git remote add gitserver Unix-Git:/home/ae/git/selenium
$ git push gitserver master

Which should give you something like this:

 

 

What we’re doing here is first adding a remote server. Essentially identifying the Linux Ubuntu machine where we want to push and commit our Selenium scripts to. Note that we define the server name as ‘Unix-Git’ which is the ‘Putty’ name we defined for this server earlier.

Once we’ve added a remote called ‘gitserver’ we can use this as part of our final ‘push’ command. The ‘push’ command sends the files to the ‘gitserver’ and adds them to the branch called ‘master’.

Now are Selenium script is safe in our Linux Ubuntu source code repository. It’s available for other users and servers in our framework of machines to use. In the next two sections we’ll look at…

1. Modifying the selenium script on another server and checking the changes in
2. Updating our Jenkins job so that it uses the latest Selenium source code from the Git server

At this point though we’re well on the way to having a distributed source code repository that stores all our automation scripts safely. All we need to do is update our Jenkins job so that it uses the Selenium source code from the repository. From there any updates that are made to the sripts, so long as they are pushed to the repository, will be picked up by our Jenkins job.

Part 8: Updating our Jenkins Job to Use the Git Repository

With our Selenium source code safely stored in our Git Repository all we need to do is make sure that our Jenkins job, that executes the Selenium scripts, pulls the latest source from the repository before it starts. To do that we just need to make a few updates to our ‘RunSeleniumTests’ job.

TODO: put the schematic diagram in here

  1. Configure the ‘RunSeleniumTests’ job

Click on the configure menu option for the ‘RunSeleniumTests’ job on the Jenkins home page:

http://www.testmanagement.com/wp-content/uploads/2015/01/BTS-module6-img10-configure-selenium-job.png” alt=”” />

  1. Change the ‘Source Code Management’ option

In the ‘Source Code Management’ section change the option from ‘None’ to ‘Git’

 

  1. Enter details for the Git Repository

We need to point this job at our new Git repository residing on our Linux Ubuntu machine. Update the ‘Repository URL’ field with this value:

Unix-Git:/home/ae/git/selenium

This tells Jenkins to use our already configured (back in part 4) Putty ssh connection. If you remember we configured a Putty client called ‘Unix-Git’. We use this Putty client name as the first part of the repository Url (this is what established the link to the Git server over Putty Ssh). Then we define the location of the Selenium Git project on the Git server. This should look like this…

 

 

 

We don’t need any security credentials defined (we’ve already specified Putty Ssh host) and the branch to build should automatically be set to “*/master”.

With this configured Jenkins will pull our SelLoginTest.py script out of the Git repository prior to running the build commands specified in this job. So next we need to tell Jenkins to use this Selenium script that it gets from the Git repository.

  1. Update the ‘Execute Windows batch command’

Once Jenkins, executing the RunSeleniumTests job on the remote Windows machine, pulls out the SelLoginTest.py script from Git it can be executed. The Git pull request executed on the Windows client machines places a copy of the SelLoginTest.py script in this directory on the Windows client machine

C:\jenkins\workspace\RunSeleniumTests

Where the ‘RunSeleniumTests’ in this path is the name of our Jenkins job. So you’ll see it on the Windows client machine here:

 

 

The only problem is that our Jenkins job, the ‘Execute Windows batch command’ section, points at the ’SelLoginTest.py’ script on the Desktop. Back on our Windows Jenkins master machine you see this configured in the Jenkins job here:

 

 

We need to update this so that it points at the checked out script in the Jenkins work space. So change this to:

set
%WORKSPACE%\SelLoginTest.py Ie %PUBLIC_HOSTNAME%
%WORKSPACE%\SelLoginTest.py Chrome %PUBLIC_HOSTNAME%
%WORKSPACE%\SelLoginTest.py Firefox %PUBLIC_HOSTNAME%

Notice that we’ve used the Jenkins Environment variable %WORKSPACE%. Jenkins knows where the work space is on the Windows client machine so we may as well let Jenkins work that out each time the job runs. Once updated the command field should look like this:

 

  1. Run and Test the Updated Job

Save the updated Jenkins job and return to the dashboard. You can run this job now and check it works:

 

 

If you view the console output for this job you should see it start off with something like this:

 

 

The part here being these few lines:

Building remotely on Windows-client (i-2c2ac7ea) (SeleniumTestClient) in workspace c:\jenkins\workspace\RunSeleniumTests
Fetching changes from the remote Git repository
git.exe config remote.origin.url Unix-Git:/home/ae/git/selenium # timeout=10
Checking out Revision e47f98e0c04922d02e990337126dc0376f50f029 (refs/remotes/origin/master)
git.exe config core.sparsecheckout # timeout=10

This shows that Jenkins is using Git to fetch any changes to the SelLoginTest.py scripts. In this case there haven’t been any changes so not much happens. In the next part we’ll see what happens when we have made changes.

The other piece of note is the last section in this console output.

 

 

You’ll see here, for example, that Jenkins has expanded the %WORKSPACE% environment variable and replaced it with the full path to the workspace where our SelLoginTest.py file has just been checked out from Git to:

c:\jenkins\workspace\RunSeleniumTests>c:\jenkins\workspace\RunSeleniumTests\SelLoginTest.py Chrome http://ec2-54-200-24-122.us-west-2.compute.amazonaws.com:3000

The final part in this is making sure we can make changes to our SelLoginTest.py scripts from other machines and checking them into to Git. Then we’ll want to see those changes being checked out by our Jenkins job on the Windows client machine. We’ll see this in action in the next section.

Part 9: Modify and Commit our Selenium Scripts from another server

At this stage then, maybe another tester decides our Selenium script needs a little updating (more comments perhaps). On our Windows master machine we can check out the scripts, make our modifications and then push the mods back to the repository. Next time we run our Jenkins ‘RunSeleniumTests’ job we should see those changes in the execution of the Selenium script.

We’ll see this in action as we complete the next few steps where we make changes to the SelLoginTest.py script on the Windows master machine. We’ll then push those changes to our Git repository. When our Jenkins job runs on the Windows client machine we should see those changes incorporated in that test run.

So back on the Windows Master Machine

  1. Create a folder for the Selenium scripts

In explorer, in the Document folder, create a new folder called ‘automation’

 

 

We’ll pull our Selenium project and SelLoginTest.py script out of Git into this directory.

  1. Open the Git GUI

From the Start menu select the ‘Git GUI’ application

 

 

We have three options here. ‘Create New Repository’ which we don’t need as we already have our repository created on our Unix-Git machine. ‘Open Existing Repository’ which means start using a repository that already exists on this local machine (we don’t have anything yet so this is no good). And ‘Clone Existing Repository’ which allows us to take a copy of our repository that is residing on our Unix-Git machine. This is the option we’ll select.

 

 

On this next screen we’ll need to enter the location of the repository that’s on our Unix-Git machine and tell the ‘Git GUI’ where is needs to copy that repository to locally. So enter the following:

Source Location: ae@Unix-Git:/home/ae/git/selenium
Target Directory: C:\Users\Administrator\Documents\Automation\Selenium

Then click on the ‘Clone’ button:

 

 

What we’re doing here is using our (already created) Putty ae@Unix-Git ssh connection and the location of our git/selenium project as the source. We’ll clone that project that resides on the Unix-Git machine into a new directory ‘Automation\Selenium’ on this local machine. In Explorer you should now have this…

 

 

And Git GUI should show you this window…

 

 

Lets ingnore this window for a second and quickly update our Selenium script

  1. Open the SelLoginTest.py script

Open ‘notepad’ and edit the SelLoginTest.py script:

 

 

Add a new comment or something, just so that we’ve made a change to the script:

 

 

Then close notepad and save the update…

 

 

  1. Git GUI Rescan

In Git GUI click the ‘Rescan’ button to check for the changes we’ve just made. You should see the modification listed like this…

 

 

  1. Git Config
    Now we can ‘Commit’ the changes to our local repository. Then we can ‘Push’ the changes to our master repository on our Unix-Git machine. Before we can commit the changes we need to setup our identity on this machine (using ‘git config’ like we did on the Windows client machine).

 

 

Then run these two commands at the prompt:

$ git config –global user.name “Automation Engineer”
$ git config –global user.email “ae@ae.com

Which should give you this:

 

 

That step is just a one off config step. We need to run it otherwise ‘Git GUI’ will complain that it doesn’t know your identity to complete the commit. Once you’ve run it you won’t need to do it again prior to future commits.

Then back in ‘Git GUI’ we should be able to run our commit. First enter some text in the ‘Commit Message’ section to sumarise the change you’ve made. Then click the ‘Rescan’, then the ‘Stage Changed’ button followed by the Commit’ button

 

 

Right, all that’s done is commit your changes locally. It’s hasn’t pushed the changes to the Git Unix repository. We’re ready to push them though.

  1. Git Push

Now we’ll be able to ‘Push’ the changes so that our Jenkins job can pick up these changes.

 

 

On the ‘Push’ dialogue box just select all the defaults and click ‘Push’:

 

 

You should see this confirmation box showing the successful push:

 

 

Now we’re ready to see if Jenkins will pick up these changes in the next run of the ‘RunSeleniumTests’ job.

  1. Build the ‘RunSeleniumTests’ Job and Confirm pull of Updated Source

Back in Jenkins on the Windows master machine lets run the Selenium test job again. This time we’ll check the job pulls the latest source out of Git before running the SelLoginTest.py script.

 

 

As this is running we can check the build log:

 


And in here we should see some of these messages at the start of the console output:

git.exe rev-parse –is-inside-work-tree # timeout=10
Fetching changes from the remote Git repository
git.exe config remote.origin.url Unix-Git:/home/ae/git/selenium # timeout=10
Fetching upstream changes from Unix-Git:/home/ae/git/selenium
git.exe –version # timeout=10
git.exe -c core.askpass=true fetch –tags –progress Unix-Git:/home/ae/git/selenium +refs/heads/:refs/remotes/origin/
git.exe rev-parse “refs/remotes/origin/master^{commit}” # timeout=10
git.exe rev-parse “refs/remotes/origin/origin/master^{commit}” # timeout=10
Checking out Revision 89293a45f2accb9b4191c717c23363901fd247d6 (refs/remotes/origin/master)
git.exe config core.sparsecheckout # timeout=10
git.exe checkout -f 89293a45f2accb9b4191c717c23363901fd247d6
git.exe rev-list e47f98e0c04922d02e990337126dc0376f50f029 # timeout=10

For the observant of you you’ll notice that the check out id (‘89293a45f2accb9b4191c717c23363901fd247d6’) is different. Indicating that we have a different version of our SelLoginTest.py script. If you open the SelLoginTest.py file in the Jenkins ‘workspace’ on this Windows client machine you’ll see our updates:

 

 

And that’s it! We’ve gone full circle making changes to our Selenium scripts on one machine. Then seeing those changes picked up automatically by our Jenkins job, and the changed Selenium script being used on our Windows client machine.

We can now say that we have control of our test source code. You’re job now it to complete the same set of steps for the SoapUI and JMeter source files.

Conclusion

When we started this module we had everything running in our automation framework. Jenkins could install the application under test, run the Selenium tests, run the SoapUI tests and execute some performance tests. What we didn’t have was control over the source code that was created for these Selenium, SoapUI and Jmeter tests. None of our tests were stored in a central location and none of them version controlled.

In this module we showed you how to setup a central Git server, commit our test files to this Git source code repository and then configure our Jenkins jobs to use the test files stored on this Git server. Finally we looked at how you can develop on one machine and then commit changes to the Git repository. Of course Jenkins then automatically picks up and runs with those latest changes.

All of this makes it easier to collaborate during the development of your tests. It makes it easier to maintain the different versions of your test files and of course revert to old versions if you break something. This whole setup also giving you a distributed repository that’s effectively a backup of all your test files.

Finally, it puts you in the same league as your development team who will undoubtedly be using a source code control tool to manage the development of the application you’re testing.

Free Test Automation Framework Course
Learn the Practical steps to building an Automation Framework. Six modules, six emails (each email a short course in it's own right) covering Amazon AWS, Jenkins, Selenium, SoapUI, Git and JMeter.
Facebooktwittergoogle_plusredditpinterestlinkedinmail

In this Moudule we’re focusing on running our performance and load tests. We’ll create some simple scripts in JMeter and link the execution of these scripts into our build process with Jenkins. Once our Selenium functional tests and our SoapUI REST API tests are complete we’ll kick off these JMeter tests. The setup of this will cover these topics:

1. Install JMeter
2. Configure and Create Performance Tests
3. Add and Configure Jenkins Performance Plugin
4. Deploy and Run all our test jobs

 

To keep things simple we’ll use JMeter to test the performance using the Rocket Chat Rest Api. This will allow us to focus on the key concept of building the automation framework rather than getting to hung up on writing the performance tests. You’ll be pleased to know, at this point in the course, it’s a pretty straight forward process of adding JMeter to the Jenkins configuration.

Yet again we’ll add a new plugin to Jenkins (the ‘Performance Plugin’) which allows us to consume the test result reports from JMeter and display them graphically within Jenkins. We’ll work out how to configure the JMeter tests on our Windows Master machine but we’ll deploy them to a Linux machine for execution. This approach will serve you well for future larger performace tests where you might want to start running distributed performance tests.

What You’ll Learn

The aim is to assess the performance of the build once the application is built and installed. We’re looking to catch issues where performance degredation occurs after changes have been made to the code base. To this end our Jenkins configuraiton will not only kick off the performance tests but it will also asses the performance statistics from one build to the next. If the performance degrades from one build to the next by say 10% then we’ll get Jenkins to notify us.

 

To acheive this we’ll need to have these pieces in place on our test automation rig:



As we’ve already mentioned this isn’t just going to be about running Performace tests. We’ll need to create the tests on the Windows master machine using the JMeter GUI. Then we’ll distribute the JMeter configuration and tests to a Linux machine for execution.

The Tools We’ve Chosen

We’re using JMeter mainly because of it’s popularity and it’s wide use within the industry. Mind you that’s no good if it doesn’t support our technical requirements. We need to create REST Api requests, listen for the REST responses and then store the test results.

Another reason for using JMeter is that there is a Jenkins ‘Performance’ plugin that supports JMeter. This plugin allows us to process the log files created by Jenkins and create some neat charts. You can never have too many charts!

It’s also worth mentioning that JMeter runs (under Java) on both Windows and Linux platforms. We can create tests using the GUI on our Windows Master test machine. We can also run these tests from a Linux machine from a command line when we need to. Again this is all about being able to run from the command line – which is the simplest way to approach things when using Jenkins.

Prerequisites

If you’ve followed upto Module 4 so far you should already have your Amazon Virtual machine environment up and running along with Jenkins, Selenium and SoapUI. This existing setup gives us the 2 machines we’ll need to use in this module.

  1. Windows Master machine: this is running Jenkins and controlls all our other machines (including the installation of the AUT and the exection of our Selenium tests). This machine will be responsible for kicking off our SoapUI API tests
  1. Linux Client machine: this Ubuntu linux machine is run up on demand by Jenkins and then has the AUT (Rocket Chat) autoamtically installed on it. This machine provides the web interface for the Rocket Chat application and the API for the Rocket Chat application.

Check the Status of your AWS Machines

Your windows Master machine should already be running. The Linux machine may or may not be running. The Linux machine is run up automatically by Jenkins so it’s fine if it’s not running right at this moment. Whatever the state of the linux machine you should see the Windows machines status in the AWS console as follows:


Open an RDP Terminal Session on the Windows Master Machine

With these windows machines running you’ll need to open an RDP session on the Windows Master machine. This is where we’ll configure Jenkins.



Then enter the password (you may need your .pem private key file to Decrypt the password if you’ve forgotten it) to open up the desktop session.

Start the Linux Client Machine

If the Linux machine isn’t running with the AUT installed then we need to start it. We can get Jenkins to do this for us. Once you have an RDP session open to your Windows Master machine you should have the Jenkins home pages displayed. If not open a browser on this machine and go to this URL:

 > http://localhost:8080/

From here you can start the ‘BuildRocketChatOnNode’ job and start up the AUT.

 



Once RocketChat is up and running we’ll need to know the host name that Amazon has given our new Linux instance. We save this in our ‘publicHostname.txt’ file that is archived as part of our build job. So if you go to this directory using Explorer

C:\Program Files (x86)\Jenkins\jobs\BuildRocketChatOnNode\builds\lastSuccessfulBuild\archive

You should find this publicHostname.txt file…



Open this with notepad and make a note of the hostname. We’ll need this while we configure our performance tests.

At this point you should have…

  1. An RDP session open to your Windows Master machine
  2. Your Linux Ubuntu machine running with Rocket Chat installed

From here we’ll setup our Windows Master machine and install/configure JMeter on the Master machine.

Part 1: Install JMeter

We’re going to use our existing Windows Master machine for this. We’ll install JMeter on this machine so that we can develop our performance tests on this Master test machine. We just need to open the RDP session, download JMeter and install it.

On the Windows Master machine follow these steps:

  1. Open a browser
  2. Enter the following address:

    http://jmeter.apache.org/download_jmeter.cgi

  3. Download the Apache JMeter Zip’ package

  1. Open the download folder and extract the JMeter folder from the zip file…

  1. Open the folder that contains JMeter.

Before you can run JMeter we need to configure the PATH environment variable so that it contains the path to our Java install.

  1. Configure the environment variable by ‘right clicking on Computer’. Then selecting ‘Properties’ followed by ‘Advanced system settings’

  1. In the ‘advanced system settings’ click on ‘Environment Variables’ and find the ‘Path’ environment variable to edit:

  1. At the end of the ‘Path’ environment variable add this text at the end:

    ;C:\Program Files (x86)\Jenkins\jre\bin\

Note the ‘semi-colon’ at the start of the text and the ‘’ at the end. When you’ve finished the full path should be something like this:

> %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;%systemroot%\System32\WindowsPowerShell\v1.0\;%systemroot%\System32\WindowsPowerShell\v1.0\;C:\Program Files\Amazon\cfn-bootstrap\;C:\Program Files (x86)\Jenkins\jre\bin\

Save this. If you want to check this works then open a command prompt and just type ‘java -version’. This should show you the version of Java we have installed.

  1. From here you should be able to run JMeter by clicking on the ‘JMeter Batch file’ in explorer:

You can create a desktop short cut to this batch file if you want to. This will make your life a little easier later on.

  1. At this point you should be presented with the JMeter GUI.



Now we’re ready to start configuring our performance tests.

Part 2: Initial Configuration of JMeter

Initially we just need to setup JMeter and check that we can send a single request and get a response. We’ll configure a Thread Group (users) against the Rocket Chat /api/version end point. Once we can get a response from this end point we’ll move on to configure a more realistic set of load scenarios.

  1. Right click on ‘Test Plan’ and select ‘Thread Group’ so that we can define the number of users we need to simulate



 

  1. Update these settings for the Thread Group:

    Number of Threads (users): 10
    Loop Count: 20

This way we’ll simulate 10 user and repeat our test 20 times.

 



 

  1. Right click on the ‘Thread Group’ node and select ‘Add’ followed by ‘Sampler’. Then select HTTP Request:



 

This will allows us to create a REST API request that uses the Http protocol (similar to the functional tests we’ve already created with SoapUI).

  1. On the ‘HTTP Request’ pane we need to specify the details for the request. Update the following:

    Server Name or IP: <host name for Rocket Chat>*
    Port Number: 3000
    Method: GET
    Path: /api/version

    this is the host name we obtained from the publicHostname.txt file when we completed the Prerequisite tasks at the start of this module. You should not put the ‘http://’ at the start of this field.

  1. On the Test Plan create a ‘View Results Tree’ listener:



 

You can leave all the defaults set here so that the Result Tree settings look like this



 

  1. Save the Test Plan at this point (click on file and select ‘Save Test Plan as’)



 

Save the test plan as ‘RocketChat.jmx’.

  1. Click on ‘Start’ and check you get valid responses



 

Now that we have a successful connection, with requests and responses, we can configure some more scenarios that will give us a more relaistic load.

Part 3: Configuring Our Performance Tests

In SoapUI we created a test case that logged in and then passed the userId and authToken to the subsequent test cases (API calls). We need to create a similar setup in JMeter. The main difference this time round being that we’ll have to simulate multiple users and track multiple userID and authToken sessions. We do this in JMeter by configuring Threads, where a single thread represents a single user.

  1. First we need to create a new test plan in JMeter



 

We can leave all the default settings for the test plan as they are, although you can change the name if you need to.

  1. Next we can add a new thread group. Right click on the test plan and add the ‘Thread Group’…



Again we can leave all the default settings for this thread group (e.g. 1 user and loop count of 1)

  1. Probably a good point to save this project, so click on the save button and save this as ‘RocketChat.jmx’



 

  1. Now we need to start building out the Http requests that we’ll need to send to the Rocket Chat API in order to load test it. The spec for the Rocket Chat API can be found here

https://rocket.chat/docs/master/developer-guides-4-rest-api

First then we’ll setup a default HTTP Header by adding an ‘HTTP Header Manager’ node.



 

And for our Rocket Chat request to work we’ll need to add one Header record as follows:



 

So add the following:

Name: Accept-Encoding
Value: gzip, deflate

  1. Then we need to add an ‘HTTP Request Defaults’ record. This will allow us to define the default URL and end point for all the subsequent Http requests we define.



 

And define the settings for this as follows:



 

Where we have set these two fields:

Server Name: <your AWS Rocket Chat host name>
Port Number: 3000

It’s these values that will be passed on to all subsequent requests as the defaults. Just saves us having to define the same values in all the other requests.

  1. So now we’re ready to actually send our first Http request the Rocket Chat Api. So we’ll an ‘HTTP Request’:

 

All we need to configure here is the End point path and method (and provide a more meaningful name)

Name: HTTP Request – Get Version
Path: /api/version
Method: GET

Like this…

 

All this is going to do is get the version of Rocket Chat that we’re running. It does check we’ve configured everything correctly though. We’ll need to add a listener that tracks the requests and responses and then we’ll be able to run this.

  1. Add a ‘View Results Tree’ listener as follows:

 

You don’t need to configure anything in this, but once it’s in place we can check our script so far. Just click on the run button and look at the ‘sampler results’

 

At this point we just need configure a few more requests and make sure we have the userId and authToken passed to those requests.

Key to the other requests is the login. When we login we get a userId and AuthToken returned in the response. The userId and AuthToken need to be used in the following requests. So we’ll login and store the userID and AuthToken as variables for the other requests. For this we need to setup the login request followed by two post processor ‘Regualr Expressin Extractors’

  1. Add a another HTTP Request (Thread group -> Add -> Sampler -> Http Request) and configure it as follows:

Name: HTTP Request – login
Path: /api/login
Method: POST
user: admin
password: tester123

Making sure you add these user and password login parameters:


The response when we run this request will include this json content:

{
“status”: “success”,
“data”: {
“authToken”: “uzdJZQNrtCYdGcnBL8kfKOxRNe6EmBArmzcTZKTghj0”,
“userId”: “6eJ6cZG6azfLj24QX”
}
}

So in our JMeter configuration we now need to pass this and capture the authToken and userId values.

  1. Now we’ll add TWO post processors that will use regular expressions to extract the values we need:

 

Adding two of them as follows:

Name: Get userId
Apply to: Main sample only
Field to check: Body
Reference Name: userId *
Regular Expression: “userId”: “(.+?)”
Template: $1$

 

And …

Name: Get authToken
Apply to: Main sample only
Field to check: Body
Reference Name: authToken *
Regular Expression: “authToken”: “(.+?)”
Template: $1$

 

  • it’s the Reference Name that is the variable name that stores the values used in the following Http requests.

Both of these values need to be passed in the header for other Http requests that require authentication. So we’ll add a new ‘HTTP Header Manager’ and add these userID and authToken values in there.

  1. Add a 2nd ‘HTTP Header Manager’ config element

 

Where this is configured as follows:

X-User-Id: ${userId}
X-Auth-Token: ${authToken}

The ${} nomenclature is used to insert the variables that we’re set in the regular expressions extraction.

Now we have the authentication details in the header we can call the Get Rooms and Logout HTTP requests.

  1. Add the ‘Get Public Rooms’ HTTP request (Thread group -> Add -> Sampler -> Http Request) and configure this as follows:

Name: HTTP Request – Get Rooms
Path: /api/publicRooms
Method: GET

 

  1. Add the ‘logout’ HTTP request (Thread group -> Add -> Sampler -> Http Request) and configure this as follows:

Name: HTTP Request – Logout
Path: /api/logout
Method: GET

 

Now let’s check that end to end

  1. Click on the ‘View Results Tree’ and clear the previous results

 

Then run this thread group (that only simulates 1 user at the moment). If you click on the Get Rooms request and look at the response data you should see something like this:

Which basically proves that we’ve picked up the correct authentication data from the Login request and used it in the headers for subsequent requests successfully.

We’ll add one more Listener to give us a graph of our results and increase the number of users. With that we’re pretty much done.

  1. Add a response time graph

 

And stick with the defaults to that this graph is configured as follows:

  1. Increase the number of simulated users by altering the thread group settings

 

So we’ll change just these two values:

Number of Threads (users): 20
Loop count: 10

With these settings we’ll create 20 simulated users and each will go through our set of requests 10 times. So effectively we’ll run the scenario we’ve created 200 times.

At this point your JMeter Test Plan structure should look something like this…

 

(You can add the ‘Constant Timers’ in to your test plan if you like just to make things a little more realistic.)

  1. Run the simulated load test by clicking on the ‘View Results Tree’ and clear the previous results

 

Then we can run the load test by clicking on the run button and viewing the results:

 

And if we click on the ‘Response Time Graph’ we should be able to see what the response times for all of our different requests look like:

 

Nothing too much to worry about in those results but they will form the basis of our trending across multiple builds/test-runs as we plug this into Jenkins. And that the next bit. Tying all of this into Jenkins so that it’s run automatically and the results are pulled back for reporting in Jenkins too.

Probably not a bad idea to save your JMeter project at this point too.

Part 4: Configuring our Linux Performance Test Server

We’ve developed our tests using the JMeter GUI on a windows machine. That’s fine and makes our life easier on the development side of things. However, to deliver our distributed and scalable performance capacity we’ll deploy these tests on an AWS Linux instance that’s run up automatically.

Normally we’d have an SVN or Git source code repository that we’d check our tests into (all our Selenium, SoapUI and JMeter). During development of the tests we’d check our JMeter tests in to this source code repository from the Windows machine. At excution time we’d have our Linux machine check out the latest version of these tests.

For the purpose of this course though we’re just going to take our JMeter configuration file, the RocketChat.jmx file, store this on our Windows Master machine. Our Jenkins on our Windows master machine can then deploy this JMeter config file to our Linux performance test server when we start the test.

First off then lest configure our Linux machine. Similar Jenkins setup to the Rocket Chat Linux server we setup at the start of this course. We’ll start this Linux machine on demand and shut it down automatically when it’s not needed.

  1. On our Windows master machine add the new AMI in the Jenkins configuration section:

 

Which should take you to this Jenkins URL:

> http://localhost:8080/configure

We already have our Amazon EC2 service configured in Jenkins. And under this configuation we have two servers configured already:

i. RocketChat-Server (AUT running on Linux)
ii. Windows-Client (Selenium windows server)

We’re going to add a third now (very similar to the RocketChat-Server)

iii. Perfromance-Client (JMeter Linux server)

Click the ‘Add (List of AMIs to be launched as slaves)’ button right at the bottom of the page:

 

  1. Configure this new AMI with the following parameters:

Description: Performance-Client
AMI ID: ami-9abea4fc *1
Instance Type: T2Micro
Security group names: Unix-AUT, default
Remote user: ubuntu
AMI type: unix
Remote ssh port: 22
Labels: PerfServer *2
Usage: Utilize this node as much as possible
Idle temination time: 60 *3
Init script: <see below>
Number of executors: 1

You’ll still have to enter the ‘Init script’ as show below but every thing else can be left blank for this AMI’s settings.

*1 – note that the AMI may be different for you. This depends on which AWS regieon you’re using. Of course Amazon may just have removed this AMI and added a new one with a different AMI ID. You’ll need to search in your AWS console for something similar to “Ubuntu Server 14.04 LTS (PV),EBS General Purpose (SSD) Volume Type. ”

*2 – we’re going to user this Label (PerfServer) to force the performace job to run on this machine

*3 – setting the idle temination time to 60 minutes means that we’ll automatically shut this server down when it’s not in use. We only need this AMI running when we’re running our performance tests.

The init script we’ll want to enter is as follows.


‘’’
#!/bin/sh
# Update existing packages and install Java
export JAVA="/usr/bin/java"
if [ ! -x "$JAVA" ]; then
    sudo rm -rf /var/lib/apt/lists/
    sudo apt-get -y update
    sleep 10
    sudo apt-get install -y openjdk-7-jre ca-certificates-java tzdata-java libcups2 libcups2 libjpeg8 icedtea-7-jre-jamvm openjdk-7-jre-headless openjdk-7-jdk git npm jmeter
    sleep 5
fi

# Add Swap Space
SWAP=/mnt/swap1
if [ ! -f $SWAP ]; then
    sudo dd if=/dev/zero of=$SWAP bs=1M count=2K
    sudo chmod 600 $SWAP
    sudo mkswap $SWAP

    # add new swap to config and start using it
    echo "$SWAP none swap defaults 0 0" | sudo tee -a /etc/fstab
    sudo swapon -a
fi

‘’’

All we’re doing with this is making sure Java is correctly installed (for our Jenkins slave process), setting up our disk swap space and installing JMeter. Note that this init script is the same as our Rocket Chat server script except that we’ve added ‘jmeter’ to the list on the ‘apt-get install’ line.

At the end of this you should have something like this…

 

Lastly we need to configure a Tag. So click on the ‘Advanced’ button:

 

Find the ‘Tags’ section and click the ‘Add’ button:

Now enter the following values:

Name: Name
Value: Perf-client

You should have something like this:

 

Setting this up means that we’ll see the Name field populated automatically:

 

That’s nice but there’s a more important reason behind this. We have a Linux AWS instance that runs the Rocket Chat application. We also have a Linux AWS instance that will run our performance tests. Trouble is both of these machines are configured identically. If one is running in AWS and we try to start the other Jenkins thinks we already have one machine running that meets our criteria, so Jenkins won’t run the second machine up. By setting this tag Jenkins will run up two separate machines (even though they are identical configs). So it’s very important to set these tag values.

Save this and then we can check it launches okay.

  1. At this point we can run this performance client up and just check everything is okay the JMeter install. In Jenkins manage the nodes:

 

Which should take us to this Jenkins URL

http://localhost:8080/computer/

And from here we can provision the Performance client AMI

 

  1. You can check this is running up in your AWS account as follows:

 

And then login using ssh. So get the ‘Private IP’ (it’s IMPORTANT that it’s the private ip) address from your AWS account for this new server and then open the ssh client that’s already running on the windows master machine:

 

Enter the private IP address of the new linux machine and ‘Open’ the ssh terminal, accept the putty security alert and you should have your new linux terminal session. You just need to enter ‘ubuntu’ as the user name and you’re in.

  1. Check that JMeter is installed

Once you have the terminal open type this at the command prompt:

jmeter -v

And you should see the version of JMeter something like this…

 

Which confirms that JMeter is installed. You can close this terminal. We’re ready to start configuring our Jenkins performance job and deploying our performance scripts to this new server.

If you get a message saying that JMeter is NOT installed then go through the next section. This will explain what to do if your Performance client isn’t installed correctly.

Part 5: Parameterise our JMeter Project

We’ve configured our JMeter project and we’re ready to set this up as part of our Jenkins jobs now. Only slight problem is that the hostname of our Rocket Chat server is going to change everytime we re-build and install Rocket Chat. That means the hard code Server Name we’ve entered in JMeter won’t work. So we need to parameterise this value in our JMeter project.

The aim is to pass the Rocket Chat hostname as a command line argument to JMeter when we kick off the performance test. To do this we need to update our JMeter ‘HTTP Request Defaults’ properties.

  1. In JMeter open the ‘HTTP Request Defaults’ config element

 

  1. Update the Server Name field with this string

${__P(serverName)}

Like this

  1. Save your JMeter project

 

Now when we run our JMeter project from our Linux performance machine we’ll be able to run it with a command line like this:

jmeter -n -t RocketChat.jmx -JserverName=ec2-54-201-180-143.us-west-2.compute.amazonaws.com -l rcPerfResults.jtl

Where the arguments we pass on the command line are:

-n – run in headless/non-gui mode
-t – use the RocketChat.jmx configuration file
-JserverName – run the test against the Rocket Chat server with this hostname
-l – log the results to the rcPerfResults.jtl file

Only slight problem with this is that the server name is hardcoded. We need to pick up the public or private Ip of the host that is running our Rocket Chat application. If you remember in one of the earlier modules when we configured the AWS machine that is running Rocket Chat we had a script in Jenkins that created a publicHostname.txt file. In this file we had the public host name of the Rocket Chat. This txt file is archived as part of the ‘BuildRocketChatOnNode’ job and then passed to other jobs that use values as environment varialbes. We’ll hijack this file to add the private ip of the Rocket Chat server too. We can then use this value in our jmeter command line.

To configure this we’ll start by modifying the ‘BuildRocketChatOnNode’ job. On Jenkins dashboard click on the ‘Configure’ menu item for this job

 

Scroll to the of the config page and find the “Execute shell” section. At the bottom of this script you’ll find these couple of lines:

This is where we create the publicHostname.txt file. We need to add to this by including this line:

ifconfig eth0 | grep “inet addr” | awk -F: ‘{print $2}’ | awk ‘{print “PRIVATE_IP=” $1}’ >> publicHostname.txt

Once you’ve added this you should have:

 

Click the ‘Save’ button to save this.

This will run the linux ‘ifconfig’ command that spews out loads of network information for the host. We then run this through grep and awk to pick out the ip address and concatenate this with the text ‘PRIVATE_IP’. So it will add this line to the publicHostname.txt file:

PRIVATE_IP=172.31.29.xxx

We can then pass this publicHostname.txt file to our Jenkins Performance job and use the environment variable PRIVATE_IP to get the correct Jmeter arguments in the command line. So something like this:

jmeter -n -t RocketChat.jmx -JserverName=$PRIVATE_IP -l rcPerfResults.jtl

Don’t worry about this for now though, more on how we run this on the command line as we configure the Jenkins job in a moment. Before we do that we’ll need to run our ‘BuildRocketChatOnNode’ job so that we have the correct values added to our publicHostname.txt file

Once that job has completed, on your Jenkins machine you should be able to find this directory:


Opening this text file should confirm that we have two environment variables recorded in here.

All we need to do now is add the Jenkins Performance Plugin and configure the Jenkins performance job.

Part 6: Add and configure the Jenkins Performance Plugin

In Jenkins, in order to capture reports from JMeter we’ll add the ‘Performance Plugin’. Once this is installed and configured we’ll be able to chart the trend of performance results from one build to the next. It’s this trend that’s key to us spotting potential performance issues before it’s too late.

  1. Add the ‘Performance plugin’

 

  1. Once this is installed you should see the plugin listed on the ‘Installed’ tab in the Plugin Manager page on Jenkins (you might need to apply the filter to see this amongst all the other plugins installed)


We have our ‘Performance Linux Client’ configured. We have the Jenkins plugins installed that we need. Now we’re in a position to create the Job to run this performance from Jenkins.

Part 7: Configure the Jenkins Job to Deploy our Performance Tests

As mentioned previously our performance test files ought to be stored in a source code control system (possibly Git or Svn or something similar). That way when we develop our JMeter tests on our Windows machine we’d check them into our source code control system. Then we’d configure our Linux performance host to check out these tests from our source code control system before running them.

We’ll look at doing this the in a later stage but for now we’ll just get Jenkins to copy the JMeter configuration files on to the Performance Server when we need them.

First then, we’ll copy the JMeter ‘.jmx’ file to our Jenkins master machine in the ‘userContent’ directory. With the file in this location it will be available to the Jenink’s jobs to copy to our Linux Performance Server. Let’s get started on this.

  1. On the Windows master machine find the RocketChat.jmx JMeter configuration file.

The file should be in this directory (or whereever you installed JMeter):

C:\Users\Administrator\Desktop\apache-jmeter-2.13\bin\RC

 


This then needs to be copied to this Jenkins directory:

C:\Program Files (x86)\Jenkins\userContent

 

With this JMeter configuration file in the Jenkins ‘userContent’ directory it will be available to the new job that we’ll create next.

  1. Create the new performance job by clicking on ‘New Item’ on the Jenkins home page

 

Select ‘Freestyle project’ and call your new item ‘RunPerformanceTests’

 

  1. Configure the new job

This new job needs to complete a couple of key tasks. First we need to ensure it runs on our Linux Ubuntu AWS performace instance. Then we need to copy over the JMeter ‘.jmx’ file and then run the JMeter test (from the command line). To acheive this configure the job as follows:

Project name: RunPerformanceTests
Restrict where this project can be run: <checked>
Label Expression: PerfServer
Copy files into the job’s workspace before building: <checked>
Files to copy: RocketChat.jmx
Paths are relative to: $JENKINS_HOME/userContent

These settins should look like this when configured:

Restrict Where this project can be run:

 

Copy files:

 

With the core settings configured we can now add a few build steps:

  1. The ‘Copy Artifacts’ Build Step

First build step is the copy artifact from other project. We need to pull the publicHostname.txt file in from another project as that contains the hostname where Rocket Chat is running. We’ll create this as follows:

Add the ‘Copy artifacts from another project’ build step

 

And then set these parameters:

Project Name: BuildRocketChatOnNode
Which Build: Latest successful build
Artifacts to Copy: publicHostname.txt

So this build step should look like this:

 

  1. The ‘Inject Environment Variables’ Build Step

Next build step is the ‘Inject Environment Variables’ build step:

 

And for this one we need to get Jenkins to parse the data in the publicHostname.txt file and create an environment variable that will tell our performance host machine where Rocket Chat is running. Create this with just:

Properties File Path : publicHostname.txt

Which should look like this:

 

  1. The ‘Execute Shell’ Build Step

Now add the execute shell build step that will run the JMeter tests.

And set this up as follows:

Command:
jmeter -v
echo $PUBLIC_HOSTNAME
echo $PRIVATE_IP
jmeter -n -t RocketChat.jmx -JserverName=$PRIVATE_IP -l rcPerfResults.jtl

So the first three lines give us a little bit of debug info if we need it. The forth line starts and runs our JMeter tests sending the results to the rcPerfResults.jtl file.

  1. Run and test the Performance Test Execution

Lets just run this quickly and check that we see the results we expect. Click ‘Build Now’ for the ‘RunPerformanceTests’ job from the Jenkins home page

Then check the log file for the build

 

Which should give you something like this:

 

Now all we need to do is configure a Post Build Build Action that publishes the performance report.

  1. Configure the Post Build Performance Report

Next then add a post build task, which should give you the option to add a Performance Report as we have the Jenkins Performance Plugin installed.

Click on the ‘Add post-build action’ button and select ‘Publish Performance test result report’

 

In this build job section click the ‘Add New Report’ button and select ‘JMeter’ :

 

IN the new Report file field that is displayed we just need to add our ‘rcPerfResults.jtl’ file name:

Report files: rcPerfResults.jtl

Which gives us this …

 

Save the whole job and return to the Jenkins home page. We’re ready to run Performance Tests from Jenkins now.

Part 8: Check the Performance Job and Configure in the Whole Build Chain

Everything is configured now. We need to check our ‘RunPerformanceTests’ job in isolation and then link this job into the whole build chain.

  1. From the Jenkins home page click on the ‘build now’ icon for the ‘RunPerformanceTests’ job:

 

As the performance reports are ‘trending’ reports you may want to run this job two or three times. That way when you view the results we’ll have some trend data to view. So click the build job icon again.

Once the job has completed for the 2nd or 3rd time check the build job results by clicking on the job name:

 

From here you’ll see the Performance Trend graphs:

 

And if you click on the ‘Performance Trend’ links you can drill down into more detail (both of these charts can be viewed in a larger scale by clicking on them):

 

Now all we need to do is add this to the chain of other jobs that build and test our RocketChat application.

  1. Update ‘RunPerformanceTests’ to run after ‘RunApiTests’

From the Jenkins home page we’ll need to modify the ‘RunPerformanceTests’ job so that it waits for the ‘RunApiTests’ to finsh then starts. Configure the ‘RunPeformanceTests’ job

 

 

Set the parameters for the ‘Build after other projects are built’ option:

Build after other projects are built: <checked>
Projects to watch: RunApiTests
Trigger even if the build is unstable: <set>

This should give us the following:

 

Where we will be waiting for the ‘RunApiTests’ to complete. Even if the ‘RunApiTests’ fail we want to run our performance tests. So we’ve set this to trigger even if the build is unstable.

Save the changes to this job and we’ll check the test jobs all run in turn.

  1. Check all the test jobs run in sequence

Again from the Jenkins main home page we’ll manually trigger the build of the ‘RunClientRDPSession’. This is the job that’s triggered after the Rocket Chat build is complete. We already have Rocket Chat running so we’ll simulate the run from this point in the chain.

 

 

What we should see once we’ve started this is

i. the RDP session open to the client windows test machine
ii. the browsers open in turn as the Selenium tests run
iii. the Api tests run in the background
iv. the RDP session close
v. the performance tests run in the background

Both the Api and performance tests are running in the background so not a lot to see when these run. However, on completion we should have a full set of passed test results all run in sequence:

 

 

At this point you can drill down into the Api tests and check these results. Click on the build number for the ‘RunApiTests’ job and then select ‘History’ or ‘Test Results’:

 

Then do the same to check the performance test run results. click on the link for the ‘RunPerformanceTests’ job and then select ‘Performance Trend’:

 

And there we have it. A full test run. End to end, functional tests with Selenium, Api functional tests with SoapUI and Api performance tests using JMeter. All run with a single click of a button.

Conclusion

Once you start to get a feel for Jenkins building up each of the blocks to create an end-to-end test run covering Gui functional, Gui Api and performance tests isn’t too difficult. Admitidly we’ve only touched the surface of these tools like Selenium, SoapUI and JMeter. With the basics though it’s easy to start building out a lot of these tests and increase the test coverage significantly.

The key from here though is making sure the build and the test run are run on a regualr basis. Either configuring the build job for Rocket Chat to run every night or triggering it from source code check-in monitoring (a topic for another course). Kick everything off automatically on a regular basis AND add a few test cases each day. Before you know it you’ll have a large regression pack.

What’s more is you’ll soon find it easier to add an automated test case than writing and running a manual test case. And once you hit this you’ve nailed test automation!

Free Test Automation Framework Course
Learn the Practical steps to building an Automation Framework. Six modules, six emails (each email a short course in it's own right) covering Amazon AWS, Jenkins, Selenium, SoapUI, Git and JMeter.
Facebooktwittergoogle_plusredditpinterestlinkedinmail

In this module we start to put together some API tests to check the REST Api that is delivered as part of a Rocket Chat install. The moment the Selenium tests complete Jenkins will trigger SoapUI to run a number of REST based API tests from one of the Windows AWS client machines. In setting this up we’ll cover a few key areas:

1. Looking at the Rocket Chat API calls
2. Installing and writing SoapUI REST API tests
3. Driving SoapUI from Jenkins
4. Using the Jenkins xUnit plugin to display test results

We’ll run in to a few small challenges whilst setting this up. For example the rocket Chat Api returns some security credentials after the initial login. In order to successfully run all the other REST tests we need to pass those credentials between all the different test cases. We’ll look at how you can configure this in SoapUI.

Once we have SoapUI running the tests we’ll see how we can save the results in JUnit format. Then using the Jenkins xUnit plugin you’ll learn how to capture those test results and display them from within Jenkins. This is a great way to introduce you to an important plugin that has a multitude of uses when tracking xUnit results from various sources.

What You’ll Learn

In this module we’re going to look at creating and running some REST API tests. We’re going to use the open source tool SoapUI to run these tests. Of course these tests will all be initiated from Jenkins once the build of the Application Under Test (AUT) is complete. We’ll look to run these SoapUI API tests in serial from the same test machine that we’re running the Selenium tests from. The Selenium tests will complete then the SoapUI tests will be kicked off.

Once this is configured we’ll have these pieces in place on our test automation rig:

This is an important module because we’re starting to build out the bredth of our test coverage now. You’ll find the configuration of Jenkins quite straight forward now. However, we’ll show you how to overcome a few key challenges like passing parameters in SoapUI and displaying JUnit results within Jenkins.

The Tools We’ve Chosen

We’ve picked SoapUI. Mainly because of it’s popularity but also because it’s GUI is easy to get started with. It’s also simple to covert the tests we write into a test suite that can be run from the command line – which is what Jenkins needs.

SoapUI also provides us with the capability to record test results in JUnit format. This format can be read by the Jenkins xUnit plugin which allows us to display all of our REST Api test results from within Jenkins.

Worth pointing out here that the Rocket Chat API is a REST api. SoapUI might imply support for SOAP api’s but it does support REST too.

Prerequisites

If you’ve followed Modules 1, 2 and 3 you should already have your Amazon Virtual machine environment up and running along with Jenkins and Selenium. This setup gives us the 3 machines we’ll need to use in this module.

1. Windows Master machine: this is running Jenkins and controlls all our other machines (including the installation of the AUT and the exection of our Selenium tests). This machine will be responsible for kicking off our SoapUI API tests

2. Linux Client machine: this Ubuntu linux machine is run up on demand by Jenkins and then has the AUT (Rocket Chat) autoamtically installed on it. This machine provides the web interface for the Rocket Chat application and the API for the Rocket Chat application.

3. Windows Client machine: this Windows Server 2012 machine has 3 browsers (Ie, Firefox and Chrome) installed on it along with Selenium. The Windows master machine kicks off the Selenium tests that drive the 3 different browser tests against the Rocket Chat application.

Check the Status of your AWS Machines

Both of the windows machines should already be running. The Linux machine may or may not be running. The Linux machine is run up automatically by Jenkins so it’s fine if it’s not running. Whatever the state of the linux machine you should see the Windows machines status in the AWS console as follows:

 
 

 

Open an RDP Terminal Session on the Windows Master Machine

With these windows machines running you’ll need to open an RDP session on the Windows Master machine. This is where we’ll be configuring Jenkins.

 

 

 

Then enter the password (you may need your .pem private key file to Decrypt the password if you’ve forgotten it) to open up the desktop session.

Start the Linux Client Machine

IF the Linux machine isn’t running with the AUT installed then we need to start it. We can get Jenkins to do this for us. Once you have an RDP session open to your Windows Master machine you should have the Jenkins home pages displayed. If not open a browser on this machine and go to this URL:

 http://localhost:8080/

From here you can start the ‘BuildRocketChatOnNode’ job and start up the AUT.

 

 

 

Once RocketChat is up and running we’ll need to know the host name that Amazon has given our new Linux instance. We save this in our ‘publicHostname.txt’ file that is archived as part of our build job. So if you go to this directory using Explorer

C:\Program Files (x86)\Jenkins\jobs\BuildRocketChatOnNode\builds\lastSuccessfulBuild\archive

You should find this publicHostname.txt file…

 

 

 

Open this with notepad and make a note of the hostname. We’ll need this while we setup our API tests.

Open an RDP Terminal Session on the Windows Client Machine

As we’re utalising our existing Clicent Windows 2012 R2 test machine we don’t need to configure any new Amazon instances or machines. We have what we need running already. We just need to open an RDP terminal and install the software we need. To open the RDP terminal:
  

 

 

Again enter the password (you’ll need the .pem private key file again if you need to Decrypt it) to open up the desktop session.

At this point you should have…

1. An RDP session open to your Windows Master machine
2. An RDP session open to your Windows Client machine
3. Your Linux Ubuntu machine running with Rocket Chat installed

From here we’ll start to setup our Windows test machine and configure Jenkins on the Master machine to run the tests.

Part 1: Install SoapUI

We’re going to use our existing Windows client machine for this. So once we have the RDP session open we can download SoapUI and install it on our Windows Server 2012 R2 64 bit machine.

Only a few steps to follow here then, all to be carried out on the Windows client machine:

1. Open a browser

2. Enter the following address:

https://www.soapui.org/downloads/open-source.html

3. Download the ‘Windows Installer (64 bit)’ package

 
 

 
 

4. Run the installer, accept the agrements and accept all the default options…

 
 

 
 

Once you’ve finished you should be presented with the SoapUI user interface:

 
 

 
 

Now we have SoapUI running we can check the connection to the Rocket Chat Rest API.

Part 2: Connect to the Rocket Chat API

So Rocket Chat, our AUT, comes installed with a REST Api. This API is documented here:

https://github.com/RocketChat/Rocket.Chat/wiki/REST-APIs

On your install of Rocket Chat you should be able to connect to the Api directly with a browser here…

http://<your-amazon-aws-instance >:3000/api/

Remember earlier we said you could get your host name from the publicHostname.txt file on the Windows Jenkins master machine. So if you replace the <your-amazon-aws-instance> text with your public hostname you should be able to connect to this Api from any remote machine. You’ll see something like this:

 
 

 
 

If you have trouble connecting from outside your Amazon Virtual Private Cloud you’ll need to check your Security Group settings in your AWS control panel. If all else fails connect from the Windows Client machine (the one with SoapUI now installed).

One final check before we start writing some SoapUI tests. Lets check we can the version of Rocket Chat that’s running from the API. We’ll do this from the Windows client machine. So in the Windows Client machine RDP session…

1. open Chrome (it must be Chrome)
2. browse to this URL

http://<your-amazon-aws-instance >:3000/api/version

3. check the Rest response

You should see this Json structure returned in the Rest response:

 
 

 
 

The reason we had to use Chrome there is that Ie isn’t that happy displaying Json without messing around a bit. Easier just to use Chrome.

We’ve confirmed that we can connect to the Rocket Chat API and that we can get a valid response. Lets start writing some tests.

Part 3: Creating Some REST Requests

Now we have access to the Rocket Chat API we can start creating some REST requests. These requests will be written in SoapUI and executed on the Windows Client machine. Eventually we’ll have these tests kick off automatically from Jenkins.

For now though lets write some requests in the SoapUI gui and get them working. We need to create a new REST project and …

1. create a new REST project and enter the Rest URI

 
 

 
 

and then enter the URI for your Rocket Chat Rest API and click ok

http://<your-amazon-aws-instance >:3000/api/version

This should give you something like this…

 
 

 
 

The navigator section here showing you the hierarchy of project, endpoint, resource, method and finally request. We’ll look at each of these in detail next.

2. Define the request

In the request window we’ll configure a request to check the version number. So set the following:

Method: GET
Endpoint: (already set)
Resource: /api/version

It should look like this:

 
 

 
 

This particular request doesn’t have any parameter or body send. So we’ve defined enough now to check this. Before we move on though a few basic points about SoapUI

In SoapUI we basically have 3 main panels for each request:

1. Request details: the method (eg. GET, POST, etc), Endpoint, Resource and Parameters

2. Request body: any additional content (e.g. body or parameters) that need to be included in the request

3. Response: the response that comes back from the Endpoint after the request has been sent

These different panels are shown here…

 
 

 
 

In addition to this we have our green ‘Submit Request’ button that sends the request we define. Let’s see how this works.

3. Test an Initial Request and Check the Response

We can now click on the ‘Submit Request’ button …

 
 

 
 

And check the response. The result? Probably not very exciting. You probably got the error message…

“The content you are trying to view cannot be viewed as XML”

We already know, from our earlier call using a browser, that the response is in Json format. Just need to click the ‘Json’ tab to view the response then:
 
 


 
 

We can also check the raw response and make sure we received an Http 200 Ok response code:

 
 

 
 

Next then we’ll add a few more requests to login, list the rooms and log out again. From there we can add all these requests to a test suite and define some assertions.

4. Add More Requests

At this point we need to add three more requests. Requests to login, list the rooms and log out again. To add each of these 3 requests we’re going to repeat these steps:

1. Clone Resource

 
 

 
 

2. Name Resource

 
 

 
 

3. Open the request (double click)

 
 

 
 

4. Set the Method

 
 

 
 

5. Set the resource

 
 

 
 

6. Set the parameters

 

You’ll need to click in the parameters field here then the dialogue box opens up where you can enter the parameters
  

 
 

7. Specify the Post data

On some requests you need more than just the end point and resource. You’ll need to send additional data (e.g. like a browser does when you complete and html form and press the submit button). You’ll need to define that data and pass the data using a specific content-type
  

 
 

8. Set the header

You only need to set these values once you’ve completed the login request (this is NOT needed on the login request). Basically you run the login request, an auth token and userId are returned from that request. In all sebsequent requests you’ll need that ‘auth token’ and ‘userId’ to complete the requests.

 
 

 
 

You’ll need to repeat the above steps and create these three requests:

Request 1 – Login

Resource Name: Login
Method: Post
Resource: /api/login
Data (1): user=admin
Data (2): password=tester123
Post QueryString: <checked>

Create this request then run it.

You should have something like this after you’ve configured and run the request:

 
 

 
 

And the Json response containing data like this:

{
“status”: “success”,
“data”: {
“authToken”: “-7GGh68UQ5B0zbuLAEj29DO95H3uNg2HvRgZg63-nMF”,
“userId”: “bNitLrJ3rhZq5uLMR”
}
}

You need then to take the authToken and userId and use them in the next requests.

Request 2 – List the Chat Rooms

So go back and repeat steps 1 to 8 above using this data:

Resource Name: publicRooms
Method: Get
Resource: /api/publicRooms
Data: <remove data fields>
Post QueryString: <unchecked>
Header(1): X-Auth-Token=<authToken>
Header(2): X-User-Id=<userId>

Create this request then run it.

You should get a response like this:

 
 

 
 

And Json data equivalent to this:

{
“status”: “success”,
“rooms”: [ {
“_id”: “GENERAL”,
“ts”: “2016-03-01T10:57:10.758Z”,
“t”: “c”,
“name”: “general”,
“usernames”: [“admin”],
“msgs”: 0,
“default”: true
}]
}

Request 3 – Logout

So go back and repeat steps 1 to 8 above using the data below. Make sure you clone the ‘publicRooms’ resource as this one already has the headers defined:

Resource Name: logout
Method: Post
Resource: /api/logout
Data: <remove data fields>
Post QueryString: <unchecked>
Header(1): X-Auth-Token=<authToken>
Header(2): X-User-Id=<userId>

Create this request then run it.

You should get a response like this:
 
 

 
 

And a Json response containing this data:

{
“status”: “success”,
“data”: {“message”: “You’ve been logged out!”}
}

Don’t forget if you want to expand all these tests and create your own you can refer to the list of supported requests here:

https://github.com/RocketChat/Rocket.Chat/wiki/REST-APIs

We now have a few requests that work. We just need to convert them to tests and create some assertions that check the responses.

Part 4: Converting the REST Requests to Tests

From here then we have 4 REST requests that all give us valid responses. With SoapUI the next step is to convert them to tests and create the assertions that validate the responses. Two ways you can do this:

1. Create individual test cases for each Request

NOTE: you can do this one by one (as listed below) or you can jump to section 2 below and convert the whole lot in one go. The choice is yours.

i. Right click on the ‘request’
ii. Select ‘Add to TestCase’
  

 
 

iii. Create the Test Suite (just give it a test suite name)
iv. Create the Test Case (just give it a test case name)
v. Accept the default options for adding the test case

 
 

 
 

Easier to use method 2 though…

2. Create test cases within a test suite for all resources.

i. Right click on the ‘end point’
ii. Select ‘Generate Test Suite’

 
 

 
 

iii. Select <create> test suite and create ‘One Test Case for each Resource’

 
 

 
 

iv. Give the Test Suite a name (e.g. RCTestSuite)

In the navigator panel you should then see something like this…

 
 

 
 

We now need to update each Test Case so that it has some assertions that check the results from the test run. We’ll also need to look at passing some values between test cases. We’ll need to pass values because the login test case response has the ‘authToken’ and ‘userId’ values that subsequent test cases need.

3. Add the Test Case Assertions

We can select the first test case (the one that gets the version of Rocket Chat) and add our first assertion. Make sure you have the Request work space open:

 
 

 
 

Then click on the assertion button to open the assertion panel:

 
 

 
 

Then we’ll add our first assertion. For this test case it’ll just be that the response is a valid HTTP Status Code 200 Ok:

 
 

 
 

After you’ve clicked the ‘Add’ button just enter 200 as the code:

 
 

 
 

And then click okay. You can confirm that this works by clicking the green ‘Submit’ button for the request and then check that your assertion passes:

I’ll show you one more example of an assertion that checks the content of a Json response. Then you’re on your own for adding a range of assertions for all of the test cases.

Next select the Login TestCase Request and open the work space (double click the request):
 
 


 
 

This time you’ll notice that I’ve run the request before I’ve created the assertion. You can see the Json response that I want to create the assertion for now.

Click the add assertion button and select the ‘JsonPath Count Match’:

 
 

 
 

We know that if the login is successful then we’ll see this in the response…

{
“status”: “success”,
“data”: {
“authToken”: “-7GGh68UQ5B0zbuLAEj29DO95H3uNg2HvRgZg63-nMF”,
“userId”: “bNitLrJ3rhZq5uLMR”
}
}

What is absolutely crucial is that we get back this ‘data’ structure because we need the ‘authToken’ and ‘userId’. We need these for the subsequent requests we’re going to send. So let’s create this assertion so that it checks for the ‘data’ structure. We’ll enter these values in the dialogue box:

JSONPath Expression: $.data
Expected Result: 1

You can click the test button to check this in the dialogue box too:

 
 

 
 

From here you know enough to start experimenting with adding further assertions to the other requests. Just follow exactly the same process we’ve covered above.

What’s important now is to string these Test Cases together and pass the ‘authToken’ and ‘userId’ from one Test Case to the next.

NOTE: might be worth saving your project at this point. File menu, Save All Projects. You can save it with the default name of “REST Project 1”

4. Passing Parameters to our Test Cases

What we need to do now is work at the Test Suite level, link all these Test Cases together in a chain and pass some parameters between the Test Cases. So double click on the ‘Test Suite’ node and open the ‘Test Suite workspace’. Then click on the ‘Properties’ button to open up the properties panel.

 
 

 
 

We need to create a couple of properties at the Test Suite level. So click the ‘plus’ button and add ‘userId’ and ‘authToken’ properties.

 
 

  
These properties will be set by the Login test case. Then these properties can be used by the other test cases as part of the Headers to enable access for each request. Next step is to set these Test Suite level property values.

Right click on the ‘Login’ TestCase and add a ‘Property Transfer’ test step to this test case. You can give this test step the default name of ‘Property Transfer’:

 
 

 
 

Then open the workspace for this Property Transfer Test Step (double click). Then add 2 Transfer values, userId and authToken:
  

 
 

Now all we need to do is set the source and target for these property transfers. The source will be the Login Test Case response that returns the ‘userId’ and ‘authToken’. The Target will be the Test Suite level properties (which then makes these values available to ALL test cases in the suite).

Set the authToken first by setting these values…

authToken

Source: Request 1
Property: Response
Path Language: JSONPath
Path: $.data.authToken

Target: TestSuite
Property: authToken
Path Language: JSONPath

It should look like this…

 
 

 
 

Then set the userId …

userId

Source: Request 1
Property: Response
Path Language: JSONPath
Path: $.data.userId

Target: TestSuite
Property: userId
Path Language: JSONPath

Which should look like this…

 
 

 
 

We can check this setup by clicking on the ‘Run All Property Transfers’ button. From the Transfer log we should see these values picked up from previous responses from the login request:

 
 

 
 

And now the properties are available at the Test Suite level we can use them to run the other test cases. Just need to tweak the other test cases where the ‘authToken’ and ‘userId’ are currently hard coded.

Edit the ‘publicRooms’ test case and click on the ‘Header’ button so that we can add these TestSuite parameters to the Header values. We’ll need to add these property strings to get the Header values to use our TestSuite properties:

X-User-Id: ${#TestSuite#userId}
X-Auth-Token: ${#TestSuite#authToken}

So replace the hardcoded values with these strings so that you have this:

 
 

 
 

You can check this setup by clicking the green submit request button for this test case. Assuming it works what we now have is the ability to run the Login test, get the dynamic authentication variables that Rocket Chat passes us back in the response, and use these variables in all the other test cases.

All you need to do now is update the Logout Test Case to. The logout test case should look like this:

 
 

 
 

Next step then is to get these TestCases to all run in series, end to end.

5. Running the Test Suite

Well this bit is probably easier than you’re expecting. Just open the TestSuite workspace and click on the ‘Run’ button. You should see each test case within the Test Suite run in turn. Each test case highlighted in green to indicate that it’s passed.

 
 

 
 

All we need to do now is get this running from the command line and get Jenkins to kick the API test run off.

Oh! Probably worth saving your SoapUI project at this point!

Part 5: Running the SoapUI Test Suite from the Command Line

There is an easy way to work out how to run this Test Suite from the command line. You can initiate a command line run from the SoapUI gui and then copy the command line that the GUI gives you.

1. Launch the TestRunner

To do this, from the ‘Project’ menu select ‘Launch TestRunner’:

 
 

 
 

This will give you the test runner dialogue box. One the ‘Basic’ tab all we need to define is the path to the TestRunner. When we run these tests from the command line we’re basically running a windows batch file called ‘testrunner.bat’. You just need to set the path to this file to:

TestRunner Path: C:\Program Files\SmartBear\SoapUI-5.2.1\bin

The version number in the directory may change for you but it should be like this…

 
 

 
 

Then on the ‘Overrides’ tab we just want to select our Endpoint. We need to see how to pass the value in on the command line so setting it here will get SoapUI to use this value as a parameter.

 
 

 
 

Then click ‘Launch’ to run this. A successful run should look like this…

 
 

 
 

A few exceptions in there with this release of SoapUI. Nothing to worry about. We can fix these by stopping SoapUI trying to load these plugins.

2. Clear the Exceptions (optional step)

To clear all these unwanted exceptions open explorer and go to this directory

C:\Users\Administrator.soapuios

Close SoapUI after you’ve saved your project. Then rename the plugins directory to something like ‘plugins-old’. Like this…

 
 

3. The Command Line

What we’re really interested in though is the command that was run by the TestRunner. If necessary re-run the test runner from SoapUI. Then click ‘OK’ and scroll back up to the top of the Test Runner windows. You need to locate this…
 
 


 
 

From this you can pick out and copy the command line you need. Like this…

directory: C:\Program Files\SmartBear\SoapUI-5.2.1\bin
command: cmd.exe /C testrunner.bat -ehttp://<your-aut-host>:3000 C:\Users\Administrator\REST-Project-1-soapui-project.xml

You’ll want to modify this slightly so that you have this format…

cmd.exe /C “C:\Program Files\SmartBear\SoapUI-5.2.1\bin\testrunner.bat” -ehttp://<your-aut-host>:3000 C:\Users\Administrator\REST-Project-1-soapui-project.xml

Note the path in front of the bat command and the inverted commas. This is what we’ll test before we add it to a Jenkins job. So lets check this from a command line prompt. Open a command window and run this command:

 
 

 
 

When it’s completed check the error level with a command like ‘error %errorlevel’:

 
 

 
 

If all the tests passed then the error level should be ‘0’. If any failed then the response should be ‘-1’. You can test this if you like by slightly modifying one of your test cases in SoapUI to make it fail (change the assertions on one of the TestCases or something). Then run the command line command again and check the error level is ‘-1’.

Nearly there now. Just need to plug this all into a Jenkins job.

Part 6: Running the SoapUI Test Suite from Jenkins

First we’ll need that SoapUI command from the previous step. So you’ll have something like this…

cmd.exe /C “C:\Program Files\SmartBear\SoapUI-5.2.1\bin\testrunner.bat” -ehttp://<your-aut-host>:3000 C:\Users\Administrator\REST-Project-1-soapui-project.xml

Back on to our Windows Master machine that’s running Jenkins (open the RDP session if necessary). Then bring up the Jenkins home page. From here we need to create a new job / new item:

 
 

 
 

We’ll make this a ‘Freestyle Project’ and call the job ‘RunApiTests’
 
 

  
We have a few key things to configure on this new job:

1. Restrict where this project can be run: SeleniumTestClient
 
 

 
 
2. Build Triggers:

Build after other projects are built
Projects to watch: RunSeleniumTests
Trigger only if build is stable
  

  
Then we need to add 3 new build steps. To create each one click on the ‘Add build step’ button, select the build step type and set the parameters (as set out below)

1. Copy artifacts from another project
We need this to pull in the publicHostsname.txt file from the ‘BuildRocketChatOnNode’ job. This way this build job will know where Rocket Chat is running.

2. Inject environment variables
We’ll take the contents of the publicHostname.txt file, that contains the host name where Rocket Chat is running, and use this value in the next batch command job.
  

  
3. Execute Windows batch command
This is where we’ll run our SoapUi command on the remote machine (the machine labled SeleniumTestClient). Note that we don’t need to hard code the host name. We can use the %PUBLIC_HOSTNAME% variable that’s set from the publicHOstsname.txt file. So enter your command like this:
  

  
Using this command:

cmd.exe /C “C:\Program Files\SmartBear\SoapUI-5.2.1\bin\testrunner.bat” -e%PUBLIC_HOSTNAME% C:\Users\Administrator\REST-Project-1-soapui-project.xml

No post build actions at this stage. So we can just save this job and return to the Jenkins home page.

Before we run this though lets setup things up so that Jenkins can actually report on the status of the tests run by SoapUI. To do this we’ll need a new plugin installed in Jenkins.

Part 7: Reporting the SoapUI Test Results in Jenkins

What we want to do now is see the individual test case results displayed in Jenkins. SoapUi can save the test results in a JUnit style report format. Then we can get the Jenkins ‘xUnit’ Plugin to display the test results. Lets install the plugin first.

1. Install the xUnit Jenkins Plugin

Just go to the Jenkins ‘Manage Plugins’ page, select the available tag and search for “xUnit”.

 
 

 
 

Click install without restart. Once the plugin is installed we can configure our SoapUI project to save the test results in JUnit format.

2. Modify the Jenkins ‘RunApiTests’ Job

Back on the Jenkins home page configure the ‘RunApiTests’ job.
  

  
What we need to do now is configure our SoapUI command line so that it save the test results in a JUnit format. We can do this by changing our ‘Execute Windows batch command’ from this:

cmd.exe /C “C:\Program Files\SmartBear\SoapUI-5.2.1\bin\testrunner.bat” -e%PUBLIC_HOSTNAME% C:\Users\Administrator\REST-Project-1-soapui-project.xml

to this…

cmd.exe /C “C:\Program Files\SmartBear\SoapUI-5.2.1\bin\testrunner.bat” -e%PUBLIC_HOSTNAME% -sTestSuite -j -fc:\jenkins\workspace\RunApiTests\ C:\Users\Administrator\REST-Project-1-soapui-project.xml

Note that we’ve added three parameters to this command:

-sTestSuite: defines the TestSuite to run (which we called ‘TestSuite’)
-j: Turns on exporting of JUnit-compatible reports
-fc:\jenkins\workspace\RunApiTests: which specifies the directory to save the report in

So now when we run this job we should get this file created on the client machine that will contain the individual test results:

C:\jenkins\workspace\RunApiTests\

It’s important to save this in the Jenkins workspace on the test machine. This way Jenkins will automatically make the JUnit files available to the master Jenkins machine for processing.

Don’t save this job yet. Still one more thing to configure. We have to get Jenkins to read those results and publish them.

3. Publish xUnit Test Results

Whilst we’re still editing the ‘RunApiTests’ job we can add a post build action. Click on the ‘Add post-build action’ button and select ‘Publish xUnit test result report’
  

  
Once this is added we need to add an xUnit type of report. Click on ‘Add’ and select ‘JUnit’
  

  
From here we can set the file names Jenkins needs to look for where the JUnit test results reside. Well SoapUI will be creating a JUnit file called TEST-TestSuite.xml. So we’ll need to configure this ‘Publish xUnit test result report’ to look for TEST*.xml files. So set these parameters:

JUnit Pattern: TEST*.xml
Skip if there are no test files: un-checked
Fail the build if test results were not updated this run: checked
Delete temporary JUnit files: checked
Stop and set the build to ‘failed’: checked

And that it’s really nothing else to set here (you don’t even need to set any of the test thresholds).
  

  
Save this job now and lets run the full set of Jenkins jobs.

On the Jenkins home page click the “Run now” button for the ‘BuildRocketChatOnNode’ job. This should end up running our full set of 5 jobs. And once complete we can check the console output for our ‘RunApiTests’ job.
  

  
That console ouptput should show you something like this at the end:

c:\jenkins\workspace\RunApiTests>exit 0
[xUnit] [INFO] – Starting to record.
[xUnit] [INFO] – Processing JUnit
[xUnit] [INFO] – [JUnit] – 1 test report file(s) were found with the pattern ‘*.xml’ relative to ‘c:\jenkins\workspace\RunApiTests’ for the testing framework ‘JUnit’.
[xUnit] [INFO] – Check ‘Failed Tests’ threshold.
[xUnit] [INFO] – Check ‘Skipped Tests’ threshold.
[xUnit] [INFO] – Setting the build status to SUCCESS
[xUnit] [INFO] – Stopping recording.
Warning: you have no plugins providing access control for builds, so falling back to legacy behavior of permitting any downstream builds to be triggered
Triggering a new build of CloseClientRDPSession
Finished: SUCCESS

If you get warnings about clocks being out of sync check the next section. If there results are okay then move on to ‘Reviewing the JUnit Results’.

4. What to do if Clocks are Out of Sync

The ‘xUnit’ plugin depends on the clocks, between master and slave nodes, to be in sync. If they’re not in sync then you might see an error like this in the console log for the ‘RunApiTests’ job

[xUnit] [ERROR] – Clock on this slave is out of sync with the master, and therefore I can’t figure out what test results are new and what are old.
Please keep the slave clock in sync with the master.
[xUnit] [INFO] – Failing BUILD.

If that’s the case take a look at the Jenkins configuration to confirm this.
 
 

  

So indeed on this system the client machines clock is running 17 seconds behind. To resolve this you’ll need to run these 4 commands on the ‘Client’ machine:

net stop w32time
w32tm /config /syncfromflags:manual /manualpeerlist:”time-a.nist.gov, time-b.nist.gov, time-c.nist.gov, time-d.nist.gov
w32tm /config /reliable:yes
net start w32time

 

Like this…

 
 

  
Then wait a minute or two. Go back to the Jenkins master machine and refresh the status:
  

  
And clocks are all back in sync.

5. Reviewing the JUnit Results

We’ve set the xUnit reporter to pass the build/job if all the tests fail. What happens if we see a failure though? Well if you first check the workspace for the job:
  

  
You’ll see the TEST-TestSuite.xml file and the other log files that were saved from the SoapUI test run:
  

  
From here if you look at the drop down menu for the last test run you’ll see an option for viewing the test results:
  

  
Click on this and you can then start drilling down through all of the unit test results:

  

  
And if you click the ‘History’ item in the right hand menu bar you’ll see a track record of all the SoapUI JUnit test results.
  

  

Conclusion

Well nothing too difficult on the Jenkins side of things this time round. By now you should be experienced enough to configure the Jenkins build job easily to handle the execution of the SoapUI test run. The only new thing we introduced here for Jenkins is the capability to process JUnit test results and display them. A key capability for tracking test results in many other tools controlled by Jenkins too.

We delved into a lot of SoapUI features to create a handful of REST based Api test cases. The only real complexity here being the passing of parameters between test cases. Once you’ve seen how to do this it not difficult to repeat the process and build up a good pack of Api test cases. Key to the success of this module though is the ability to run the SoapUI tests from the command line and get Jenkins to pick up the JUnit test result file. As long as you know where to pick up the SoapUI test runner application and configure the xUnit plugin none of this should have been too challenging.

At the end of this module then we have a test automation environment that covers installing our appliation under test, running a suite of GUI based browser tests with Selenium and now running a handful of API test cases using SoapUI. All started and executed with ‘one click’ on a ‘Run Now’ button.

In the next module we’ll look at how we can build in some performance tests with JMeter driven from Jenkins too.

Free Test Automation Framework Course
Learn the Practical steps to building an Automation Framework. Six modules, six emails (each email a short course in it's own right) covering Amazon AWS, Jenkins, Selenium, SoapUI, Git and JMeter.
Facebooktwittergoogle_plusredditpinterestlinkedinmail

As we look at driving a Windows client machine from Jenkins, to run Selenium based browser tests things get a little bit more involved. In this 3rd module of our Building The Test Automation Framework course we step things up a little bit. Nothing we can’t handle though as we take you through each step in detail.

We’re going to cover four key areas:

1. Setting up a Windows Jenkins salve machine
2. Install the test software on the slave machine (e.g. Python and Selenium)
3. Creating a basic Selenium script
4. Running the Selenium Scripts from the Jenkins Master Machine

Once you’ve completed all of these steps you’ll have setup a client Windows AWS machine that will run Selenium tests against our application under test (AUT). As always we’re looking to automate the whole process. So we’ll be configuring our Jenkins server to start the client machine and then control this client machine through the use of the Jenkins slave application.

A few complexities in this module though as Windows User Account Controls (UACs) do their best to prevent us from achieving our goals. We’ll show you some tips and tricks that get round a lot of these issues. Tips and tricks you’ll find invaluable when you come to creating your own Jenkins environments.

What You’ll Learn

In this module we’ll go through the 12 parts listed below looking at the practical aspects of setting up Selenium.

In this session we’re going to configure our system so that we automatically start a Windows test machine that we’ll run a set of Selenium browser tests from. This client windows machine will be automatically started by Jenkins. Once running the Selenium scripts will be started by another Jenkins project.

Once complete we’ll have added the Selenium components to our system as shown below:

However, in order to run these Selenium scripts on a client windows machine we need a desktop terminal session that the scripts will run in. We want to run the test scripts in a real environment and see them running. We don’t want to run them in some headless mode that isn’t a true simulation of what an end user would be doing with the application under test.

Getting Jenkins to create RDP terminal sessions is quite tricky due to the way Windows implements user account control (UAC). So we’ll learn some tricks to get round this and how to really create a set of tests that represent real user actions.

One final thing to mention before we get started. This is a course on building the test automation framework using jenkins. It’s not a course on writing Selenium scripts. So the Selenium scripts we’re using are pretty basic. They server the purpose of implementing this framework and are easy to build on if you want to expand and plugin your own scripts later.

The Tools We’ve Chosen

We’re testing a browser based application so it seems sensible to choose Selenium as the tool to write our automated test cases in. We can get Selenium drivers for a range of different browsers so we’ll be able to provide test coverage against IE, FireFox and Chrome (we could do more but this’ll be adequate for now).

It’s important to point out though that this isn’t a Selenium course. So the Selenium scripts we’re using here are simple, linear and, well basic. This gives the added advantage that it makes things easier to understand. You just need to be aware that in order to scale the actual test cases you’ll probably want to look at improving the way these test cases are written (something we’ll get into in a later course).

So if we’re using Selenium the next question is what language are we going to write our test scripts in. Well “to stop the should it be C# or Java discussion” we discounted those two languages straight off. And because I’m keen on Python that’s what I chose. Then there’s the fact that it’s efficient, fast and easy to learn. Oh and there’s the point that the demand for testers that can code in Python is growing exponentially. So Python it is.

Prerequisites

Right, we need to make sure we have everything setup correctly before we start. First we need to be sure we’ve launched our Windows master machine and that we have an RDP session open.

Make Sure your Windows Master EC2 Instance is Running

If you don’t have your Windows master machine up and running yet then you’ll need to revisit Module 1 and take a look at the section on Running up the Windows Instance.

With the Windows 2008 master machine configured then we’ll need make sure the instance is running and that we have an RDP session open. You can complete these steps with

1. Open your AWS management console, and view your list of Instances (making sure you have the correct Region selected).



2.Once started open an RDP session on this Windows machine.



Then enter the password (you may need your .pem private key file to Decrypt the password if you’ve forgotten it) to open up the desktop session.

Make Sure you have your Private key (.pem file)

Remember back in Module 1 we created our public and private key pairs? Well at that stage you should have saved your private key pair .pem file (e.g. FirstKeyPair.pem) file. You’ll need this private key when configuring Jenkins later.

If you don’t have have this private key you can go back and create a new key pair. Much easier if you can find the one you created in Module 1 though.

Setup a new Security Group for Windows Client

For the Windows client machine it’s best to setup it’s own dedicated security group. We’ll need this as Jenkins connects to this machine with CIFS (Common Internet File System) and WinRM (Windows Remote Management). Both of these require access over specific protocols and ports.

To setup a new security group follow these steps

i. login to your AWS management console
ii. go to your AWS EC2 dashboard
iii. select ‘Security Groups’ in the left hand menu
iv. click on the ‘Create Security Group’ button
v. add the ‘Security Group Name’ – “Windows-client”
vi. add the description – “Windows client machine”
vii. leave the VPC field set to the default
viii. add the following rules then click ‘Create’

Security Group Rules

Inbound: Custom TCP Rule TCP 445 0.0.0.0/0
Inbound: Custom TCP Rule TCP 5985 0.0.0.0/0
Inbound: RDP TCP 3389 0.0.0.0/0
Outbound: All traffic All All 0.0.0.0/0

Part 1: Setup Our Windows Test Machine

Create a Windows 2012 Server Instance in AWS

Four things we need to create this Windows instance:

  1. Microsoft Windows Server 2012 R2 Base – ami-83a5bce2
  2. t2.micro
  3. Name: Windows-Client
  4. Security: default

Back to our EC2 dashboard then:

i. login to your AWS management console
Step 1: go to your AWS EC2 dashboard
Step 2: select the correct region
Step 3: click ‘instances’ in the side menu
Step 4: select the AMI listed above (Microsoft Windows Server 2012 R2 Base )
Step 5: select the Type listed above (t2.micro)
Step 6: accept all the ‘Instance Config’ defaults
Step 7: accept all the ‘Storage’ defaults
Step 8: [optional] add a tag for the Name if you like (e.g. Windows-Client)
Step 9: for the security group we’ll need to:
Step 10a: Select existing security groups
Step 10b: Check the ‘Windows-client’ security group AND
Step 10c: Check the ‘default’ security group
Step 11: Review and then ‘Launch’

Once the new instance is running you can use the EC2 console to put the instance into a “stopped” state. Don’t terminate it, just put it into a stopped state. We’ll start it up again using Jenkins later.

Part 2: Configuring Jenkins to Start A Windows Slave Machine

We’ve already configured Jenkins to run up one slave machine. This slave machine runs our Ubuntu Linux environment that hosts our Application Under Test (AUT) – Rocket Chat. Now we need to add to this environment and create a connection to the Windows slave machine that we’ll run our Selenium browser testing from.

First step is to configure this machine in Jenkins and make sure we can connect to it. We can complete all of this from the Manage Jenkins / Configuration page in the Jenkins Gui.

1. Open up Internet Exporer and type in this URL

http://localhost:8080/

2. In the Jenkins home page click on Manage Jenkins -> Configure System



3. At the bottom of the configuration page we need to create a new AMI. We already have our cloud settings configured so this time round we only need to add an additional AMI. So scroll to the bottom of the page and add an AMI



4. Enter the AMI details

Description: Windows-client
AMI ID: <see below>

We’re going to be using this slave machine to run a few different browsers and Selenium. We’ve already created instance and have this running with an AMI that gives us this type of server:

Microsoft Windows Server 2012 R2 Base 64-bit

The current AMI for this is…

ami-83a5bce2

However, this may change as AWS update their AMIs. The quickest way to check this and make sure you have the correct AMI is to

i. login to your AWS management console
ii. go to your AWS EC2 dashboard
iii. select the correct region
iv. click ‘instances’ in the side menu

Whilst you’re on this page it’s worth making a note of the ‘Availability Zone’ that your master Windows Jenkins machine is running in. We’ll need this in the next step. So note down this value…



Then continue with…

v. click the ‘Launch Instance’ button
vi. make sure the ‘Free tier only’ check box is checked
vii. look for the “Microsoft Windows Server 2012 R2 Base” AMI
viii. copy the AMI number (e.g. ami-83a5bce2)

You don’t actually need to launch an ‘instance’ here. You just need to make sure you have the AMI id that is associated with a Windows Server 2012 R2 Base 64 bit machine.

So at the end of this part you should have two pieces of information that we’ll need in a minute:

a. the ‘Availability Zone’ that your master Windows Jenkins machine is running in
b. the AMI id of a windows 64 bit 2012 R2 Base server that Amazon has available for you to create instances from.

Both of these peices of information will be needed in the next part.

5. Click on Check AMI to make sure AWS gives us access to use this AMI



6. Select the ‘T2Micro’ Instance Type (to make sure you stay on the AWS free tier)

7. Enter the Remote User, AMI Type and a few other values leaving everythying else as a default.

EBS Optimized: <un-checked>
Availability Zone: <get-from-aws-account> (*1)
Use Spot Intance: <un-checked>
Security group names: default, Windows-client (*2)
Remote FS root: c:\jenkins
Remote User: Administrator
AMI Type: windows
Windows Admin Password: <leave blank> (*3)
Use HTTPS: <un-checked>
Boot Delay: 3
Labels: SeleniumTestClient
Usage: Utilize this node as much as possible
Idle termination time: 30
Init script: <leave blank>

  *1 – set this to the same value as the Availabilty zone that your Windows Master Jenkins machine is running in

   *2 – we setup the Windows-client security group in the Prerequisites seciton of this module.

   *3 – we need to leave this blank for now. We’ll come back and update this in minute.

 

Once you’ve entered these values you should have something like this:



8. Enter the Advanced settings. You’ll need to click the ‘Advanced’ button to expose further settings that we need to update:



Most of these we can leave blank but you will need to update these values:

Stop/Disconnect on Idle Timeout: <checked>
Use private DNS: <checked>

The first setting here stops Jenkins ‘Terminating’ this windows instance if it’s been idle for 30 minutes. With this set if we hit the idle limit this instance will be ‘Stopped’ which preserves all our data.

The second setting for using the private DNS keeps the connection from our master Windows machine (running Jenkins) to our client Windows machine using DNS and hostnames that are private to our AWS Virtual Private Cloud. This just simplifies some of the security complexities for us.

At the bottom of the page you just need to click the ‘Save’ button

9. Start Windows Client Machine from Jenkins

In Jenkins we need to complete these actions to start the AWS Windows client machine instance:

i. go to the Jenkins home page
ii. go to ‘Manage Jenkins’ then ‘Manage Nodes’

On the nodes page we should be able to start our Windows client machine by clicking on ‘Provision via RocketChat Server’ button and selecting ‘Windows-client’



10. Check Windows Client Machine has started

On the Jenkins Nodes page you can click the ‘see log for more details’ link and see the node come up.



You should see a log message that confirms that the machine has been started…

>FINER: Node Windows-client (i-d9b15b01)(i-d9b15b01) is ready

However, you’ll also see that Jenkins is failing to connect and control this machine because we have this message repeating itself…

Waiting for WinRM to come up. Sleeping 10s.

At this stage we’ve started the Windows client machine from Jenkins. However, we’ve only been able to start it. We can’t yet connect to it from Jenkins. Automatically connecting to Windows machines is a little more complicated than our Linux equivalent (where we can just use SSH with our private key). Establishing the connection and control over this machine is what we’ll look at next.

Part 3: Completing the Windows Client Configuration

With the windows client machine started we still need login to it manually with an RDP session, setup some additional configuration manually and then update the Jenkins configuration. Once we’ve done this Jenkins will have complete control over this Windows client machine.

1. Connect Using RDP to the Windows Client machine

Going back to our AWS management console we need to start an RDP session on our Windows Client machine. Follow these steps to open the RDP connection:

i. login to your AWS management console
ii. go to your AWS EC2 dashboard
iii. select ‘Instances’ in the left hand menu
iv. click on the entry for the new Windows Server 2012 instance
v. right click on this instance and select ‘Connect’
vi. select ‘Get Password’ (you’ll need your .pem private key file again)
vii. Decypt the password and save it somewhere safe
viii. click ‘Download Remote Desktop File’

** Make sure you keep a copy of the password – we’ll need it again latert **

At this point you should have got to here…



2. Set Termination Behaviour

Whilst you’re in your AWS account now is probably a good time to set the termination behaviour for a couple of your instances. For instances where you don’t want to lose data it’s worth ‘Enabling Termination Protection’. This just stops you terminating these instances by accident.

i. select the instance
ii. right click on the instance and select ‘Instance Settings’
iii. then select ‘Change Termination Protection’ in the sub menu
iv. in the pop up dialogue box click the ‘Yes, Enable’ button



You’ll want to change this protection setting for both your Windows-master and Windows-client machines. Do NOT change it for your Unix-client machine (we need to terminate this on a regular basis).

3. Configure Windows client to allow CIFS and WinRM access

To allow Jenkins to install it’s Jenkins client on this machine and take control of it we need to update a few settings. We need to enable WinRM (Windows Remote Management) with the following:

i. Open a command prompt
ii. execute the WinRM commands below

WinRM Commands
winrm quickconfig
winrm set winrm/config/service/Auth @{Basic=“true”}
winrm set winrm/config/service @{AllowUnencrypted=“true”}
winrm set winrm/config/winrs @{MaxMemoryPerShellMB=“1024”}



and…



and…



That should give Jenkins the access it needs to connect to the machine. All that’s left now is to install Java so that Jenkins can install it’s client application. It’s this client application that gives Jenkins full control over the machine.

4. Install Java JDK on the Windows client

Jenkins needs Java installed (and Java in the path variable) in order to install and run it’s client/slave application. It’s this app that gives the Jenkins master machine full control over the client and enables it to run Jobs on the client. To install Java we’ll need to:

a. Open Internet Explorer and search for …

Download Java JDK

This should take you to a web page like this…



b. This will present you with this web page where you need to accept the licence agreement then select this package to save…



Note that you might have to change your Internet Explorer security settings here to allow you to download it.


Save this package to the desktop:



The run the installer (as Administrator):



Accept all the defaults as you follow through the install wizard.

c. Last thing is to just check that the install completed successfully and that we have Java in our path.

i. open a NEW command window
ii. type ‘java -version’
iii. type ‘echo %PATH’
iv. check for this in the path: C:\ProgramData\Oracle\Java\javapath



5. Update the Node Configuration in Jenkins

On the Jenkins master machine we just have to update a few configuration settings for the client now. So we’ll need to complete the following actions:

** NOTE: we’re back on our master Jenkins RDP session now! **

i. go to the Jenkins home page (http://localhost:8080)
ii. go to ‘Manage Jenkins’ then ‘Manage Nodes’

On the nodes page we should see our Windows client machine (with an ‘X’ against it as Jenkins has failed to connect with it). From here…

iii. Click the ‘Configure’ link in the side menu


On the Jenkins master machine weiv. Enter the Windows password

From step one above, we decrypted our password for this AWS instance. Hopefully you’ll still have this so that you can enter it here (if not go back to your AWS management console and get the password for this windows-client instance)


On the Jenkins master machine wev. click the save button at the bottom of the screen.

6. Establish Connection Between Jenkins master and Windows Client

At this point we should have everything we need for the master Jenkins machine to communicate with, and take control of, our windows client machine. From our Jenkins master machine follow these steps:

** NOTE: we’re still on our master Jenkins RDP session here! **

i. go to the Jenkins home page (http://localhost:8080)
ii. go to ‘Manage Jenkins’ then ‘Manage Nodes’

On the nodes page we should see our Windows client machine (with an ‘X’ against it as Jenkins has failed to connect with it). From here…


iii. click on the windows-client link
iv. click the ‘Relaunch slave agent’ button



At this point you should see the log file displayed automatically. After a minute or so the log file should start to show messages like this…

>FINER: Node Windows-client <instance-id> is ready
>Connecting to <ip-address> with WinRM as Administrator
>Waiting for WinRM to come up. Sleeping 10s.
>WinRM service responded.
>WinRM should now be ok on Windows-client
>slave.jar sent remotely. Bootstrapping it
>This is a Windows slave
>Slave successfully connected and online

At this point we have our Windows slave machine up and running. It’s running the Jenkins slave Jar too so the Jenkins master machine can control it and send jobs to it.

However, before we move on, let’s talk a little about what happens if you can’t get this connected.

Part 4: What to do when you Can’t Connect the Windows Slave

The connection between the Jenkins master machine and the Jenkins windows slave is established using Windows Remote Management (WinRm). This is installed and running by default when we create our Windows slave instance using the Windows Server 2012 R2 Base AMI.

However, sometimes you may find you run into problems connecting the two machines using WinRm. To see if the connection issue is down to WinRm configuration you can try this on the Jenkins Windows Master machine.

  1. In your AWS account find out what the ‘Internal IP address’ is of the “Client/Slave Windows Machine”. You’ll also need the Administrator password for this machine too.
  2. On the Jenkins master machine open a command terminal
  3. Run this command in the terminal window
winrm identify -r:http://<ip-address-of-client>:5985 -auth:basic -u:Administrator -p

What this does is try to connect to the client machine using WinRm (don’t forget to replace <ip-address-of-client> with the right client ip address). It’s basically simulating what Jenkins tries to do when it connects to the slave machine. Now, if you get this result, or any other connection error, you know you have an issue with your WinRM configuration…

>WSManFault
>Message = The WinRM client cannot process the request.
>Unencrypted traffic is currently disabled in the client
>configuration. Change the client configuration and try
>the request again.

In which case it’s worth trying commands like this on the Jenkins Windows Master machine:

>winrm set winrm/config/client @{AllowUnencrypted=“true”}
>winrm set winrm/config/client/Auth @{Basic=“true”}

Then when you try this command again…

>winrm identify -r:http://<ip-address-of-client>:5985 -auth:basic -u:Administrator -p

You should get a response along these lines:

>IdentifyResponse
>ProtocolVersion = http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
>ProductVendor = Microsoft Corporation
>ProductVersion = OS: 6.3.9600 SP: 0.0 Stack: 3.0
>SecurityProfiles
>SecurityProfileName = …

This is telling us that the connection was successful. If this is successful then Jenkins should be okay making the WinRm connection now. So you can try going back to Jenkins on the nodes pages and “Relaunching the slave agent”.

WinRm is a complete topic in it’s own right. However, using the commands above may well help you at least identify where the connection issue lies.

If you need to dig deeper into this topic then there’s a lot of helpful information on this page:

Installation and Configuration for Windows Remote Management

Another issue you might run into is slow response times from the slaves. This is especially true when we’re running low tier AWS instances. If you’re seeing the connection succeed then drop out again, there are a couple of options.

First, you could increase the AWS teir that your instance is running on. Of course if you do this you may run up charges and costs as these are unlikely to be on the free teir.

Secondly, you could try turning off the response time check as a temporary fix.
Go to Manage Jenkins -> Manage Nodes -> Configure, and uncheck the “Response time” box. This should stop Jenkins dropping the slave just because it’s not responding fast enough.

Part 5: Installing the Software we need on the Windows Slave

We have the slave Jenkins machine running and under the control of our main Jenkins machine. Now we can deploy some of the software we need to this slave machine so that it can run our Selenium tests. Software packages we’ll need will include:

Chrome
Firefox
Python 3.5

1. Open an RDP session on the Windows 2012 slave machine

i. login to your AWS management console
ii. go to your AWS EC2 dashboard
iii. select ‘Instances’ in the left hand menu
iv. click on the entry for the new Windows Server 2012 instance
v. right click on this instance and select ‘Connect’
vi. click ‘Download Remote Desktop File’

2. On your Windows 2012 Server client machine download and install the following:

Chrome: http://www.google.com/chrome
Firefox: https://www.mozilla.org/en-US/firefox/new/
Python: https://www.python.org/downloads/release/python-351/
(Windows x86-64 executable installer)

I’m not going to take you step by step through this because it should be pretty straight forward. Once you have those three installed we can walk through the process of setting up Selenium and then writing our first Selenium scripts.

3. Check Python is installed correctly.

a. open a command prompt
b. type ‘py’ followed by return
c. you should see “Python 3.5.1 (v3.5.1:37a07cee5969…”
d. type ‘exit()’ to come out of the Python shell

If this didn’t work you’ll have to go back to step 2 above and try re-installing Python again.

Now all we need to do is add the Selenium Python package to our install.

4. Install the Selenium Python package

If Python is installed correctly you should find it installed here…

C:\Users\Administrator\AppData\Local\Programs\Python\Python35\



We need to change directory now and make sure we have ‘pip’ the Python Package and software management tool installed. We’ll need this to install Selenium. So double click on the ‘Scripts’ folder and look for the file/executable ‘pip’.

From a command prompt run this command:

C:\Users\Administrator\AppData\Local\Programs\Python\Python35\Scripts\pip.exe help

This should show you some help information to confirm that pip is installed correctly. From here we need to replace the ‘help’ command with the ‘install’ command to install the Selenium packages. From the command prompt run

C:\Users\Administrator\AppData\Local\Programs\Python\Python35\Scripts\pip.exe install -U selenium



So we have Python installed and the Selenium package. We have our browsers installed but we don’t have the Selenium drivers installed for those browsers. Well that’s not strictly true. FireFox comes installed with the Selenium driver but IE and Chrome don’t. So we’re missing these bits…



Next then we need to install the Selenium drivers for IE and Chrome.

5. Install the Chrome Selenium Driver

On our Windows 2012 Slave machine use a browser to search for the ‘Chrome selenium driver’. This should take you to a Url like this…

https://sites.google.com/a/chromium.org/chromedriver/downloads

From here download the latest ChromeDriver, for example:

chromedriver_win32.zip

Extract the exe from the zip file and copy this file to the ‘C:\Windows’ folder.



The only reason we’re copying it to the ‘C:\Windows’ directory is because this directory is in the PATH environment variable already. Which means when we execute it the system will have no problem finding the exe for this driver. You can try this if you like by running this command:

chromedriver.exe



This shows the Chrome driver running and waiting for a connection.

Next then the IE driver.

6. Install the IE Chrome Selenium Driver

Bit more tricky to find this one. However, a hunt on the web for ‘IE Selenium Driver’ should take you to a place like this…

http://selenium-release.storage.googleapis.com/index.html

Select the latest folder/version and download the latest IEDriverServer file, for example:

IEDriverServer_Win32_2.50.0.zip

Again, extract the exe from the zip file and copy this file to the ‘C:\Windows’ folder.



One last thing on the IE setup. We need to disable protected mode for all zones:



Then close down IE and we should be ready to go.

Part 6: Create Our First Selenium Script

So at this point we have everything we need on this Windows 2012 slave machine. We just need to create a few Selenium tests and run them locally. Once we have them running locally we can start triggering their execution from the master Jenkins machine.

To begin with we’ll check Python and Selenium can drive all our browsers. We’ll great a short script to open each browser in turn.

1. Open notepad and enter the following script

from selenium import webdriver driver = webdriver.Firefox() driver.get("http://www.google.com") driver.quit()

driver = webdriver.Ie() driver.get("http://www.google.com") driver.quit()

driver = webdriver.Chrome() driver.get("http://www.google.com") driver.quit()

Save this script to the desktop with the file name ’sel.py’

2. Open a command prompt and run this script

C:\Users\Administrator\Desktop\sel.py

Which should be executed as follows:



Running this should open each browser in turn, go to the Google home page and then close each browser.

This just confirms for us that everything we need is setup correctly on the slave machine. Just need to check we can run this from our Jenkins master machine now.

3. Checking the sel.py script return codes

When Jenkins runs scripts on remote slave machines it determins the success or failure of the job/build based on the return code from the LAST script or command executed. If you run the sel.py script again on the Slave machine then type this at the command prompt:

echo %errorlevel%

In the example below where the script ran successfully we see the error code is ‘0’ which means success. If Jenkins sees this it’ll mark the Job/build as a pass (which is what we want).



Lets change the script slightly so that we make it fail. You can do this in notepad by changing this line…

driver = webdriver.Ie()

to

driver = webdriver.IE()

Note the change in case of ‘IE’. Save this and run the script again. This time we should see a failure



And when we look at the error code we see a ‘1’. This means the script failed. When Jenkins picks up on this it will mark the Job as failed. We going to keep this state whilst we configure Jenkins.

Part 7: Running the Selenium Script from the Jenkins Master Machine

Lets setup the Jenkins master machine to kick off this selenium script on the Slave machine. The Selenium scirpt is configured to fail at the moment so we should see this fail the job first time round. Then we’ll update the Selenium script to fix it and see the job pass. That’ll just confirm for us that we’ve configured all of this correctly.

1. Create a new Job/build task in Jenkins

** We’re back on the Master Jenkins Windows 2008 machine now **



2. Give the new job an item name and select Freestyle project

Item Name: RunSeleniumTests
Freestyle project: <selected>



3. Configure the job with the following settings:

Restrict where this project can be run: <checked>
Label Expression: SeleniumTestClient


This forces the job to run on our Windows 2012 client/slave machine where we’ve setup our Selenium tests.

At the bottom of the configuration page we need to setup a build step. Click the ‘Add build step’ button and select ‘Execute Windows batch command’. Then add the following command

C:\Users\Administrator\Desktop\sel.py



Then click the ‘save’ button.

4. Run the job and check that it fails

Now we click on ‘Build Now’ in the side menu to kick off this job on our Windows slave machine:


The build should show up in the Build que but because we’ve set it to run on our client machine labeled ‘SeleniumTestClient’ it may take a while for this client to start or for Jenkins to re-establish communications with the client. Once it’s started though you should see this…


And then if you return to the home page (click back to dashboard) you should see this job/build fail.



Click the ‘Console output’ menu item next to the failed build number to check why this has failed. You should see something like this:



Which is what we expected. We had ‘IE’ instead of ‘Ie’ in our script so the script failed with this error message

AttributeError module ‘selenium.webdriver’ has no attribute ‘IE’

And returned an error code of ‘1’ that Jenkins interpreted to mean the job failed.

5. Update the Selenium script on the client machine changing this…

driver = webdriver.IE()

back to

driver = webdriver.Ie()

and save the ’sel.py’ file

6. Run the job again and check that it passes

Go back to the home page and click the ‘Bulid now’ icon



This time round we should see a blue button to indicate that the build passed.


Click on the ‘Console Output’ icon again and review the results from the Selenium script run. You should see something like this…


You can see from this that the error level was 0 (e.g. success) and Jenkins used this to mark the job/build as a pass.

Now all we have to do is write some selenium scripts to test our Rocket Chat application and get Jenkins to run these scripts once the build of Rocket Chat has completed.

Part 8: Checking we can Access Rocket Chat from our Windows Client

What we need to do now is run up our application under test, Rocket Chat. Now we already have that scripted in Jenkins and designed to run on a dedicated AWS Linux instance. So lets start out by running this up.

1. Kick off the ‘BuildRocketChatOnNode’ job in Jenkins

So click on the ‘build now’ icon for the Rocket Chat job.



This might take a few minutes to complete but you should see this in Jenkins:

2. Make sure your Windows Selenium test client/slave is running

If you check on your Jenkins dashboard and you see the Windows Client as offline like this…



Then you can bring it back online automatically by running this Jenkins job too



So we’ve started up both Jenkins slave machines automatically from our Jenkins master machine. From our ‘Build Executor Status’ panel we should be seeing something like this…



And of course in our AWS account we should see all three of our instances all up and running together for the first time:



Next we need to make sure our Windows client machine can see the application under test running on our Linux client machine.

3. Check the Windows Client can access the Rocket Chat application on the Linux client

So we’re going to look to establish this link (shown in red below)



Essentially this link is just a browser on the Windows client machine displaying the web page that is being generated by the Rocket Chat application running on our Linux client machine.

Now don’t forget that when these Linux clients run up they pick up a new public Ip address and hostname. So you’ll need to check your AWS account to find the Hots name of the Linux client:



Then taking this host name or Ip address we’ll open up a browser on the windows client machine. We need to bear in mind here that Rocket Chat runs on port 3000 so we’ll need to enter this Url in your browser on the Windows client machine:

http://ec2-54-191-125-53.us-west-2.compute.amazonaws.com:3000

So you should get something like this…



At this point we’re ready to write a few Selenium scripts on our Windows client machine that login to Rocket Chat.

Part 9: Writing Some Selenium Tests for Rocket Chat

Now we’re not going to get into how to develop good Selenium scripts in this module. Plenty of good resources on the web that already cover that. What we’ll do is write a login/logout script and run that for each browser type. This will give you enough to expand on as you develop your own environment.

We’re going to take an example directly from the Selenium Python Bindings documentation (found below) and modify this for our purposes:

http://selenium-python.readthedocs.org/getting-started.html

1. Open notepad with the sel.py script and replace the contents with the following script (making sure you get the indentation correct):


from selenium import webdriver
from selenium.webdriver.common.keys import Keys
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC 
import sys
import time
 

if (sys.argv[1] == "Firefox") : 
        driver = webdriver.Firefox()
elif ( sys.argv[1] == "Ie" ) :
        driver = webdriver.Ie()
elif ( sys.argv[1] == "Chrome" ) :
        driver = webdriver.Chrome()
else:
        print ( "Unknown driver type" )
        sys.exit(1)

driver.implicitly_wait(5);

userName = "admin"
password = "tester123"
email = "asdf@asdf.com"

driver.get(sys.argv[2])
time.sleep(3)
assert "Rocket.Chat" in driver.title

elemUsername = driver.find_element_by_name("emailOrUsername")
elemUsername.send_keys(userName)
elemPass = driver.find_element_by_name("pass")
elemPass.send_keys(password)

elemSubmit = driver.find_element_by_class_name("button")
elemSubmit.click()


try:
        accountNotCreated = WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.ID, "toast-container")))

except:

        #use existing Admin account
        time.sleep(2)

        elemUser = driver.find_element_by_class_name("data") 
        assert elemUser.text == userName 
        elemUser.click()

        time.sleep(2)

        elemLogout = driver.find_element_by_class_name("icon-logout")
        elemLogout.click()

        time.sleep(3)

        elemLogin = driver.find_element_by_xpath("/html/body/section/div/form/div[2]/button/span")
        assert elemLogin.text == 'LOGIN'

else:

       #create a new Admin account
        elemRegister = driver.find_element_by_class_name("register")
        elemRegister.click()

        elemUsername = driver.find_element_by_name("name")
        elemUsername.send_keys(userName)
        elemEmail = driver.find_element_by_name("email")
        elemEmail.send_keys(email)
        elemPass = driver.find_element_by_name("pass")
        elemPass.send_keys("")
        elemConfPass = driver.find_element_by_name("confirm-pass")
        elemConfPass.send_keys(password)

        elemSubmit = driver.find_element_by_class_name("submit")
        elemSubmit.click()

        elemConfirm = driver.find_element_by_class_name("button")
        elemConfirm.click()

        time.sleep(2)

        # Deal with first login warning message
        try:
                button = driver.find_element_by_class_name("confirm")
                button.click()

        except:
                print("Warning box not found")


        time.sleep(2)
        elemLogin = driver.find_element_by_name("username")
        elemLogin.click()
        elemLogin.send_keys(Keys.RETURN)

        elemUser = driver.find_element_by_class_name("data")
        assert elemUser.text == userName
        elemUser.click()

        time.sleep(3)

        elemLogout = driver.find_element_by_class_name("icon-logout")
        elemLogout.click()

        elemLogin = driver.find_element_by_xpath("/html/body/section/div/form/div[2]/button/span")
        assert elemLogin.text == 'LOGIN'

driver.close()

Save this file as:

C:\Users\Administrator\Desktop\sel.py

With this in place we can run tests with a command like this…

sel.py [driver_type] [http://aut_ip-address:port]

For example

sel.py Chrome http://54.200.192.16:3000

We’ve updated this script a little from the example given on the Selenium Python Bindings web site. Most of what this script does is explained on that web site but the few changes we’ve made are detailed below. We can run the command with a call like this:

a. we’re passing in the driver type in the command line. So now we can control which browser we’re testing in. Later we’ll use Jenkins to control which browser we’re testing by getting Jenkins to set this driver type.

b. we’re now passing in the URL and port number in the command line. We’re passing this in as parameter number 2 on the command line (argv[2]). This is because down the line we’ll need Jenkins to pass this value in each time it runs the job. The host name for the server running the AUT will change so Jenkins will need to deal with this.

c. we’re using XPATH and Class Names to identify objects on the web page and then interact with those objects. We’d recommend using Firefox with the FirePath extension to identify objects in your applications. Makes it all much simpler.

d. we have conditional logic that looks to see if this is a NEW install of Rocket Chat. If it is then we need to create the account first before we do the login. If it’s NOT a new install then we use an existing Admin account and login without creating a new account.

e. the %errorcode% returned from running this script is set directly by the success or failure of the unit tests. If the unit test asserts fail it’s an %errorcode% of ‘1’ which tells Jenkins that the job has failed. If it’s an %errorcode% of ‘0’ this indicates a pass and Jenkins will report the job/build as a pass.

And that’s it for now on the Selenium script side of things. Just enough to test that the application is running, that we can create a new account and that we can login/logout.

Part 10: Running an RDP/RDC Session on our Master Jenkins Machine

The next challenge (and it’s kind of a big one) is to get our master Jenkins machine to open up an RDP/RDC session to our client windows machine that runs our Selenium scripts. We are going to run GUI tests on a jenkins windows slave with a remote desktop connection running on the Jenkins master machine.

We want this because the Selenium scripts are designed to run on a terminal with the browsers running. We could run some browser tests in a headless mode but this comes with it’s own set of issues and isn’t really a close enough representation of what the end user will be doing (in my opinion). So we need to get Jenkins to create an RDP/RDC terminal on the Jenkins master machine automatically.

This is fraught with issues. But there is a neat solution…even if it is a bit convoluted.

The key problem we need to overcome is that Jenkins is running on the master machine as a service. And with Windows 7 and later ‘running as a service’ means you can’t start applications (e.g. an RDP session) on that machine directly from that service. You run into all sorts of issues with User Account Control Setting issues.

The way round this then is to run a Jenkins slave process on the Master machine. This slave jenkins process is run from a user account. Having it run from a user account (using a batch file or something similar) means that this Jenkins slave process does have the right account privileges to run applications (e.g. RDP sessions). You then get the Jenkins master to call the Jenkins slave (which is on the same machine) and run up the RDP session. And once the RDP session is running we can then get Jenkins to run the Selenium scripts.

Here’s how we do this then…

1. Create the jenkins working directory

First create a jenkins directory on the master machine, so that you have this directory…

C:\jenkins

Which looks like this…



2. Download the Jenkins slave.jar on the Jenkins master machine

In a borwser on the master machine enter this Url

http://localhost:8080/jnlpJars/slave.jar

Once the file has downloaded open the download folder and copy the slave.jar file to the C:\jenkins directory. You can use a command like this if you want

copy C:\Users\Administrator\Downloads\slave.jar C:\jenkins

3. Configure this slave as a node in Jenkins

In Jenkins we need to setup this machine so that it is seen as a slave machine. To do this go to ‘Manage Jenkins’ and then ‘Manage Nodes’



From here we can click on ‘New Node’



We’ll call the node “SlaveOnMaster” (to indicate that we’re running a Jenkins slave on the Jenkins master machine) and select ‘Dumb Slave’



On the configuration page we’ll need to set a few fields

Name: SlaveOnMaster
Description: <blank>

# of executors: 1

Remote root directory: C:\jenkins
Labels: SlaveOnMaster
Usage: utilize this node as much as possible
Launch method: Launch slave via execution of command on the Master
Launch command: <blank>
Availability: Keep this slave on-line as much as possible

A few things to point out here. We have the label set to ‘SlaveOnMaster’ because we want to force specific jobs to run on this machine. We have left the launch command blank. We DON’T want this Jenkins master process to launch the slave Jenkins process. We want to do this manually (more on this in a minute). It’s lanuching this slave process outside of the Jenkins master process that’ll give us the privileges we need to automatically start an RDP session.

So this should give us this:



Once we save this we should have:



With the red cross indicating that this Slave isn’t connected. So next we need to connect it!

4. Run the Jenkins Salve.jar process

Now we need to run this Jenkins slave process and get it to connect to the Jenkins master process (both of which are running on the same machine).

We need to create a batch file called ‘jenkinsSlave.bat’, add the following command and save the batch file to the desktop:

cmd /k “C:\Program Files (x86)\Jenkins\jre\bin\java” -jar C:\jenkins\slave.jar -jnlpUrl http://localhost:8080/computer/SlaveOnMaster/slave-agent.jnlp

Make sure this is all on 1 line. It should look like this:



What this batch file does is lanuch the Jenkins slave process using the Java executable. This will then connect to the Jenkins master process.

To create the connection double click and run this batch file.

You should then see this in the Nodes dashboard in Jenkins:



Note: if you want you can create a shortcut for this .bat file then locate the Startup folder and save this batch file shortcut in the startup folder. This way it’ll automatically start when the server starts up.

5. Create the Jenkins Job to start the RDP terminal

Now Jenkins can talk to the Slave process we can get jenkins to lanuch the RDP session automatically. We just need to create the job

Go back to the Jenkins home page and select ‘New Item’



Call the new job ‘RunClientRDPSession’ and select ‘Freestyle project’



Only things we need to update on this now job are:

Restrict where this project can be run: SlaveOnMaster

So we should have…



And then select ‘Add build step’ and configure as follows:


cmd /c cmdkey /generic:TERMSRV/<windows-selenium-client> /user:Administrator /pass:<password-for-host>
mstsc /v:<windows-selenium-client> /w:1920 /h:1080 set BUILD_ID=dontKillMe

For now we’re going to hardcode the hostname of our client windows machine that will run our selenium tests. We’ll come back and add this as a parameter later.

The first line of this command sets up our master machine connection to the windows host so that it connects automatically with the Administorator account. You will need to specify the Admin password in this command.

The second line starts the RDP session with the window heigh and width parameters defined. And the last line just makes sure that Jenkins doesn’t kill the RDP session we’ve just started when the commands have completed.

Save the job and then we’re ready to check that we can automatically start an RDP session from Jenkins.

6. Run the RunClientRDPSession job

Go back to the Jenkins home page and run the RunClientRDPSession job.



You should see Jenkins open an RDP session on the windows Jenkins machine automatically.

7. Check the Selenium tests run in the RDP session

You should be able to run the selenium tests on the client machine now



And you should see those tests running in the RDP session that you’e just opened with Jenkins too.

Part 11: Closing the RDP/RDC Session on our Master Jenkins Machine

Bit simpler this bit. Once we’ve opened the RDP session and then run our Selenium tests we’ll want to close the RDP session. We’ll need to close it because if we run the process again we don’t want to end up with 2 RDP sessions open.

1. So at this stage you should be able to create a new project by clicking ‘New Item’ on the Jenkins home page.

2. Then use the Item name:

Item Name: CloseClientRDPSession

3.We don’t need to restrict where this project can be run as we want it to run on the master machine that has the RDP terminal session open. So all we need to set is the batch command to run.

4. Then add an ‘Execute Windows batch command’ build step and enter the following script:

cmd /c taskkill /IM mstsc.exe

So we’ll have…



5. Run this project (click the ‘build now’ icon) and just make sure it closes the current RDP terminal session that’s open.

With that in place it’s just a question of linking all the projects together.

Part 12: Running the AUT build followed by the Selenium Tests

We now have the 4 things we need in place to get this up and running fully. We have the Jenkins project that installs and starts the application under test. We have the project that opens the client RDP terminal session on the master machine. And we have the project that starts and runs the Selenium tests on the client. Lastly we have the project that closes the client RDP terminal session. All we need to do now is string them together.



First we’ll link the RDP session opening (RunClientRDPSession) to the Selenium test execution (RunSeleniumTests) and the RDP close session (CloseClientRDPSession). Then we’ll link in the application under test install at the start of that (BuildRocketChatOnNode).

1. Modidfy the RunSeleniumTest project by clicking on ‘Configure’ for the project



2. Update the RunSeleniumTest Build Trigger settings so that we have…

Build after other projects are build: <checked>
Projects to watch: RunClientRDPSession
Trigger only if build is stable: <set>

Like this:



This needs to be set so that the RunSeleniumTests project gets kicked off after other project is built. It only gets kicked off IF the RunClientRDPSession is stable. If there RDP session isn’t stable and doesn’t open no point in running the Selenium tests. So in this case we’re checking that RunClientRDPSession project has completed successfully.

3. Update the CloseClientRDPSession Build Trigger to:

Build after other projects are build: <checked>
Projects to watch: RunSeleniumTest
Trigger even if the build fails: <set>

Like this:



Note that we’ve set this to ‘Trigger even if the build fails’. We want the RDP terminal session to close even if the Selenium tests fail. That’s so the terminal always closes and is ready for the next Selenium test run.

Save these project updates then we can test that this works.

4. Test that the project dependencies work

First make sure you close the RDP session on the master machine. Then go back to the main Jenkins dashboard. Kick off the RunClientRDPSession project manually



Then what you should see of course is the RunClientRDPSession project execute followed directly by the RunClientRDPSession and then finally the CloseClientRDPSession project run. Our Jenkins dashboard should show the results as follows:



Now all we need to do is pull in the initial project that builds and installs the AUT (BuildRocketChatOnNode).

5. Add condition that starts Client RDP Session when ATU Build is complete

At this stage just one last thing to add to this chain of events. When we run the build/install of the AUT (the Jenkins RunClientRDPSession project) we need the completion of this job to trigger RDP session creation (RunClientRDPSession) and the selenium tests (RunSeleniumTests)

We need to update the RunClientRDPSession Build Trigger to

Build after other projects are build: <checked>
Projects to watch: RunClientRDPSession
Trigger only if build is stable: <set>

Like this:



Only problem we have now is that when ever we do a complete install of the AUT and Amazon AWS creates a new instance we’ll have a new Url for the AUT. So we need to pick the hostname and Url out of the BuildRocketChatOnNode project and pass that to the subsequent jobs.

6. Determin hostname/Url of AUT and pass to downstream projects

So the next bit gets interesting. The problem is that our ‘RunSeleniumTests’ job has the host name the AUT is running on hardcoded. For example:

C:\Users\Administrator\Desktop\SelLoginTest.py Ie http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000
C:\Users\Administrator\Desktop\SelLoginTest.py Chrome http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000
C:\Users\Administrator\Desktop\SelLoginTest.py Firefox http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000

This is going to cause problems when we start the whole process from scratch and we run up a new AWS instance. That new instance will have a new hostname and our hard coded ‘RunSeleniumTests’ job won’t work. So we need to parameterise these commands. This requires a number of things in Jenkins

a. Jenkins 'BuildRocketChatOnNode' job to record it's AUTs public host name for the host it is run on
b. Jenkins master machine to know the AUTs public hostname
c. Jenkins 'RunSeleniumTests' job to pick up the hostname as a parameter

Probably many ways to approach this (for example using some of the Jenkins parameterization plugins). We’re going to approach it in the simplest way I know using the the ‘Environment Injector Plugin’, ‘Copy Artifact Plugin’ and the in-built ‘Archive Artifacts’ capability in Jenkins.

https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin

https://wiki.jenkins-ci.org/display/JENKINS/Copy+Artifact+Plugin

What these plugins allows us to do is create a file on the slave running the AUT that contains a variable with the public host name in. This file then gets pulled back to the master jenkins machine. This file is then copied from the ‘BuildRocketChatOnNode’ workspace to the ‘RunSeleniumTests’ workspace. When we come to run the ‘RunSeleniumTests’ job, this job reads in the file and uses the public host name as a parameter.

First we need to install the ‘Environment Injector Plugin’ and ‘Copy Artifact Plugin’.

i. go to the Jenkins home page
ii. go to ‘Manage Jenkins’ then ‘Manage Plugins’
iii. click the ‘Available’ tab and search for ‘Environment Injector Plugin’
iv. check the check box for this plugin
v. search for the ‘Copy Artifact Plugin’
vi. check the check box for this plugin
v. scroll to the bottom of the page and click the ‘Install without restart’ button
vi. wait for the success indication and then go back to the dashboard

From here we need to do three things. First, create the file that contains the public host name. Second, configure the ‘BuildRocketChatOnNode’ job to pull the file back from the slave to the master jenkins machine and keep it as an archived file. Third, configure the ‘RunSeleniumTests’ job to read the file and use the public host name value.

First then we need to update the ‘BuildRocketChatOnNode’ so that it creates a file with our public host name in. Go back to the Jenkins home page and configure the ‘BuildRocketChatOnNode’ job.

At the bottom of this page, in the Execute Shell Command section you need to add these two line at the bottom of the script:

> cd ~/workspace/BuildRocketChatOnNode/
> echo "PUBLIC_HOSTNAME=http://$(curl http://169.254.169.254/latest/meta-data/public-hostname 2>/dev/null):3000" > publicHostname.txt

So it should look something like this…

All this command does is find out the public host name from one of the Amazon servers, concatenate this with the string ‘http://’ and the ‘:3000’ port number. It then puts this information into a file called ‘publicHostname.txt’. The contents of which will look something like this…

PUBLIC_HOSTNAME=http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000

Next we need to get this ‘publicHostname.txt’ file back from the workspace area on the linux slave to the workspace on the Jenkins master machine and archive the file. To do this we just use the in built build step to ‘Archive the artifacts’ post build action.

To configure this configure the ‘BuildRocketChatOnNode’ job again…

At the bottom of the configuration screen add a ‘Post Build Action’ to ‘Archive the artifacts’

In the ‘Archive the artifacts’ section that is added enter the name of our file containing the Host Name of the AUT machine. This file name is ‘publicHostname.txt’

Save the job. What this will do is pull the publicHostname.txt file back from the AUT machine and save it on the Jenkins master machine in the project workspace. Then all we need to do is copy this file from ‘BuildRocketChatOnNode’ workspace to the ‘RunSeleniumTests’ workspace. We can do this by editing the ‘RunSeleniumTests’ job from the Jenkins home page:

And then adding a ‘Copy artifacts from another project’ build step…

Then complete the following fields:

Project name: BuildRocketChatOnNode
Which build: Latest successful build
Artifacts to copy: publicHostname.txt

Like so…

Now we have the file containing the host name available to this job. Next we need this job to process the file at run time. For this we need to ‘Inject environment variables’. So we’ll add another build step for ‘Inject environment variables’:

Add the following field data:

Properties File Path: publicHostname.txt

Like so…

When this job executes on the Windows slave machine it will set the environment variable …

PUBLIC_HOSTNAME=http://<your_public_hostname>:3000

All we need now is for the part of the job that runs the selenium tests to use this hostname. For that we just edit the existing ‘Windows Batch Command’ changing it from:

C:\Users\Administrator\Desktop\SelLoginTest.py Ie http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000
C:\Users\Administrator\Desktop\SelLoginTest.py Chrome http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000
C:\Users\Administrator\Desktop\SelLoginTest.py Firefox http://ec2-54-213-164-123.us-west-2.compute.amazonaws.com:3000

to…

C:\Users\Administrator\Desktop\SelLoginTest.py Ie %PUBLIC_HOSTNAME%
C:\Users\Administrator\Desktop\SelLoginTest.py Chrome %PUBLIC_HOSTNAME%
C:\Users\Administrator\Desktop\SelLoginTest.py Firefox %PUBLIC_HOSTNAME%

So it should look like this now…

C:\Users\Administrator\Desktop\SelLoginTest.py Ie %PUBLIC_HOSTNAME%
C:\Users\Administrator\Desktop\SelLoginTest.py Chrome %PUBLIC_HOSTNAME%
C:\Users\Administrator\Desktop\SelLoginTest.py Firefox %PUBLIC_HOSTNAME%

We now have 3 build steps in this Job. It’s really important that they run in the right order though. You’ll notice on the build steps that you can ‘grab’ the handle and change the order the steps. For example…

To get this working correctly you MUST put the build steps in this order…

  1. Copy artifacts from another project
  2. Inject environment variables
  3. Execute Windows batch command

In short you need the publicHostname.txt artifact available to the job before you can inject it. Once publicHostname.txt is available to the job the ‘Inject environement varialbes’ build step can read the file and make the PUBLIC_HOSTNAME environment variable available to the job. Then the windows batch command can use the %PUBLIC_HOSTNAME% variable when the commands are executed.

Save the changes you’ve made to the job and return to the Jenkins home page. Run the ‘BuildRocketChatOnNode’ job which will then trigger the ‘RunClientRDPSession’ job follwed by the ‘RunSeleniumTests’ job automtically.

With a bit of luck you should see the BuildRocketChatOnNode job create the publicHostname.txt file. That publicHostname.txt copied for use in the RunSeleniumTests and these test complete successfully.

You may find the first Selenium test against IE failed. This will probably be down to the trusted sites setup in IE. In which case you’ll want to define the amazonaws.com domain as a trusted site so the ‘warning message’ doesn’t stop the execution. You can do this on these dialogue boxes:

All we need to do now is run this right from the start which Jenkins creating a new instances of the Linux machine (with a new public hostname).

7. Test the whole workflow

That’s everything configured. All we need to do now is test the whole process. To do this we’ll

i. Go to the Amazon EC2 dashboard
ii. Select ‘Instances’ in menu
iii. ‘Terminate’ the Linux Ubuntu client
iv. ‘Stop’ the Windows client

Make sure you get these the right way round. We don’t want to Terminate the Windows client

Now we can go to the Jenkins dashboard and kick of the full process. To do this click ‘Build Now’ for the ‘BuildrocketChatOnNode’ project.



This should create the Linux EC2 instance, build the AUT and install Rocket Chat. If that completes successfully then the next projects in the chain will start that run the RDP session and kick off the Selenium tests. Last but not least the RDP terminal session is closed once the Selenium tests are finished. Job done.

Conclusion

So we’ve configured Jenkins to start a slave Windows machine that will run our browser tests. We’ve install the software we needed to run our browser tests (e.g. a set of different browsers, Python and Selenium). We’ve created our first Selenium script and checked that this runs against our application under test.

With the automated tests in place we’ve then configured Jenkins to run these scripts auotmatically on our Windows client machine. We’ve worked out how to run RDP/RDC terminal sessions on our Master Jenkins machine so that these Selenium tests can run in a real environment (not just some headless mode). In order to do this we’ve gone through some quite complex configuration steps in this module. Most of the complexity needed to get round Windows User Account Control (UAC).

With all the steps/projects created in Jenkins we’ve then completed the simple process of chainning all our Jenkins projects together. And hopefully on running this for the first time we’ve seen everything run end to end. Right from starting our client AWS machines, building/installing our AUT and running our automated tests.

What we’ve completed in this module is the crux of building out our test automation framework. Yes it’s a little tricky in places but once running you have a setup that you can expand and develop further. You know all the key tricks for building this out to test your own appplications now. You just need to plugin your application, write your own Selenium tests and plug those tests into this framwork too.

Free Test Automation Framework Course
Learn the Practical steps to building an Automation Framework. Six modules, six emails (each email a short course in it's own right) covering Amazon AWS, Jenkins, Selenium, SoapUI, Git and JMeter.
Facebooktwittergoogle_plusredditpinterestlinkedinmail

We have the test environment in place (if you don’t check here) and we know enough to be dangerous with Amazon Web Services. Next step is probably the most important. We need to get Jenkins installed, configured and running. Jenkins has to be one the testers most useful tools. It’s not just handy for kicking off automated tests it’s indispensable for automating all sorts of processes you have to complete day in day out.

We’re going to cover 4 main areas here…

1. Jenkins Installation
2. Installing Jenkins Plugins
2. Jenkins Configuration
3. Deploying and Building the Application Under Test

By the time we’ve completed the module we will have Jenkins running on our Windows Master machine. The Jenkins configuration will be completed so that it will carry out six main actions…

i. Run up a new/clean EC2 Ubuntu instance (client)
ii. Install the Jenkins client on the Ubuntu client
iii. Download the AUT from GitHub to the Ubuntu client
iv. Build the AUT on the Ubuntu client machine
v. Install and start the AUT running on the client machine
vi. Run some simple post build checks

What You’ll Learn

In this module we’ll go through the 12 parts listed below looking at the practical aspects of setting up Jenkins. By the ended of the module you will understand the following concepts:

 

 

When we’re finished we’ll have this setup:

BTS Overview Module 2 New Page

Note that we’re building on top of the AWS infrastructure we built in the first module by adding Jenkins and a bit of configuration. Whilst we created a client Ubuntu machine in in the first module we’re not actually going to be using that machine. What will happen is that Jenkins will fire up a completely new instance of the Ubuntu machine automatically whenever it’s needed. This is an ideal use case for bringing up Amazon Instances as and when we need them. More on how we do this in a minute.

Why Use Jenkins

On the Jenkins web site they don’t talk about Continuous Integration or Dev Ops or use any other popular buzz words. They simply refer to Jenkins as the “Open Source Automation Server”. And that’s the key. Jenkins isn’t just an app for developers. It’s an automation tool for testers too.

I personally love Jenkins. I don’t think of it as an app for developers or build engineers. I don’t think of it as an app for continuous integration or for building software. Yes it does all of that. But! It’s just the best app for automating a load of the daily or weekly tasks that the test team have to perform. Whether that’s installing the application you want to test or setting up your test environment. It’s just the best way to save yourself loads of time and effort on repetitive tasks.

Prerequisites

A few things we need to make sure we have setup correctly before we start.

Make Sure your Windows Master EC2 Instance is Running

First, if you don’t have your Windows master machine up and running yet then you’ll need to revisit Module 1 and take a look at the section on Running up the Windows Instance.

With the Windows 2008 master machine configured then we’ll need make sure the instance is running and that we have an RDP session open. You can complete these steps with

1. Open your AWS management console, and view your list of Instances (making sure you have the correct Region selected).

 

BTS module2 img2 AWS start instance

 

 

2. Once started open an RDP session on this Windows machine.

 

BTS module2 img3 AWS RDP Connect

 

 

Then enter the password to open up the desktop session (you may need your .pem private key file to decrypt the password if you’ve forgotten it) .

Create and Save Your Amazon ‘Access Key Id’

Second we need to get our Amazon ‘Access Key ID’. We’ll need this later as we’re configuring Jenkins to start our client/slave machines. For other systems or programs to connect to your AWS account they need an access key (like a password but for an application not a person). Jenkins needs this access key if it’s going to be allowed to start EC2 instances.

To get this Id follow these steps:

1. Login to your AWS account https://aws.amazon.com

2. Click on your user account drop down and select ‘Security Credentials’

 

BTS module2 img3 AWS RDP Connect

3. Expand the ‘Access Keys’ section and click on ‘Create New Access Key’

 

BTS-module2-img1a-AWS-security-id

 

4. You can either download or show the access key. Either way you need to record these two parts of the key

 

Access Key Id
Secret Access Key

NOTE: once you’ve downloaded or viewed the secret access key you CAN NOT obtain it again. If you lose it you’ll have to create another access key (no big deal but it’s easier if you just look after it now).

Make Sure you have your Private key (.pem file)

Third, remember back in Module 1 we created our public and private key pairs? Well at that stage you should have saved your private key pair .pem file (e.g. FirstKeyPair.pem) file. You’ll need this private key when configuring Jenkins later.

If you don’t have have this private key you can go back and create a new key pair. Much easier if you can find the one you created in Module 1 though.

Terminate any Running Unix Client Instances

Lastly, we need to make sure we don’t have any Linux Ubuntu clients running. When Jenkins creates and starts new instances of the Linux clients it checks to see that no existing instances are running OR in a stopped state. So we need to TERMINATE any running instances. To do this follow these steps:

i. login to your AWS management console

ii. go to your AWS EC2 dashboard

iii. select the correct region

iv. click ‘instances’ in the side menu

v. in the list of instances select your Unix-client instance

vi. right click the Unix-client entry, select ‘Instance State’ followed by ‘Terminate’

vii. in the list of instances you should now see this:

BTS-module2-img1b-unix-terminate

What Next?

With our Amazon Access ID, Key pair private key, our Linux machine terminated, our Windows master machine running and a desktop session available we’re ready to start installing and configuring Jenkins.

Part 1: Installing Jenkins

At this point we’re ready to visit the Jenkins-ci.org web site and download the Windows install package. Follow these steps to complete the install on your Windows 2008 server master machine.

1. Open up Internet Explorer and type in this URL http://jenkins-ci.org

2. On the home page for Jenkins, right hand side, you’ll see the Download Native packages for Windows section. Click this link.

BTS-module2-img4-Jenkins-home-page

3. Open the download folder and drill down into the Jenkins zip file. Extract the file in the zip file by dragging it to the desktop

BTS-module2-extract-Jenkins-installer

4. Run the installer accepting all the default install options. Nothing very exciting seems to happen on completion of the install. Except that after a while a new tab should open in Internet Explorer with the following:

Jenkins-home-page

If this page doesn’t open automatically you can type in this Url:

http://localhost:8080/

This is the default location and port that Jenkins runs on. This’ll be just fine for what we need.

And that’s it. That simple. Jenkins installed and ready to go. Next step configuration and creating your first job.

A Quick Overview of Jenkins

Before we start configuring Jenkins lets take a look at some key features and concepts. As we’ve already mentioned Jenkins is an automation server that gives us the capability to automate many process within our development and test projects.

Part 2: The Main Jenkins Configuration Areas

We need to achieve three things with our configuration of Jenkins

  1. Start a slave machine: we’ll get Jenkins to automatically start our Linux Ubuntu machine when we’re ready to build and install the application under test on this Linux machine
  2. Download, Build and Install the application under test: once the client Linux machine is running we’ll download the source code for the AUT, build the AUT and install it on our Linux client machine.
  3. Run some Smoke Tests Against the AUT: once the AUT is installed and running we’ll run a couple of very simple tests to make sure that it is up and running.

Part 3: Jenkins’ Plugins

A fundamental concept within Jenkins is it’s plug-in module capability. There’s a plug in module to help you automate just about any task you need to automate. A full list of the modules can be found here..

https://wiki.jenkins-ci.org/display/JENKINS/Plugins

These plugins are broken into a number of different types that deliver different types of capabilities:

Source Code Management: Whilst Jenkins supports source code tools like Subversion and CVS out of the box there are other source code tools you might want to work with. Source Code Management plugins support all sorts of other source code tools. We’ll be working with Git and GitHub so we’ll need to add a plugin for GitHub in a minute.

Build Triggers: When do you want, or need, to build and test the AUT? Well plugins for Build Triggers allow you to monitor external activities and trigger a build of your AUT when certain conditions are met. For example a developer may check in some code and you’ll want to trigger a build off that check in.

Cluster Management and Distributed build: Typically with lots of automation activities being carried out, and many builds to process, you’ll distribute these activities to other client machines. You won’t run everything on your main Jenkins server. Distributed build plugins allow you to run up, communicate and control other machines. We’ll be using an Amazon EC2 Plugin that runs up and controls our Amazon EC2 Linux Ubuntu slave machine.

Slave Launchers and controllers: Depending on the type of slave machines you run up you’ll want to find different ways of communicating with those slaves. You’ve already seen how we’ll be communicating between our Windows master machine and Ubuntu client machine with SSH. So we’ll be installing the SSH Slaves plugin so that our Windows master Jenkins machine can communicate and control the Linux Ubuntu slave machine over SSH.

Other Post Build Actions: Once the build is complete you may want to complete other actions like running Windows Power shell scripts or Unix shell scripts. Things like this can be setup with ‘Post Build Action’ plugins. We’ll be using Hudson Post build task’ plugin to run some install completion scripts.

There are many other categories of plugins, including Build notifiers, Artifact up-loaders and build reporting. There are hundreds of plugins so chances are any automation task you need to complete will be covered either by features native to Jenkins or a plugin. If it’s not you can always write your own plugin too (but that’s a topic for another day).

Part 4: Installing Plugins

Let’s install the plugins we need for this project. We’re going to need these:

Amazon EC2 Plugin

https://wiki.jenkins-ci.org/display/JENKINS/Amazon+EC2+Plugin

With this plugin we can use our Jenkins machine to run up an Amazon EC2 instance automatically. We’ll be running up a Linux Ubuntu instance that will then run a Jenkins client application. This Jenkins client application will then be responsible for downloading the AUT source code, building the AUT and running the AUT.

SSH Slaves Plugin

https://wiki.jenkins-ci.org/display/JENKINS/SSH+Slaves+plugin

If you remember from our first Module we connected to our Linux Ubuntu client machine using SSH. This plugin gives Jenkins the capability to use our SSH private key to connect to the Amazon EC2 client machine. Once Jenkins has a connection to the client machine it can install the Jenkins client application on this machine and then control this machine.

GitHub Plugin

http://wiki.jenkins-ci.org/display/JENKINS/Github+Plugin

For this project our AUT is an application called Rocket.Chat. This project’s source is hosted on GitHub. With the Jenkins Github plugin we can connect to GitHub and download the source automatically.

Post Build Tasks

https://wiki.jenkins-ci.org/display/JENKINS/Post+build+task

Once we’ve completed the AUT build and install we’ll want to run a few tasks to check that everything is okay. With this plugin we’ll be able to check the logs for successful install messages and run a few checks to make sure the AUT is running correctly.

How do we install and/or update these plugins? Well Jenkins makes is really easy. Just follow these steps:

1. Click ‘Manage Jenkins’ in the control panel

2. Click ‘Manage Plugins’ in the control panel

 

On the Plugin Manager screen you should see a list of plugins grouped by tabs that cover; Updates, Available, Installed and Advanced tabs. First we’ll need to update one plugin.

3. On the ‘Update’ tab find the ‘SSH Slaves plugin’, check the ‘install’ check box and click the ‘Download now and install after restart’ button.

 

 

5. Let the install and upgrade complete so that ‘Download Successfully’ is displayed. Click the ‘Go back to the top page’ link.

 

Update success

So that’s one plugin updated just another 3 to install now. To install these plugins..

 

  • Select the ‘Available’ tab and search for each of these plugins in turn, then checking the check box:Amazon EC2 pluginselect-plugins
    GitHub PluginHudson Post build task

 

Then click the ‘Download now and install after restart’ button again.

At this point Jenkins should start installing the plugins and all the dependency plugins. So you’ll see a lot more than just 3 plugins installed.

Once you see all of the ‘Downloaded Successfully’ messages you can go ahead and restart Jenkins.

6. Restart Jenkins just by clicking on the ‘Restart Jenkins when installation is complete…’ check box

 

At which point you should see this restart message:

With all our plugins installed we’re ready to start configuring Jenkins.

Part 5: Configuring Jenkins

Now for the interesting part. We need to configure Jenkins so that the tasks we need automating are setup to be run by Jenkins. There are four key parts to this configuration.

Firstly we need to set Jenkins up so that it is integrated with our Amazon AWS service. The ‘Amazon EC2 Plugin’ we’ve installed needs to have the ‘Amazon Access Key Id’ installed so that it has permissions to drive AWS.

Secondly, we need to configure Jenkins so that it will start our Linux Ubuntu machine on demand. When Jenkins starts that machine it needs to specify the Amazon AMI to use and install other software packages that we’ll need for our build/instll.

Thirdly, we’ll also need to setup an initialisation script for the Linux Ubuntu instances that we start via Jenkins. This script will be responsible for updating existing software packages on the Linux client and adding some additional software that isn’t included in the AMI we’ve used.

Lastly, we need to configure the ‘job’ that kicks of the build and install of our AUT. Jobs in Jenkins are just automated tasks that you configure Jenkins to run. For each Job you configure you can run that Job (e.g. build now), track the changes you’ve made to it and see all the run results for that job.

Hot tip: this setup is designed so that the client/slave machine that we install our application under test on gets shut down and everything deleted on a regular basis. This means any manual configuration you do, or data you add, on this slave machine gets deleted too. This is by design. By good design.

When you know your test server will get deleted and everything removed on a regular basis it FORCES you to make sure EVERYTHING is in the automation scripts. Every actions that you need to build the test environment is scripted. This means everything is documented and repeatable.

Part 6: Configuring Jenkins – Amazon AWS Integration

Back on the Jenkins home page you’ll need to:

 

1. click on the ‘Manage Jenkins’ link again

 

 

2. click the ‘Configure System’ option

 

There are a lot of options for configuring Jenkins. All we need to concern ourselves with is the ‘Cloud’ section (at the bottom of the page). The Cloud section is where we define our Amazon EC2 instance start up details.

3. Scroll to the bottom of the Jenkins ‘Configure’ page where you should find the ‘Cloud’ section. Then click ‘Add a new cloud’ and select the ‘Amazon EC2’ option

From here we can enter all of the details needed to run up our EC2 Ubuntu instance. Before we can complete this though we’ll need to get our Amazon ‘Access Key ID’ which you should have from going through the Prerequisites Section of this module.

4. Enter the following details for your Amazon EC2 instance

 Name: RocketChatServer
Access Key ID: <key created in prerequisite stage of module>
Secret Access Key: <key created in prerequisite stage of module>
Region: <select your region>*1
EC2 Key Pair’s Private Key: <copy in the contents of your .pem file>*2

*1 – make sure you select the same region that your Windows 2008 server machine is running in. Login to the AWS management console and check the region if you’re not sure. It’s critical that you select the right region.

*2 – in the Prerequisite section in this module we talk through getting your .pem private key file that you created in module 1. You’ll need to open this .pem file in a text editor and paste the contents in to the Jenkins ‘EC2 Key Pair’s Private Key’ text box.

NOTE: if you see this error message once you’ve pasted in your private key you can usually just ignore it:

 

Once all of these fields are configured you can click the ‘Test Connection’ button.

Once you’ve completed the test you should see the word ‘Success’ to the left of the ‘Test Connection’ button.

 

Now we’re connected to our AWS account we’re ready to start configuring the details for the Linux Ubuntu slave machine we need to start up.

Part 7: Configuring Jenkins – Starting the Linux Amazon Instance Slave

 

5. On the ‘AMI’s line click the ‘Add’ button

6. Enter the following details for your AMI instance

Description: RocketChat-Server
AMI ID:<see below>

So the AMI id is the Amazon Machine Image number that correlates with our Linux Ubuntu machine that we want to run up. So it’s the same Id as the Linux Ubuntu machine instance that we already have configured in our AWS account. We find this ID with …

i. login to your AWS management console

ii. go to your AWS EC2 dashboard

iii. select the correct region

iv. click ‘instances’ in the side menu

v. in the list of instances select your Unix-client instance

vi. in the instance details panel (bottom of page) look for this:

From here you can pick out the ‘ami’ which should be something like:

ami-9abea4fb

Then we just need to click on the ‘Check AMI’ button. This should give you confirmation that AWS can find the image you need. It should look like this:


  1. Complete the rest of the AMI details

Instance Type: t2.micro (IMPORTANT*)

EBS Optimized: Un-checked

Availability Zone: <leave blank>

Use Spot Instance: Un-checked

Security Group Names: default, Unix-AUT (see below)

Remote FS root:<leave blank>

Remote user: ubuntu

AMI Type: unix

Root command prefix:<leave blank>

Remote ssh port: 22

Labels: RCBuildDeployServer

Usage: Utilize this node as much as possible

Idle termination time: 30

Init script:<leave blank>

*-make sure you select ‘t2.micro’ here as this is the only Instance Type on the free tier. Select anything else and you’ll be charged for it!

The security groups you configure here will be determined by what you’ve setup in your AWS account. To find the right value:

i. login to your AWS management console

ii. go to your AWS EC2 dashboard

iii. make sure you have the correct region selected

iv. click ‘Security Groups’ in the side menu

v. in the list of security groups find your Unix-AUT group name

vi. find the ‘Group Name’. You’re looking for this:

This group will be specific to you. You may have used the same name as me but it’s best to check using the steps above. You’ll need to use both the Unix security group (Unix-AUT) and the default security group (default)

That should give us everything we need for this initial stage. Once you have the settings looking like this click the ‘Apply’ button.

Now we’re ready to check that Jenkins can run up an Amazon EC2 Linux Ubuntu instance for us automatically.

8. Return to the Jenkins home page (click ‘Jenkins’ link top right)

9. Click the ‘Build Executor Status’ link on the home page


This will take you to the ‘Nodes’ page. On this page you’ll have a list of nodes that can act as build machiens. You’ll already see your Windows 2008 Master machine listed. You won’t see a slave machine in the list yet because it’s not running yet. However, we can run the salve machine up from here.

 

10. Click the ‘Provision via RocketChatServer’ button and select the AMI we defined earlier

 

At this point you should see a message from Jenkins that ‘This node is being launched’

From here we can do two things:

  1. check the Jenkins log to make sure the node is launched correctly
  2. check our AWS account to see the running node

11. Check the Jenkins log by clicking ‘See log for more details’

At this point Jenkins is logging all the actions carried out as it brings up this Ubuntu instance. What you need to check for is this…

This just tells us that the instance was started and that Jenkins successfully logged in using our private key under the account ‘ubuntu’. You may see some warning messages but as long as the machine is running and the login worked we’re on the right track.

12. Check the AWS management console

On the AWS management console we shold be able to see our new instance running now.

i. go to your AWS EC2 dashboard

ii. make sure you’ve selected the right region

iii. click ‘Instances’ in the side menu

iv. in the list look for Unix-client (or similar)

v. select the Unix-client in the list and check it’s running

At this point you should see something like this…

We’ve successfully run up our Linux Ubuntu instance automatically from Jenkins. Great!

A few things worth mentioning…

Firstly, you may have noticed that one of the parameters we configured in Jenkins for this instance was:

 Idle termination time: 30

This means that if the instance hasn’t done anything for 30 minutest Jenkins will automatically shut the machine down for us. No need to do anything ourselves we can just leave it to Jenkins to shut the system down when it’s not needed.

Secondly, you may have noticed, in the Jenkins logs, that there were some error messages around the installation of Java. Something along the lines of:

WARNING: Failed to download Java

We’ll solve that in the next step when we get Jenkins to run some initialisation scripts on the server. We do need Java though as the Jenkins Java client needs to be installed on this Ubuntu machine in order for Jenkins to have full control over it.

Part 8: Configuring Jenkins – Instance Initialisation Script

13. Set Up the Instance Initialisation Script

The last thing we need to setup during the run up of this instance is the installation of a few additional software packages. These packages aren’t installed on the AMI we’ve started out with. To get round this Jenkins has a field in the EC2 configuration called “Init Script”

To update this we’ll need to:

  1. return ot the main Jenkins dashboard (click the ‘Jenkins’ link top left)
  2. click the ‘Manage Jenkins’ link
  3. click the ‘Configure System’ link
  4. scroll to the bottom of the page where we configured our Amazon EC2 setup
  5. the last section on the page should be the ‘Init script’ field

So we’ll need to add some Unix shell commands to this Init script field. The purpose of these commands is to:

a. update software already on the system

b. install Java (Jenkins needs Java to run it’s remote client app)

c. install npm (more on this later)

You don’t really have to understand this script (it’s just a unix shell script) but as long as you understand why it’s there that’s the important part. So copy the following into the Init Script field:

#!/bin/sh
# Update existing packages and install Java
export JAVA="/usr/bin/java"
if [ ! -x "$JAVA" ]; then
    sudo apt-get update
    sleep 10
    sudo apt-get install -y openjdk-7-jre ca-certificates-java tzdata-java libcups2 libcups2 libjpeg8 icedtea-7-jre-jamvm openjdk-7-jre-headless openjdk-7-jdk git npm
    sleep 5
fi
# Add Swap Space
SWAP=/mnt/swap1
if [ ! -f $SWAP ]; then
    sudo dd if=/dev/zero of=$SWAP bs=1M count=2K
    sudo chmod 600 $SWAP
    sudo mkswap $SWAP
    # add new swap to config and start using it
    echo "$SWAP none swap defaults 0 0" | sudo tee -a /etc/fstab
    sudo swapon -a
fi

You should have this now:

14. Return to the Jenkins home page (click ‘Jenkins’ link top right)

15 .Click the ‘Build Executor Status’ link on the home page

16. Click the ‘Provision via RocketChatServer’ button and select the AMI we defined earlier

At this point you should see a message from Jenkins that ‘This node is being launched’. This time round when you click on the ‘See log for more details’ you should see a bit more going on. In summary the log file should show you …

i. the Instance launching (INFO: Launching instance: i-1ebaa1c7)

ii. the ssh connection (INFO: Connected via SSH)

iii. execution of the Init Script (INFO: Executing init script)

iv. updates to existing software packages

v. installation of Java (INFO: Verifying that java exists)

vi. launching the Jenkins slave (INFO: Launching slave agent)

And then the final entry in the log…

Slave successfully connected and online

17. Go back to the Nodes dashboard (click ‘Jenkins-> Nodes’ in the top menu bar)

In the node list we should now see our RocketChat-Server node up and running:

At which point we have a fully configured Jenkins slave machine, running all the software we need that’s ready for us to start installing our AUT on. Next we’ll look at how to configure Jenkins to get that AUT built and installed automatically.

Part 9: A Few Points about our Jenkins Slave Machine

At this stage we can use Jenkins to start up a slave test machine automatically. There are a few points worth mentioning about how we can control this slave machine now.

Once the slave is running Jenkins runs a ‘Slave Agent’ on this machine. It’s this agent that allows the slave to talk to the master Windows Jenkins machine. It’s this slave that gives Jenkins full control of jobs and actions that can be carried out on the slave.

Slave Idle Termination Time

For example in our configuration for the Amazon EC2 slave (Manage Jenkins -> configuration) we had a setting called ‘Idle termination time’

This tells Jenkins that if the slave is inactive for more than 30 minutes to ‘Terminate’ this slave Linux EC2 instance. Great for keeping control of our Amazon charges (don’t want to be spending money on machines that are standing idle). Not great if we have data on that machine that we need as we’ll lose it all when it’s terminated. For us though we’re not worried about losing data so this’ll be just fine.

Managing Slaves from the Jenkins Master Machine

Return to the Jenkins home page and click on the link for our slave.

Viewing details for our slave you’ll see a number options in the left hand menu. These options allows us to:

Delete Slave: select this and you’ll Terminate the Amazon EC2 instance for this slave.

Configure: from here you can view and modify some of the configuration parameters for this slave

Build History: details about builds we’ve run on this slave.

Load Statistics: stats on how hard this machine is having to work.

Script Console: feature allowing us to run Groovy script on the slave machine from our Jenkins master machine

Log: details about the running up and install activities that took place when we created this instance

System Information: full list of system properties

Disconnect: the ability to disconnect Jenkins from the slave but leave the instance running still (you can reconnect later if you need to)

Part 10: Setting Jenkins up to install the AUT

So the last bit to configure is the download, build and install of the application under test (AUT) on our slave machine. The AUT we’re going to use is a chat application called Rocket Chat.

https://rocket.chat

Now it’s worth mentioning here that this is just an example app we’re using for this course. We’ll go through the steps to build and install this app but you DON’T need to understand the scripts needed to build and install Rocket Chat. These are specific to Rocket Chat.

In practice, when you’re testing your own applications, you’ll need to replace the Rocket Chat build and install scripts with your own scripts. This will mean talking to your developers or build engineers. Then adding the build/install steps for your app into Jenkins.

So from this you just need to understand how you configure Jenkins. You don’t need to understand the Rocket Chat build/install process. In real life you’ll have your own applications build/install process to add to Jenkins.

Jobs and Node Labels

Jenkins is all about configuring and running jobs. Those jobs are typically build jobs but they can include any task you need to automate. For example jobs that run tests and jobs that install applications. Anything you need to automate Jenkins can be configured to run as a job.

Jobs need to run on nodes or slaves. Jenkins has some pretty clever features for working out the best places to run jobs (e.g. on the master machine or a particular slave). We’re going to keep it simple though. We going to give our slave/node a label (e.g. RCBuildDeployServer). Then when we configure the Job we’ll say “the job must be run on a slave/node that has label RCBuildDeployServer”. This way we tell Jenkins not to run everything on the Master machine (which is the default) but to run up an instance of the slave that we need (if it’s not already running) and run the job there.

So first up we to make sure we’ve configured our node/slave label.

Node Labels

To give our Linux Ubuntu instances a lable we need to go back to our Jenkins coniguration page.

1. On the Jenkins home page click on ‘Manage Jenkins’

2. On the Manage Jenkins page click on ‘Configure system’

3. Scroll to the bottom of this page and find the ‘Amazon EC2’ section

4. In the ‘Labels’ field enter ‘RCBuildDeployServer’

 

5. Click the ‘Save’ button

Setup the Job

Now we can specify where we want to run a Job (on the slave/node labled ‘RCBuildDeployServer’) we can configure a new job

1. On the Jenkins home page click on ‘create new jobs’

2.  Enter a Job name (e.g. ‘BuildRocketChatOnNode’), select ‘Freestyle Project’ and click OK

3.  On the Job configuration page set these key values

Restrict where this project can be run: RCBuildDeployServer

Source Code Management: None

Build Triggers: Build periodically

No need to add a schedule here yet. We’ll kick our jobs off manually for now.

4.  Click on the ‘Add Build Step’ button and select ‘Execute Shell’

5. In the command text box we need to add our build script. Remember you don’t need to understand the detail here. Just that for our demo app these actions build and install the app. You’ll have a completely different set of actions for your application.Copy and paste all of the scripts below into the ‘Command’ field:

#Clean up if any left overs from last build
SCREEN_RUNNING=’/usr/bin/pgrep SCREEN’
ifSCREEN_RUNNING fi NODE_RUNNING=’/usr/bin/pgrep node’ ifNODE_RUNNING fi if [ -f master.zip ]; then rm -f master.zip fi INSTDIR=./Rocket.Chat-master if [ -dINSTDIR fi MONDIR=/home/ubuntu/db if [ -d $MONDIR ]; then rm -Rf /home/ubuntu/db fi pwd #Install packages we need for the build sudo apt-get install unzip curl https://install.meteor.com/ | sh sudo npm install -g n sudo n 0.10.40

 

#Configure Mongo Database
MONDIR=/home/ubuntu/db
if [ ! -d $MONDIR ]; then
mkdir /home/ubuntu/db
fi
pwd

 

#Build and install Rocket Chat
export PUBLIC_HOSTNAME=”$(curl http://169.254.169.254/latest/meta-data/public-hostname 2>/dev/null)”
wget https://github.com/RocketChat/Rocket.Chat/archive/master.zip
unzip -o master.zip
cd ./Rocket.Chat-master
meteor build –server $PUBLIC_HOSTNAME –directory .
cd ./bundle/programs/server
npm install
cd ../..

 

#Make sure processes continue to run when Jenkins script completes
echo -e “\n”
ps -ef
export BUILD_ID=dontKillMe
echo -e “\n”

 

#Start mongo DB and Rocket Chat
screen -d -m /home/ubuntu/.meteor/packages/meteor-tool/.1.1.10.ki0ccv++os.linux.x86_64+web.browser+web.cordova/mt-os.linux.x86_64/dev_bundle/mongodb/bin/mongod –bind_ip localhost –dbpath /home/ubuntu/db/ –smallfiles
sleep 10
export MONGO_URL=mongodb://localhost:27017/rocketchat
export ROOT_URL=http://localhost:3000
export PORT=3000
screen -d -m node /home/ubuntu/workspace/BuildRocketChatOnNode/Rocket.Chat-master/bundle/main.js
sleep 10

 

# list system details and what's running on the system before we complete script
    echo -e "\n"
    pwd
    echo -e "\n"
    env
    echo -e "\n"
    ps -ef

So at this stage we should have the Build Execute script entered as shown

Like I’ve said this little lot is particular to the Rocket Chat app we’re using for this example. When you come to implement this in the real world you’ll work with your developers to determin what goes in here.

We can then click on the ‘Save’ button

6. On the Job summary page click the ‘Build Now’ button

7. Jenkins will go through a few steps now. First it will run up a Linux Ubuntu EC2 slave machine. This is the slave machine Jenkins needs to buid and install the application on.

If you check your AWS dashboard you should see this instance initializing. It may take a while as it has to run through all the initialisation scripts we defined too.Then, once the slave is ready, we’ll see the build start.This is our first build, as indicated by the ‘#1’ tag. We can view the detail and progress on this build by clicking on the ‘down arrow’ next to the #1 and selecting ‘Console Output’

 

The console output will list all of the actions being carried out as part of this build and install.

This may take some time!

Once the build and install is complete you should something like this at the end of the log file

From here we can check if the application is actually running on our slave EC2 Linux Ubuntu instance.

7. On your Windows RDP session, open a new tab in Internet explorer. Enter the following address: http://localhost:3000

You should see the application running like this:

If you want to login and play with Rocket Chat you can click on the ‘Register a new account’ link (you don’t need to follow any email confirmation process – the first login can be created direct from the GUI).

If you go back to your Jenkins home page you should see the successful build reported as follows:

Accessing Rocket Chat from your Local Machine

If you want to access the Rocket Chat application from you desktop/laptop then follow these steps:

  1. in your EC2 management console select the Linux host
  2. find the ‘Public DNS’ value
  3. Construct the following Url: http://<public-dns-value>:3000
  4. Enter this Url in your browser

Note that this will only work if your security groups are configured correctly and Public DNS settings are configured. See module 1 of this course for more info.

All that remains now is to setup a few clean up actions and a few tests to make sure Jenkins reports the build/install as a success.

Part 11: Jenkins Post Build Actions and Smoke Tests

Once we have a setup that will build and install our application it’s worth configuring Jenkins to run a few checks and tests just to confirm that things completed without any issues.

We’ll use the Post-Build Actions feature to carry out two actions:

a) check the logs for successful install messages
b) use ‘wget’ to check that the Rocket Chat home page is displayed

We can set these up by following these steps:

1. go back to the Job configuration by selecting configure on the home page.

 

2. Scroll to the bottom of the configuration page to find the Post Build Actions section

3. Click the ‘Add post-build action’ button and select the ‘Post Build Task’ option

Check the Logs

We’ll configure a task to look for 2 log messages. Two log message that we know we should see during the install if it’s been a successful install.

4. In the Log text field enter this text (it’s a reg ex expression)

00:..:.. SCREEN -d -m node /home/ubuntu/workspace/BuildRocketChatOnNode/

Then click the ‘Add’ button and add a 2nd log message check

00:..:.. SCREEN -d -m /home/ubuntu/.meteor

These checks are specific to the Rocket Chat application install. Again when you build this for your own application you’ll have to replace these with checks specific to your build. For info though these messages are checking that the Rocket Chat processes were successfully started and running.

5. In the Script field enter this shell script text

!/bin/bash
#keep checking to see when Rocket Chat is up and running
for I in 1 2 3 4 5 6 7 8 9
do
sleep 60
# use wget to see if we can download index page
# if wget returns true we can download index page
# -T 3 => wait 3 seconds for response
# -t 1 => means only retry once
if (exec /usr/bin/wget -T 3 -t 1 http://localhost:3000)
then
echo “Rocket Chat now running ”
exit 0
else
echo “Waited $I minute(s) - Rocket Chat not running yet ”
fi
done
echo “ Rocket Chat didn’t start ”
exit 1

Again this is specific to Rocket Chat. We’re just running this script on the Linux Ubuntu Rocket Chat server to see if Rocket Chat starts running. We’re using a Unix command called ‘wget’ which gets a web page, the Rocket Chat home page. If this command returns a 404 over 10 attempts then we fail the check. If it returns a http 200 response code then we pass the check.

6. Check the ‘Run script only if all previous steps were successful’ check box

It’s only worth running the shell script if the checks on the log file pass.

7. Check the ‘Escalate script execution status to job status’ check box

If these checks pass then mark the build in Jenkins as a pass. If any of these checks fail then mark the build as failed in Jenkins. We’ll see the reporting of these results in a minute.

Then click the ‘Save’ button

Part 12: Starting Subsequent Jenkins Builds

Now at this point, do you remember this setting in your Amazon Ec2 configuration…

 Idle termination time: 30

Well your Linux slave machine has probably been idle for 30 minutes now. As a result it’s probably shut itself down. Then again maybe you went through this really quickly and it’s still running. Either way, depending on the state of this slave machine Jenkins will do one of two things when we start a new build:

a. If it has shut itself down:

When we kick off a new build it will start from the beginning and create a new EC2 instance.

NOTE: if the node has been shutdown and then a new node run up for a subsequent build then the new node with have a NEW IP ADDRESS and HOSTNAME.

b. If it hasn’t shut itself down:

The slave is still running, so Jenkins just needs to start a new build and install using the existing slave machine

If you want to avoid these nodes shutting down you can always extend the Idle termination time to more than 30 minutes. Or set it to 0 so that it always stays running (mind your AWS spend if you do this though).

Start the next build

1. Return to the Jenkins home page

2. Click the Job name (just to the right of it) and select ‘Build Now’ from the drop down menu

Assuming you didn’t have a slave running the whole process will kick off again, starting with the running up of the Amazon EC2 instance. Then the build/install will take place. Then we’ll run our completing checks/tests.

Don’t forget it can take a few minutes for these Amazon EC2 instances to run up. It can also take up to 10 minutes to complete the full job including the build and install. This is because we’re using free tier instances within AWS. Please be patient.

If the build, install and tests all succeed then we’ll see this Blue lamp and the sun icon on the Jenkins home page:

If anything fails we’ll see a red lamp and the weather will start to turn cloudy:

BTS-module2-subsequent-builds

Getting it badly wrong over a number of builds and the weather turns to Thunder and Lightning.

BTS-module2-subsequent-builds

In short the lamp indicates the state of the last job. The weather is an indication of job stability. So an aggregation of results across the last few builds.

Conclusion

Building on our AWS environment we’ve configured Jenkins so that we can control a slave machine (an Ubuntu Linux machine) and build and install the application under test. We’ve also factored in a few small checks to make sure everything is up and running.

The key take away here is that Jenkins is not just for building software. It’s not even just for implementing continuous integration. Both of these are great goals. However, on it’s own it’s just a great tool for testers. It allows us to automate a lot of our repetitive tasks like running up test environments and installing the software we need to test.

Then as we add to this the capability to kick of automated tests we’re into making our test process far more efficient. And what we’ll move on to next, in module 3 of this course, is linking in automation tools like Selenium.

Free Test Automation Framework Course
Learn the Practical steps to building an Automation Framework. Six modules, six emails (each email a short course in it's own right) covering Amazon AWS, Jenkins, Selenium, SoapUI, Git and JMeter.
Facebooktwittergoogle_plusredditpinterestlinkedinmail
1 2 3 17