UnitTestHarness  1.0
Unit Testing Tool
 All Data Structures Namespaces Files Functions Variables Pages
README

#README #Quickstart Guide - How to execute your Unit Tests on your component


Overview

This document is a summary of the steps required to incorporate your Unit Tests into the EN-ICE-SCD Test Harness and run them. The steps apply to installation on Windows or Linux. A longer detailed description is contained in the original Test Harness design document, see: Doc/unitTestingDesign.docx

This document covers:

Where to find the Unit Test Harness Software

The harness source and documentation (including this Quickstart document) is all kept in SVN at https://svn.cern.ch/reps/en-ice-svn/trunk/tools/JCOP/Projects/Framework/Test/UnitTestingHarnessAndComponent File references in this current document are also valid relative to this root.


Installing the Unit Test Harness Software

  • Download the directory structure from the above SVN location. We suggest putting it in C:

What do you need to install into your computer?

  • If you know that you only want to test using the interactive panel, you need only install the fwUnitTestComponent into your WinCC-OA project.

By the phrase "Unit Test Harness" we mean all of the following bullet points:

  • The fwUnitTestComponent
    • This contains the panel and associated files that must be installed into a User's project to allow him to run the Unit Tests interactively (ie from the panel).
  • The Python Source files.
    • These are the source files that must be installed on a User's machine to allow him to run the Unit Tests from a command line.

By default (or if you are not sure!) then install both of the above; however:

  • If you know that you only want to run your tests from a command line (or from Jenkins) you only need to install the Python Source files.

To install the FwUnitTestComponent (i.e. the graphical bit) into your WinCC-OA project

Install the component in the usual way, using the FwInstallation Tool.

To install the Python Source files (the command line bit)


Writing your Unit Tests

The [ExampleOfAComponentToBeTested](ExampleOfAComponentToBeTested) folder contains the files of a typical, trivial JCOP-Framework-style software component. Below this folder are also included examples of Unit Test code for the trivial component itself. You should create files following this same structure in your component. A detailed description of the format and meaning of the individual files is given in the Doc/unitTestingDesign.docx

Especially, don't forget to provide a Unit Test configuration file (see Config\README.html) !!

Finally, (at risk of sounding recursive!) don't forget to TEST your Unit Test sources! Be sure to check your test*.ctl file(s) for syntax errors (and even execution errors?) before you invoke them with the harness. Your sources get invoked by the harness using "eval" and any error messages that come from your source can be a bit cryptic... A trivial panel with a simple button to execute and debug your test routine before you give it to the harness might well save you a lot of time :-)


Executing your Unit Tests from a panel

Open the panel to run your tests. See also the help in the panel. As always, keep an eye on the PVSS_II.log file when running what is, after all, a WinCC-OA application.


Executing your Unit Tests from a command line

The following commands may be typed directly into a command line or even executed from within a Jenkins job. The examples below assume that you have first cd'd to the *.*.

The basic command to run the unit testing harness is :

python runUnitTests.py 

Available options can be viewed with -h as follows :

python runUnitTests.py -h

Executing your Unit Tests from a Jenkins Job

The Jenkins job must issue the appropriate command line command. An example of a Jenkins job configuration, that does this can be found at : https://svn.cern.ch/reps/en-ice-svn/trunk/tools/JCOP/Projects/Framework/Test/Hudson/jobs/UnitTestHarnessStart.

The SVN contains the master version. This job within Jenkins can be found at : https://icejenkins.cern.ch/view/SCD-Testing/job/UnitTestHarnessStart/.


Appendices


Unit Testing Harness Folder Structure

Within the Unit Testing Harness SVN tree, you will find the following files and folders:

  • README.* : The file you are currently reading.
    • README.md is the master file.
    • README.html is derived from the ".md" markdown file.
  • setup.* : These are for setting the UNITTESTHARNESS_* evironment variables. For windows use setup.bat and for Linux use *./setup.sh*
  • Doc : Contains the original specification/design document plus important diagrams.
  • ExampleOfAComponentToBeTested : A very simple example "Framework" software component. These files follow the layout rules common to all JCOP Framework components, as expected by the JCOP Framework Installation tool. The folders within this ExampleOfAComponentToBeTested show where test files should be located and the naming conventions to follow. The example illustrates using :

    • setup() - to setup the environment for an individual test
    • teardown() - to cleanup after a test
    • setupSuite() - to setup the environment that will be common to all tests in a test suite
    • teardownSuite() - to clena up after executing a test suite.

    The example files in folder *.* also show how to provide mock routines specifically for use during your tests.

  • Sources : This folder contains python scripts that are used when running the unit tests from a command line.
    • Config : The config folder contains a "magic number" file with the location of the fw installation tool that will be used during the tests.
  • Config : The config folder contains several examples of unit test configuration XML files. See the README in this folder for a description of the structure of these XML files.
  • FwUnitTestComponent : This folder contains the sources of a Framework component that contains the interactive panel for driving your Unit Tests. Install this FwComponent (using the FwInstallation tool) into your WinCC-OA project.
  • Results : This folder and the files within it will be generated automatically when you run the unit testing harness via the command line.

Magic String Definitions

The following files contain Magic Strings that must be set appropriately for your installation!

Which FwInstallation tool to use

Is specified in Sources\Config\fwInstallationToolLocation.config

Password

When pvssdev's password changes, you must update the file Sources\emuSvn.py

Where to find a Linux Server (needed when you are on Windows)

On Windows, we use Putty to access files on AFS. *Sources.py* specifies the hostname of any Linux machine that pvssdev can use to access files on AFS. Any handy machine will do. The current linux machine being used happens to be cvpc103.cern.ch but if this should ever change, you must specify the new machine in puttyGet.py


Predefined Assert Statements - Summary

The following assert() routines have already been implemented for you in FwUnitTestComponent\scripts\libs\fwUnitTestComponentAsserts.ctl


Glossary of Terms

  • Unit Test Suite
    • A collection of test cases. In our implementation, a test suite corresponds to a single file.
  • Unit Test Case or Unit Test

END