This document is obsolete, please read the documentation inside the Testing Tools package.

== IT Mill Testing Tools (TT) HOWTO ==

Download

http://www.itmill.com/download/TT/itmill-testingtools-0.9.3.war

Requirements

Toolkit applications which are to be tested need at least Toolkit version 4.1.0-rc3.

TT Server requires Servlet Container. You may run TT Server on any the same Servlet Container where you run your testable applications, but on larger test environments it is advisable to use dedicated server for TT Server.

All client testing hosts need SSH server, also Windows requires psexec.exe and taskkill.exe (XP includes this) executables.

Limitations

Recording and playing test cases works only with Firefox 2. Safari 3 support is also being developed but not yet supported.

Automatic testing has been only tested with Windows XP, all Linux platforms should work.

Setting test environment

Configuring TT Server

Install TT war package to any Application Server (/Servlet Container), we suggest that you use /TestingTools for context. If you are using Apache Tomcat, the simplest is to rename itmill-testingtools-<version>.war into TestingTools?.war and just copy it to webapps directory from where it will be auto-deployed by Tomcat.

Notes

TT Server stores all configuration and test data into an SQL database. By default it is located under Application Server directory structure. With Apache Tomcat database files are located under apache-tomcat-<version>\TestingToolsServerDatabase?.* If you wish to change the location of database file, you need to override following context wide parameter: 

 <context-param>
  	<param-name>testingToolsServerDatabaseURL</param-name>
  	<param-value>TestingToolsServerDatabase</param-value>
  	<description>Testing Tools Server Database URL</description>
  </context-param>

Specify explicit path after file tag, e.g. C:\TT\mydatabase. Overriding web.xml parameters is Application Server specific, but one option is to unzip TT WAR, edit web.xml by hand and rezipping TT WAR.

Existing database is reused when TT.war is redeployed, so it is safe to upgrade TT war without losing old database.

Configuring Toolkit applications

Activating TT for Toolkit application is done by adding following parameter e.g. to web.xml 

  <context-param>
  	<param-name>testingToolsActive</param-name>
  	<param-value>true</param-value>
  	<description>IT Mill Testing Tools activation</description>
  </context-param>

If TT Server is located on the same host as testable Toolkit applications, no further configuration is required.

If TT server is located on different host than testable Toolkit applications, you need to tell every Toolkit application where TT Server is located: 

   <context-param>
  	<param-name>testingToolsServerUri</param-name>
  	<param-value>http://localhost:8080/TestingTools/</param-value>
  	<description>IT Mill Testing Tools URI</description>
  </context-param>

Note: On larger environments it is a wise action to use dedicated server for TT Server.

Configuring automated testing environment

It is advised to use dedicated server for TT Server. This is because testing itself may crash Toolkit application servers into such state that TT Server also goes down in case you deploy TT Server to same host where Toolkit applications are run.

Testing hosts are most convinient to install on virtual environments using softwares such as VMWare Server or Virtual PC. With virtual environments it is easy to setup tens of identical hosts by cloning existing host.

Hosts need to have SSH service and an user account. Test account credentials (username and password) can be set through TT Server, just ensure account exists on host.

Linux environments need X window system.

For Windows XP environments it is suggested to install OpenSSHD package, download from Sourceforge. You need to create C:\TT directory and add files from http://localhost:8080/TT/ext/AUTClient-bin/winxp to C:\TT, assuming that your TT Server was deployed on localhost:8080. You also need free software called PSTOOLS from Microsoft, download from Microsoft. Manual installation is required, just install it to any directory, then copy PSEXEC.EXE into C:\TT and double-click it once to accept the license.

Using TT

Recording tests

Open browser and go to your Toolkit application, but add to your application URL TT parameter. For example, like this: http://toolkit.itmill.com/demo/Calc?TT. This brings your application to your browser and TT Control Panel on top of your application. TT Control Panel is initially on record mode, you can now start interacting with your application, keyboard and mouse events are recorded. When done, click "Save current test case" icon. Testcase is is now sent to TT Server and TT Server is opened to your browser. In case of issues, check for all opened browser windows to see where TT Server window opened.

Playing tests manually

Get testcase id from TT Server's Recorded testcases table, see ID column. You also need to understand which application this testcase is meant to be executed against, URL column helps on this. Because testcases may be executed against multiple different serves, IP number is not stored to URL.

To playback testcase open browser and go to your Toolkit application, but add to your application URL TT parameter and TT-TC parameter with testcase ID value. For example, like this: http://toolkit.itmill.com/demo/Calc?TT&TT-TC=2.

TT Control Panel

Control Panel can be in two different modes, either recording or playback. Each mode is either active meaning that TT is interacting with the application, or non-active meaning that TT is not interacting with the application.

Switch modes by clicking "Record" or "Playback".

Control Panel log window is displayed at recording mode.

Recording mode looks like this:

Commands

Add comment to the testcase script

  • Adds javascript comment to testcase script, does nothing while playing testcase

Add a message to testcase

  • Adds text message which is displayed on log window while playing testcase

Create an assertion point

  • Creates "checkpoint" using equals operator, assert result is displayed on log window

Save current testcase

  • Sends recorded testcase to TT Server and opens TT Server GUI to your browser

Open TT Server in a new window

  • Access TT Server GUI

Stop and show a message during playback

  • Used for semi-automatic testing, e.g. testcase requires manual interaction before continuing with testcase
  • When testcase is played, playback is stopped and given message is shown on log window
  • Playback can be resumed by clicking Play current testcase icon

Clear current tescase

  • Clears recorded testcase

Minimize TT panel

  • Gives you more room to interact with your application while recording

Playback mode looks like this:

Commands

Play current testcase

  • Plays testcase

Stop on failure

  • If any asserts fail, playing testcase is interrupted

Automatic testing and scheduling

See Configuring automated testing environment first.

Scheduling is programmed through TT Server GUI in Scheduled Tasks tab.

TBD.

Understanding how TT works

TBD

  • explaing DOM structure
  • how components are found
  • motivation for UIIDs (a'ka anchor points in DOM)
  • how to deal java Random

How to do more robust testing

  • Add few myLabel.setUIID("myLabel"); anchor points to your Toolkit application code

Advanced concepts

TBD

  • enhancing testcases using JavaScript?
  • executing arbitrary host level binaries, e.g. take screenshot in testing hosts
Toolkit TT JavaScript? API description

TBD

setStepWaitTime(time)

  • Wait time milliseconds before next step

stepFast()

  • Step as fast client / server can perform

stepNormal

  • Step at standard speed

stop()

  • Stops script execution, execution can be resumed by clicking control panel's play button

assert(ID, path, operation, value)

key = function(ID, path, eventType, keyCode, charCode, ctrl, shift, alt)

keypress = function(ID, path, charCode)

mouse = function(ID, path, eventType, button, ctrl, alt, shift, meta, x, y)

mouseMove = function(ID, path, clientX, clientY)

focus = function(ID, path) blur = function(ID, path)

change = function(ID, path, newValue)

click = function(ID, path, button, ctrl, alt, shift, meta, x, y)

typeText = function(ID, path, text)

scroll = function(ID, path, sTop, sLeft)

addMessage = function(message, color)

getObjectByPath = function(ID, path)

TT internet demo site

Attachments