Version 5
Created by ochaloup on Apr 12, 2019 5:25 AM. Last modified by ochaloup on Apr 15, 2019 3:28 AM.

    /qa module which can be found at the Narayana repository contains an extensive set of tests for verification of transaction manager functionality in a distributed environment where communication runs over iiop. In other words, it tests JTS implementation in Narayana. Tests are written to start several JVM instances where servers communicate with each other. That makes these tests running a nice set of integration test cases but it makes running them a bit long-running action. The purpose of this article is clarifying a few things about the test suite and give some advices on how to run it.

     

    /qa module structure

    The code is in java and is compiled as a maven project. But maven only compiles the java source code. The test execution is run with ant.

    Ant starts the test class which is named with prefix org.jboss.jbossts.qa.junit.testgroup.TestGroup*. This class then set up the environment and start the test. As said the test comprised from starting several JVMs where each of them does the JTS transaction processing. The task that the started program in the JVM performs is defined by abstract class org.jboss.jbossts.qa.junit.Task, or more specifically by org.jboss.jbossts.qa.junit.TaskImpl.

    The settings of which test with which parameters is executed is defined in 'run-tests.xml' used by ant. Each Task running in the separate JVM is configured by command line arguments defined in file TaskImpl.properties. This file is not present directly in the repository but there is TaskImpl.properties.template which needs to be adjusted to the machine the /qa tests are run at. The inspiration could be taken from the setup for Narayana CI in script narayana.sh.

     

    Another place where some configuration is stored in the directory 'config' where are stored information on how to connect to databases when the test requires a database for its run. Not all the tests need the database for being run.

     

    How to run

     

    Prerequisites

    • Expecting you will be having installed 'ant-junit' on your system. For Fedora "dnf install ant-junit".
    • Expecting JAVA_HOME being defined

     

    Quick how to run

    If you want to just run a test with setup the /qa module you can follow these commands (this was tested for Narayana 5.9.5.Final and you run with idlj sun orb).

     

    • build the whole Narayana repository. It's needed the narayana-full.*zip artifact would be available. The content is moved to the /qa/dist/narayan-full-* directory. The default setup for the TaskImpl.properties reference this directory when creating a classpath for starting the Task.
      You can build Narayana project simply with ./build.sh clean install -Pcommunity -DskipTests -Didlj-enabled=true and more details is in README.md or at Building Narayana and updating WildFly modules.
    • ant is not used only for the starting the build but the tasks define for example build of the iiop 'idl' interfaces. That's the 'ant dist' command

    ant -Dorbtype=idlj  dist
cp TaskImpl.properties.template TaskImpl.properties
sed -i 's/^\(COMMAND_LINE_0=\)/#\1/' TaskImpl.properties && sed -i 's/#\(COMMAND_LINE_0=\${java.home}\)/\1/' TaskImpl.properties
sed -i -e '/^.*separator}jacorb/ d' TaskImpl.properties
export DISTOPENJDKORB=`echo dist/narayana-full-*Final/lib/ext/openjdk-orb.jar`
export DISTOPENJDKORB=`echo $DISTOPENJDKORB`
sed -i "s#NEXT_COMMAND_LINE_ARG.*#COMMAND_LINE_16=-Xbootclasspath/p:$DISTOPENJDKORB#" TaskImpl.properties
ant -Dorbtype=idlj  dist
ant -f run-tests.xml -Dtest.name=otsserver -Dtest.methods="OTSServer_Test001" onetest

     

    >>> commands creates the distribution with 'idl' interfaces, creates the TaskImpl.properties while using JAVA_HOME to be set up and at the end runs a simple single test which should output "BUILD SUCCESFUL" to confirm the configuration was correct.

     

    The log files and results of the tests are stored

    • in files at /qa/TEST-<<name-of-test>> where you can observe output of the TestGroup*
    • the JVM Task(s) generates output under /qa/testoutput/<<test-group-name>>/<<test-name>>/*.txt

     

    runt-tests.xml

    The descriptor run-tests.xml contains targets to set of tests or just a single one.

     

    running a single test

    To run the single test the target is onetest. For running a single method from a testcase you will run similar to following

     

    ant -f run-tests.xml -Dtest.name=currenttests01 -Dtest.methods="CurrentTests01_Test001" onetest

     

    The parameter test.name defines the name of the Java file if it's prefixed with TestGroup. In this case, the name of the file is TestGroup_currenttests01. The test.methods parameter defines the name of the test which will be started.

     

    running with a hornetq/artemis object store

    The data could be stored in different types of object stores, those ones that Narayana supports - shadow file (a simple directory structured log), hornetq store (a append only storage log), jdbc store (jdbc connection to a database). For running the tests with hornetq storage it's needed to define profile -Dprofile=hornetq (profile is defined in run-tests.xml)

    If it's aim to use AIO version of hornetq storage it's needed to provide path to the AIO so file. The path is needed to be defined as the java.library.path for the Task execution. Thus the TaskImpl.properties needs to be updated with like

    COMMAND_LINE_14=-Djava.library.path=<dir_with_hornetq_so_file>

     

    jdbc drivers for db tests

    If you run a test which tests a communication to database you need to have defined the connection properties for the database and you need the jdbc driver for connection to be done. The jdbc driver is refered in the TaskImple.properties. You can download a jdbc driver you like and refer it there - I usually copy the driver under /qa/dbdrivers and refer it in TaskImple.properties by adding a new line under "COMMAND_LINE_2" with content similar to

     

    ${path.separator}dbdrivers${file.separator}ojdbc8.jar\

     

    Or if you don't want to download your own driver you can run ant task 'ant get.drivers' which downloads drivers (be aware they are old ones) and their location is already configured in the TaskImple.properties.

    ant get.drivers
    Buildfile: qa/build.xml

    clean-dbdrivers:
       [delete] Deleting directory qa/dbdrivers

    get.drivers:
        [mkdir] Created dir: qa/dbdrivers/oracle_10_2_0_4
          [get] Getting: http://www.qa.jboss.com/jdbc-drivers//ojdbc14.jar
          [get] To: a/dbdrivers/oracle_10_2_0_4/ojdbc14.jar
        [mkdir] Created dir: qa/dbdrivers/mssql2005_sqljdbc_2.0/enu
          ...
        [mkdir] Created dir: qa/dbdrivers/DB2_v9.7
          ...
        [mkdir] Created dir: qa/dbdrivers/jConnect-6_0/classes
          ...
    BUILD SUCCESSFUL
    Total time: 15 seconds

     

    running with jdbc log storage

    If expecting to run with jdbc log storage there is needed to configure the profile in dependency to which database is used. See run-tests.xml, for example -Dprofile=oracle. If it's configured that way then the properties are used as they're configured in the run-tests.xml. It's possible to change them just on the command line.

     

    # expecting jdbc driver is available (see above)
ant -f run-tests.xml -Dtest.name=jtsremote -Dtest.methods="JTSRemote_TimeoutTest" -Dprofile=oracle -Djdbc.db.url="localhost" -Djdbc.db.name=XE \
  -Djdbc.db.user=crashrec -Djdbc.db.password=crashrec -Djdbc.db.port=1521 onetest

     

    jdbc tests

    Some tests are expected to be run against the defined database. They are named as TestGroup_jdbcresources01_ibmdb2_jndi, TestGroup_jdbcresources01_oracle_thin_jndi and similarly.

    For them to run the database connection has to be configured. The Task takes configuration from qa/config/jdbc_profiles/<<hostname>>/JDBCProfiles.

    You need to provide connection properties for a particular database, based on the name of the test case, into the JDBCProfiles file which is stored under a directory named based on the hostname of the machine the test runs at. If such directory does not exist there are taken properties from directory default.

     

    (running the Oracle XE in docker could be done with fuzziebrain/docker-oracle-xe, my notes are added to README.md)

     

    debugging

    For running the tests in debug mode there is needed to add sysproperty or jvmarg under <junit> xml element in run-tests.xml.

     

    To run more messages

    <sysproperty key="qa.debug" value="true"/>

     

    To debug the Task JVM add the sysproperty. Each started JVM will obtain the debug address from 5000 and increasing by one

    <sysproperty key="tasks.remote.debug" value="true"/>

     

    Uncomment the debug property if needed to debug the test itself (TestGroup_*)

    <jvmarg value="-Xdebug"/>
    <jvmarg value="-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5007"/>