Tutorial

Kazuki Tutorial

The aim of this guide is showing the installation steps, as well as the basic steps to run an automation script using Kazuki.

Installation

Linux (ubuntu examples are provided)

First of all we need to have Ruby installed (1.9.x officially supported):

sudo apt-get install ruby1.9.1

Once Ruby is installed, we use gem to install the required libraries:

sudo gem install selenium-webdriver pry

Additionally the crome driver for linux needs to be downloaded separately, because the selenium-webdriver gem only comes with firefox webdriver by default. The cromedriver for linux can be downloaded from http://code.google.com/p/chromedriver/downloads/list, please download the latest version and keep in mind the architecture of the client computer.
Once downloaded and extracted, the file can be moved to a directory currently on the system path (i.g. /sbin) and that's enough to make it work.

That is all, now we can clone the Kazuki git repo or download the latest stable version from the "Files" page.

Windows

First of all Ruby 1.9.x needs to be installed, please go to http://rubyinstaller.org/ to get the binary installer

Besides the ruby interpeter we also need to download the corresponding development kit (i.e. tdm-32-4.5.2)

*NOTE: Only Ruby 1.9.x is officially supported

Once both installers are downloaded, we can proceed with the client's intallation (fairy simple one) make sure ruby is added to windows path.

The toolkit is a little bit more tricky to install, the installation instructions can be found here:
https://github.com/oneclick/rubyinstaller/wiki/Development-Kit

Then we open the windows console and use gem to install the needed libraries:

gem install selenium-webdriver pry

Finally we download the webdrivers for IE and Chrome from the following URLs:
http://code.google.com/p/selenium/downloads/list
http://code.google.com/p/chromedriver/downloads/list
All it takes to make these drivers work is to unzip the file into a folder included in window's path (I.g. C:\Ruby193\bin)

This should be enough to make the framework operative. Now we can proced to clone the git repo or download the latest stable version.

Cloning git repo

We can do it with the following command:

git clone git.code.sf.net/p/kazu/code

The location of the repo is not important as long as the internal folder structure is not changed

Running a script

All kazuki scripts are located by default on \test_cases_scripts directory, which can include subdirectories. To run a script all we need is to enter that directory and type:

ruby [script_name.rb]

I.g.: ruby Example_Script.rb

Note: If the script has the magic comment on it #!/usr/bin/env ruby and execution permissions we can just call it by ./script_name.rb

Execution Control

Every script contain it's own execution control, which allows to define for every script:
- How many test cases are run
- Which browser (or browsers) will be fired
- Local selenium driver vs. selenium grid
- Concurrency, how many test cases run in parallel

Test case Execution Control

Inside each script test cases are defined as methods within an "AcceptanceCriteria" or "TestPlan" object (you can actually use any name). Then you just instantiate this new object and call the methods (test cases) that you want to run. Let's see an example:

newTest = AcceptanceCriteria.new(qa, browser)

newTest.Case001
newTest.Case002

Browser Management

For selenium to recognize what browser to run for a particular script run, we need to specify the browser by sending a keyword as a parameter to instantiate a new webdriver object. The AcceptanceCriteria class on every script takes this keyword as a parameter and is in charge of instantiate the webdriver object:

newTest = AcceptanceCriteria.new(qa, :firefox)

The possible kewords include (but are not limited to):
- :firefox
- :chrome
- :ie

Selenium Grid vs. Local Webdriver

There are two ways to execute a ruby+selenium script:

+Local Webdriver This is the default way, on initiation the script runs the browsers locally on our pc, using what options and capabilities we have sent to the driver. On one hand it can be counter productive to run scripts this way, because concurrency or a change on the window focus can cause synchronization problems making the script fail. On the other hand it is the best way to debug using the debug console, because selenium grid has a session timeout that closes the browser window when no activity is detected for a relative period of time.
+Selenium Grid 2: This is a tool that allow us to distribute script runs between several nodes concurrently. Grid counts with a hub that recieves session requests from one or more nodes, which in turn open the browser sessions requested by the hub. Grid is the recommended method for formal automation test runs.

To select which kind of driver to use we need to alter how the webdriver object is created within the script. This happens in the constructor method of the AcceptanceCriteria object (the selenium driver is stored on the @driver global variable), therefore we can use one of the following sentences:

Local: @driver = Selenium::WebDriver.for browser

Webdriver: @driver = Selenium::WebDriver.for(:remote, :desired_capabilities => browser

Lastlly if we are going to use grid and the hub runs on a remote machine, we must send the address as a parameter, as shown on the following example:

@driver = Selenium::WebDriver.for(:remote, :url => "http://127.0.0.1:4444/wd/hub", :desired_capabilities => browser)

Replace 127.0.0.1 with the destination address and 4444 with the port we are using (4444 is the default grid port though)

Concurrency

Kazuki does concurrency on two different ways:
Running multiple scripts in parallel
Running several instances of the same script in parallel

The first way is accomplished simply by running different ruby interpeters, either by a scheduler or a deployment software like Jenkins.

The second one happens inside the script and it is basically process handling for the AcceptanceCriteria object. Ruby have several ways to run subprocesses (and not all compatible with Windows btw), but on this case we are goint to take Process.fork as an example to run the same script concurrently on 3 different browsers:

browsers = [:chrome, :firefox, :ie]

browsers.each do |browser|
Process.fork do
newTest = AcceptanceCriteria.new(qa, browser)
newTest.Case001
newTest.Case002
end
end

As you can see it's simply a matter of creating an array and iterate through it using fork to create a new subprocess for each browser.