<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/tutorial/how-to-run-jdo-unit-tests.xml">
  <properties>
    <title>How to run Castor JDO's performance tests</title>
    <abstract>
       General information about running Castor JDO's performance tests
    </abstract>
    <status>Final</status>
  </properties>
  <body>
    <title>How to run Castor JDO's performance tests</title>
    <header>
    </header>
    
	<section title="Overview">
      <p>At the time of this writing Castor JDO has 3 kinds of test suites:</p>
      
      <ul>
        <li>Database independend plan unit tests.</li>
        <li>A JUnit based test suite that is used to test various functional areas against different
          database engines to give developers/committers some reassurance when changing the codebase.</li>
        <li>A Junit based test suite to evaluate impact of changes on performance.</li>
      </ul>
      
      <p>This document provides general information about running Castor JDO's performance tests.</p>
    </section>
    
    <section title="Prerequisites">
      <p>See: <a href="how-to-setup-castor-project-in-eclipse.html">How to setup Castor project in eclipse</a></p>
    </section>

    <section title="Steps to setup environment for old CTF">
      <p>To execute performance tests against mysql database you probably need access to a mysql server. To create a
        database for PTF, you have to execute the following commands on mysql consol.</p>
        
      <code-panel>
# create database cpaptf;
# grant all on cpaptf.* at "localhost" to "test" identified by "test";
# use cpaptf;
# source [path-to-script];</code-panel>

      <p>If the server is not installed on your local maschine (the one you execute the tests on) you have to replace
        "localhost" with the IP of the maschine the tests get executed on. The script to execute is
        "cpaptf/src/test/ddl/mysql.sql".</p>

      <p>As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use
        to your classpath to execute the tests. The easiest way is to copy the driver to "lib/" directory as all jar's
        contained therein are added automatically.</p>

      <p>For mysql we still use "mysql-connector-java-3.1.13-bin", also for mysql server of version 5. This version has proven
        to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.</p>
    </section>

    <section title="Steps to execute performance tests in eclipse">
      <p>Execution of the performance test suite from within eclipse is very simple.</p>
        
      <ul>
        <li>Select "cpaptf/src/test/java" -> "org.castor.cpaptf" -> "TestAll.java" and right click</li>
        <li>Select "Run As" -> "JUnit Test"</li>
      </ul>
      
      <p>By defeult the test uses 2000 service objects that get created, loaded with various configurations and deleted
        afterwords. Obviously this will take quite some time. Please be patient for normal termination of the tests as
        you will need to clean test tables by hand otherwise. To execute tests with a different number of objects you
        can adjust "FACTOR" constant in "TestCreate.java". For example, if you set "Factor" to 1.0 the tests will be
        executed with 10000 service objects. When using more test objects be aware that you may need to increase heap size
        of the virtual maschine for the test to finish.</p>
      
      <p>By default you won't see any output of results on the consol as logging level of log4j is set to "warn" by default.
        But if you change log level of "org.castor.cpaptf" package to "info" you will see detailed execution times for every
        test on the consol. Be aware that there are quite some log4j.xml configurations in the whole Castor project at the
        moment of which the one first one on classpath will be used.</p>
        
      <p>If you like to review some older test results you will find them under "cpaptf/src/site/resources/results/" but they
        depend heavy on the machine you are running the tests on.</p>
    </section>
    
    <section title="References">
      <ul>
        <li><a href="how-to-setup-castor-project-in-eclipse.html">How to setup Castor project in eclipse</a></li>
      </ul>
    </section>
  </body>
</document>