Site-specific properties, setup and teardown example

Author: Jiri Skrivanek
Date: January 30, 2002

---

This document describes example of site specific setup. Sources can be found in CVS repository in directory xtest/examples/MyModule/test. Look for site-specific prefixed files and directories. Remember that site-specific is only name of test type. Your testtype can have a different name.

Create test case

Example of site specific test case can be database related operations. Connection parameters are different for every database and for every site/machine where tests are executed. For example url property contains connection string to a particular database. It is expected that property "url" is set outside the test case by XTest and its value can be obtained like this:

        url = System.getProperty("url");
        if(url==null) {
            fail("Property url hasn't been set");
        }

It is possible to get values of properties in setUp() method. You can see two simple examples: TestDatabases - it tries to connect to a database and TestViews - it connects to a database and checks whether database contains some views.

Create properties file

In order to execute such test case you need to define properties somewhere. We can create databases.properties file which will contain definition of properties for every XTest attribute (database name in this case). For example, the "url" property will have these definitions:

xtest.userdata(oracle)|url=jdbc:oracle:thin:@<hostname>:1521:<database>

xtest.userdata(mssql)|url=jdbc:weblogic:mssqlserver4:<database>@<hostname>:1433

xtest.userdata(pointbase)|url=jdbc:pointbase://localhost:9092/sample

It means that we can use "oracle", "mssql "and "pointbase" as attributes to run test.

Create cfg-site-specific.xml file

Config file for site specific tests has nothing special. You can define testbags regarding your expectations. In database example we can, for example, suppress executing of particular test case for a database which doesn't support tested feature:

    <testbag testattribs="(all OR stable) AND NOT pointbase" executor="code" name="Test views">
        <testset dir="site-specific/src">
            <patternset>
                <include name="TestViews.class"/>
            </patternset>
        </testset>
    </testbag>

Tests from TestViews.class will not be executed for PointBase database.

Create site-specific-build.xml

In the build file we can set additional classpaths, compilers and executors. For database tests we need to add JDBC drivers to classpath. As you may notice we have defined "jdbc.drivers.path" and "jdbc.drivers.jars" properties in databases.properties file. In build-site-specific.xml we use these properties:

<property name="xtest.extra.jars.path" location="${jdbc.drivers.path}"/>
<property name="xtest.extra.jars" value="${jdbc.drivers.jars}"/>

Run tests from module

In the case you have modified databases.properties file to real values and databases are running, you should be able to run test successfully. Go to directory xtest/examples/MyModule/test and execute:

ant -Dxtest.testtype=site-specific -Dxtest.userdata.propertyfile=databases.properties -Dxtest.attribs=oracle,all

or

ant -Dxtest.testtype=site-specific -Dxtest.userdata.propertyfile=databases.properties -Dxtest.attribs=pointbase,all

Please note, if you don't have xtest installed in the standard location (nb_all/xtest) you have to run ant with xtest.home property set to your xtest home (-Dxtest.home=<your-xtest-home>).

Modify master config

In the directory xtest/xamples/examples-instance there is master config file to run all examples. Config element to run created site-specific examples should be as follows:

  <config name="site-specific" setup="pointbase">
    <property file="${databases.properties}"/>

    <module name="MyModule" testtypes="site-specific" attributes="all,oracle" />
    <module name="MyModule" testtypes="site-specific" attributes="all,mssql" />
    <module name="MyModule" testtypes="site-specific" attributes="all,pointbase" />
  </config>

  <setup name="pointbase">
    <start antfile="${pointbase.setupfile}" target="start" onBackground="true" delay="3000"/>
    <stop antfile="${pointbase.setupfile}" target="stop"/>
  </setup>

It means that you have to supply path to properties file in ${databases.properties} and then all tests of site-specific testtype will be executed with oracle, mssql and pointbase properties.
There is also defined setup element. Target start will be run once before first test is executed and target stop after all tests are finished. You also have to point to an XML file where these targets are implemented (pointbase-setup.xml for example).

Run tests from instance

If you modified all files according to your environment, you should be able to run all tests from XTest instance. Go to directory xtest/examples/examples-instance and run:

ant runtests -Dpointbase.setupfile=<your-path>/pointbase-setup.xml -Ddatabases.properties=<your-path>/databases.properties -Dxtest.config=site-specific