You need to have a good understanding of Ant before reading this tutorial. If you don't, I suggest you read the Ant User Manual first.

このチュートリアルを読む前に Ant についての深い知識が必要です。 そうでない場合、Ant ユーザーマニュアルをあらかじめ読まれる事をお勧めします。

This tutorial explains how start Cactus tests from your Ant build script (i.e. build.xml).

本チュートリアルでは、自分の Ant ビルドファイル (即ちbuild.xml)から、 どのように Cactus テストを起動するのかについて説明します。

The Ant tasks involved for running a Cactus test are the following :

Cactus テストの実行するようにする Ant の作業手順は次の通りです :

• Step 0 : (optional) Deploy configuration files for your container,
• ステップ 0 : (オプション) 自分のコンテナに設定ファイルを配備します。
• Step 1 : Package your Cactus tests as a WAR file and deploy it to your servlet engine webapps directory,
• ステップ 1 : 自分の Cactus テストを WAR ファイルとしてパッケージ化し、 サーブレットエンジンの webapps ディレクトリに配備します。
• Step 2 : Start your servlet engine if it is not already started,
• ステップ 2 : まだ起動されていない場合、サーブレットエンジンを起動します。
• Step 3 : Run the tests using JUnit,
• ステップ 3 : JUnit を使ってテストを実行します
• Step 4 : Stop the servlet engine (if need be)
• ステップ 4 : (必要であれば)サーブレットエンジンを停止します

Cactus provides a custom Ant task (called the runservertests task) that helps perform all these tasks. The rest of this tutorial will explain how to write an Ant build file (build.xml) that performs these tasks and use the Cactus custom Ant task.

Cactus では、これらのタスクを実行するのを助けるカスタムタスク (runservertestsタスクと呼んでいます)を提供しています。 このチュートリアルの残り部分では、 これらのタスクを行う Ant ビルドファイル (build.xml)の書き方、 Cactus カスタム Ant タスクの使い方について説明します。

During the remainder of this tutorial we will show examples for Tomcat 4.0. However, the principle can be applied to any other container. Ant Scripts for other containers can be found in the /sample/build directory where you have unpacked the Cactus distribution.

このチュートリアルの残り部分で、 Tomcat 4.0 の例を示しますが、 原理的には他のコンテナについても当てはまります。 他のコンテナ用の Ant ビルドファイルは、 Cactus ディストリビューションを解凍した、 /sample/build ディレクトリにあります。

This task will perform several actions, in the following order :

このタスクは幾つかのアクションを次に示す順序で実行します :

• Check if a server is already started by constantly trying to call the test URL defined by the testURL attribute (see the example below),
• testURL 属性で定義された test URL を継続的に呼びつづけることにより、 サーバーが既に起動されているかチェックします。 (下の例をご覧ください)
• If a server is not started, call the Ant target defined by the startTarget attribute (see the example below). This target is supposed to start your container. The runservertests task will then constantly poll the server by calling the test URL until the server answers back,
• サーバーが起動されていない場合、 startTarget 属性により定義された Ant ターゲットを呼び出します。 (下の例を参照) このターゲットは、コンテナを起動するためのものです。 次に、runservertests タスクは、 server からのレスポンスがあるまで test URL を呼び出すことにより、 サーバーをポーリングし続けます。
• It will then call the Ant target defined by the testTarget attribute (see the example below). This target is supposed to start the unit tests. This is usually implemented by using the Ant junit task,
• そして、testTarget 属性により定義された Ant ターゲットを呼び出します。(下の例を参照) このターゲットは単体テストを起動するためのものです。 これは通常 Ant junit タスクを使って実装されています。
• Once the tests are finished (i.e. when the testTarget has finished executing), it will then call the Ant target defined by the stopTarget attribute (see the example below). This target is supposed to stop the container. The runservertests task will then constantly poll the server by calling the test URL until the server stops answering, at which point it will consider the server to be stopped. Note that the stopTarget will only get called if the server was not already started when the runservertests task began executing. This is to allow keeping running servers for intensive debugging phases.
• テストが終了したら(即ち、testTarget が実行終了したら)、stopTarget 属性により定義されている Ant ターゲットを呼び出します。(下の例を参照) このターゲットはコンテナを停止させるためのものです。 runservertests タスクは、 その時点でサーバーが停止したと見なせる、 サーバーのレスポンスがなくなるまで、 test URL を呼び出すことによりサーバーをポーリングし続けます。 stopTarget は、 runservertests タスクが実行し始めた時点で、 サーバーが既に起動されていなかった場合にのみ呼び出されることに注意してください。 何回も続けてデバッグフェーズを行うために、 これは、サーバーを起動したままにしておくためのものです。

The runservertests task is generic in the sense that you are free to implement the startTarget, testTarget and stopTarget as you wish and they will get called at the right time.

runservertests タスクは、 開発者が自由に、好きなようにstartTarget、 testTarget、stopTargetを実装でき、 定められた時に呼び出されるという意味において一般形なものと言えます。

Example :

例 :

<!--
   ========================================================================
     Run Tomcat 4.0 tests
   ========================================================================
-->
<target name="test.tomcat.40" depends="prepare.test.tomcat.40"
    if="tomcat.home.40" description="Run tests on Tomcat 4.0">

    <!-- Start the servlet engine, wait for it to be started, run the
         unit tests, stop the servlet engine, wait for it to be stopped.
         The servlet engine is stopped if the tests fail for any reason -->

    <runservertests
        testURL="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST"
        startTarget="start.tomcat.40"
        stopTarget="stop.tomcat.40"
        testTarget="test"/>

</target>

<!--
   ========================================================================
     Tomcat 4.0 テストの実行
   ========================================================================
-->
<target name="test.tomcat.40" depends="prepare.test.tomcat.40"
    if="tomcat.home.40" description="Tomcat 4.0でのテスト実行">

    <!-- サーブレットエンジンを起動し、正しく起動されるまで待ち、
	単体テストを実行し、サーブレットエンジンを停止し、
	正しく停止されるまで待ちます。
	何らかの理由でテストが失敗した場合、サーブレットエンジンは停止します -->

    <runservertests
        testURL="http://localhost:${test.port}/test/ServletRedirector?Cactus_Service=RUN_TEST"
        startTarget="start.tomcat.40"
        stopTarget="stop.tomcat.40"
        testTarget="test"/>

</target>

Before you can execute the runservertests task, you need to define it for Ant as it is not a standard Ant task. A good place to do this is in an init target.

runservertests タスクを実行する前に、 標準 Ant タスクでないようなタスクを定義する必要があるとします。 これを行う良い場所は、init ターゲットです。

Example :

例 :

<!--
   ======================================================================
     Initialize the build. Must be called by all targets
   ======================================================================
-->
<target name="init">
    [...]
    <taskdef name="runservertests" classname="org.apache.cactus.ant.RunServerTestsTask">
        <classpath>
            <pathelement location="${cactus.ant.jar}"/>
        </classpath>
    </taskdef>
    [...]
</target>

<!--
   ======================================================================
     ビルドの初期化。全てのターゲットにより呼び出されます
   ======================================================================
-->
<target name="init">
    [...]
    <taskdef name="runservertests" classname="org.apache.cactus.ant.RunServerTestsTask">
        <classpath>
            <pathelement location="${cactus.ant.jar}"/>
        </classpath>
    </taskdef>
    [...]
</target>

where ${cactus.ant.jar} is an Ant property that points to the cactus-ant.jar file found in the lib/ directory where you unpacked the Cactus distribution.

ここで ${cactus.ant.jar} は、 Cactus ディストリビューションを解凍した lib/ ディレクトリにある cactus-ant.jar ファイルを参照している Ant のプロパティです。

The prepare.test.tomcat.40 target is described in Step 0 below.

prepare.test.tomcat.40 ターゲットは下のステップ 0 で述べられています。

The tomcat.home.40 is simply an Ant property that points to the directory where Tomcat 4.0 has been installed. If this property is not defined we don't run the tests.

tomcat.home.40 は単に、 Tomcat 4.0 がインストールされたディレクトリを参照 Ant のプロパティです。 このプロパティが定義されていない場合、 テストを実行しません。

There are 2 possibilities for configuring your application server :

アプリケーションサーバーの設定には 2 つの方法があります :

1. You install it somewhere on your computer (or on another machine) and you deploy your test WAR (see Step 1 below) by copying it to the right subdirectory within it. Your WAR will then be placed alongside with others and your webapp will use the configuration files common to all webapps,
2. サーバーを自分のマシン(あるいは他のマシン)のどこかにインストールして、 (その正しいサブディレクトリに自分のテスト用 WAR を配備します。 (下のステップ 1 を参照) 自分の WAR は他の WAR と共に置かれ、自分のウェブアプリケーションが、 全てのウェブアプリケーションに共通な設定ファイルを使います。
3. Or, you can create your own set of container configuration files, hosted within your project, that you copy to your own deployment subdirectory (i.e. not shared).
4. あるいは、 テスト用の配備用の(即ち共有されていない)サブディレクトリにコピーするよう、 自分のプロジェクトに、 テスト用のコンテナ設定ファイルのセットを作成します。

In the provided Cactus Ant scripts, we have decided to follow approach 2 for the following reasons :

与えられた Cactus の Ant ビルドファイルでは、 次に示す理由により、上述の 2 番目の方法を採用しました :

• We keep the control of our project files as they are deployed within the directory of our project and thus it is easy to perform a clean of all generated files,
• 生成されたファイルのクリーンが簡単に実行できるように、 プロジェクトのファイルは、自分のプロジェクトのディレクトリに配備されるよう、 制御し続けたいです。
• We do not "pollute" the installed container by dropping files within it and we do not need to modify global configuration files that may prevent other applications we are developing from not running someday (because we would have made an incompatible change),
• 余計なファイルを入れることにより、インストールされているコンテナを 汚染したくありませんし、 我々が開発している他のアプリケーションが、 いつの日か動かなくなるのを避けるため、 全体の設定ファイルを変更する必要が無いからです。 (何故なら、我々は互換性の無い変更をしようとしていたかもしれないのです。)
• We completely control our needed container configuration.
• 必要なコンテナの設定を完全に操作します。
• We can guarantee to the user who wants to try the Cactus sample application that it will not deploy anything outside the scope of the Sample directory. Unlike windows applications that you install and that copies tens of DLL to shared directory, overwrite existing files, ... :(
• Cactus サンプルアプリケーションを試したいユーザーに対して、 サンプルディレクトリの範囲外には何も配備しない事を保障できます。 インストールして、何十ものDLLを共有ディレクトリコピーして、 既存のファイルを置き換えてしまう、、、と、いった Windows アプリケーションのようにはしたくないのです :(

However, this may not be the best approach for all cases, as :

しかしながら、これは全ての場合に対する最適な方法とは言えません、なぜなら :

• It is more difficult to set up as you need to understand how your container is configured (However, we have already done the job for you for most of the existing containers),
• 自分のコンテナがどのように設定されているか理解しなければならず、 インストールがより難しくなります。 (でも、我々は既に、ほとんどの既存のコンテナに対して対応しています。)
• You have only a single application to run and test and have dedicated your application server installation for it so you don't care about putting files in there and modifying global configuration,
• 開発者は、実行およびテストすべきアプリケーションが、 たった一つしかなく、それだけのために、 アプリケーションサーバーをインストールするつもりであり、 そこに一緒にファイルを置いてしまったり、 全体の設定を変更しても構わない場合。
• You want to be able to deploy in production several webapps that share the same server and thus must coexist and share common configuration files.
• 同じサーバーを共有する幾つかの ウェブアプリケーション製品を配備できるようにしたいと考えているので、 共通の設定ファイルを共存および共有させなければならない場合。

If you choose solution 1, then you can simply skip this step. The only actions to perform will be, for some containers, to edit their configuration files to tell them about your webapp (some will automatically pick you test WAR if you drop it in the correct directory).

解決策の 1 を選んだ場合、 このステップは単に飛ばしてしまうことができます。 幾つかのコンテナの場合、 行わなければならないことは、 自分のウェブアプリケーションの事をコンテナに知らせるために、 設定ファイルを編集することです。 (自分のテスト WAR を正しいディレクトリに置けば、 自動的に認識するものもあります。)

Example :

例 :

<!--
   ========================================================================
     Prepare directories and variables for running the tests
   ========================================================================
-->
<target name="prepare.test.tomcat.40"
    depends="check.test.tomcat.40,testwar" if="tomcat.home.40">

    <echo message="tomcat.home.40 = ${tomcat.home.40}"/>

    <property name="target.tomcat40.dir"
        value="${target.test.dir}/tomcat40"/>
    <property name="conf.tomcat40.dir" value="${conf.test.dir}/tomcat40"/>

    <!-- Create work and conf directories and copy configuration files -->
    <mkdir dir="${target.tomcat40.dir}/conf"/>
    <mkdir dir="${target.tomcat40.dir}/work"/>
    <mkdir dir="${target.tomcat40.dir}/webapps"/>

    <!-- Delete some config file so that they will be copied every time -->
    <delete file="${target.tomcat40.dir}/conf/server.xml"/>

    <!-- Remove the auto deployed webapp so that it is redeployed every
         time -->
    <delete dir="${target.tomcat40.dir}/webapps/test"/>

    <copy todir="${target.tomcat40.dir}/conf" filtering="on">
        <fileset dir="${conf.tomcat40.dir}"/>
    </copy>

    <!-- Copy the Tomcat web.xml -->
    <copy file="${tomcat.home.40}/conf/web.xml"
        todir="${target.tomcat40.dir}/conf"/>

    <!-- Copy the war file -->
    <copy file="${target.test.dir}/test.war"
        tofile="${target.tomcat40.dir}/webapps/test.war"/>

</target>

<!--
   ========================================================================
     テスト実行のためのディレクトリと変数の準備
   ========================================================================
-->
<target name="prepare.test.tomcat.40"
    depends="check.test.tomcat.40,testwar" if="tomcat.home.40">

    <echo message="tomcat.home.40 = ${tomcat.home.40}"/>

    <property name="target.tomcat40.dir"
        value="${target.test.dir}/tomcat40"/>
    <property name="conf.tomcat40.dir" value="${conf.test.dir}/tomcat40"/>

    <!-- work, conf ディレクトリの生成、設定ファイルのコピー -->
    <mkdir dir="${target.tomcat40.dir}/conf"/>
    <mkdir dir="${target.tomcat40.dir}/work"/>
    <mkdir dir="${target.tomcat40.dir}/webapps"/>

    <!-- 何時でもコピーされるよう、設定ファイルの削除 -->
    <delete file="${target.tomcat40.dir}/conf/server.xml"/>

    <!-- 何時でも再配備できるよう自動配備webappの削除 -->
    <delete dir="${target.tomcat40.dir}/webapps/test"/>

    <copy todir="${target.tomcat40.dir}/conf" filtering="on">
        <fileset dir="${conf.tomcat40.dir}"/>
    </copy>

    <!-- Tomcat の web.xml のコピー -->
    <copy file="${tomcat.home.40}/conf/web.xml"
        todir="${target.tomcat40.dir}/conf"/>

    <!-- war ファイルのコピー -->
    <copy file="${target.test.dir}/test.war"
        tofile="${target.tomcat40.dir}/webapps/test.war"/>

</target>

The ${target.test.dir} Ant property needs to be defined prior to calling this target and needs to be set to the location where the tests will be deployed. It should be set to any subdirectory of your output directory. This property will also be used later on in step 1 to copy the test WAR file.

Ant のプロパティ ${conf.test.dir} は、 このターゲットが呼ばれる前に定義され、 サーバー設定の場所を表す必要があります。 (Tomcat 4.0 の現在の例では、 これらは、web.xmlとserver.xmlです。)

Creating a WAR file is the preferred way of deploying Cactus tests to your servlet engine. Check the Getting Started guide and the example below for details on what files to include in the WAR.

WAR ファイルを作成するのは、 サーブレットエンジンに Cactus テストを配備する推奨される方法です。 どのファイルを WAR に入れるかについての詳細は、 Getting Started ガイド、 および、下の例をご覧ください。

Example :

例 :

<!--
   ========================================================================
     Create a Cactus test war file for the sample application.
   ========================================================================
-->
<target name="testwar" depends="compile">

    <!-- Create the war file -->
    <war warfile="${target.test.dir}/test.war"
         webxml="${conf.test.dir}/web.xml">

        <classes dir="${target.classes.sample.dir}"/>
        <classes dir="${target.classes.unit.dir}"/>

        <!-- log_server.properties need to be in the server classpath -->
        <classes dir="${conf.test.dir}">
            <include name="log_server.properties"/>
            <include name="cactus.properties"/>
        </classes>

        <lib dir="${target.lib.dir}"/>
        <fileset dir="${web.dir}"/>
   </war>

</target>

<!--
   ========================================================================
     サンプルアプリケーション用の Cactus WAR ファイルの生成
   ========================================================================
-->
<target name="testwar" depends="compile">

    <!-- WAR ファイルの生成 -->
    <war warfile="${target.test.dir}/test.war"
         webxml="${conf.test.dir}/web.xml">

        <classes dir="${target.classes.sample.dir}"/>
        <classes dir="${target.classes.unit.dir}"/>

        <!-- log_server.properties をサーバーのクラスパスに
	     入れる必要があります -->
        <classes dir="${conf.test.dir}">
            <include name="log_server.properties"/>
            <include name="cactus.properties"/>
        </classes>

        <lib dir="${target.lib.dir}"/>
        <fileset dir="${web.dir}"/>
   </war>

</target>

where :

ここで、各変数の意味は :

• ${conf.test.dir} : directory containing configuration files for the test,
• ${conf.test.dir} : テスト用の設定ファイルの入っているディレクトリ
• ${target.classes.*.dir} : directory where the java classes have been compiled. These are the classes under test + the test classes,
• ${target.classes.*.dir} : java クラスがコンパイルされたディレクトリ。 test にクラスがあり、テストクラスがあります。
• ${target.lib.dir} : directory containing the needed jars (junit.jar, cactus.jar, ...).
• ${target.lib.dir} : 必要な jar (junit.jar, cactus.jar, ...) のあるディレクトリ
• ${web.dir} : directory containing the web files to include in the test webapp (JSPs, HTML, ...).
• ${web.dir} : test ウェブアプリケーションに入れるウェブファイル(JSPs, HTML, ...) のあるディレクトリ

The compile target is used to compile all java classes into the ${target.classes.*.dir} directory.

compile ターゲットは 全 java クラスをコンパイルして、 ${target.classes.*.dir} ディレクトリに置くのに使われます。

Example :

例 :

<!--
   ========================================================================
     Start Tomcat 4.0
   ========================================================================
-->
<target name="start.tomcat.40">

    <java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
        <jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
        <jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
        <arg value="start"/>
        <classpath>
          <fileset dir="${tomcat.home.40}">
              <include name="bin/bootstrap.jar"/>
          </fileset>
        </classpath>
    </java>

</target>

<!--
   ========================================================================
     Tomcat 4.0 の起動
   ========================================================================
-->
<target name="start.tomcat.40">

    <java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
        <jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
        <jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
        <arg value="start"/>
        <classpath>
          <fileset dir="${tomcat.home.40}">
              <include name="bin/bootstrap.jar"/>
          </fileset>
        </classpath>
    </java>

</target>

We start the unit test by calling a JUnit test runner (we use the text runner in this example). Example :

JUnit test runner を呼び出すことにより、 単体テストを起動します。 (この例では test runner を使います) We start the unit test by calling a JUnit test runner (we use the text runner in this example). 例は次の通りです :

<!--
   ========================================================================
     Run the client JUnit test cases.
   ========================================================================
-->
<target name="test">

    <junit printsummary="yes" haltonfailure="yes" haltonerror="yes"
        fork="yes">

        <classpath>
            <!-- Cactus.propertie and log_client.properties need to be in
                 the classpath -->
            <pathelement location="${target.conf.dir}"/>
            <pathelement location="${target.classes.sample.dir}"/>
            <pathelement location="${target.classes.unit.dir}"/>
            <path refid="project.class.path"/>
        </classpath>

        <formatter type="plain" usefile="false"/>
        <test name="org.apache.cactus.unit.TestAll"/>
        <test name="org.apache.cactus.sample.TestAll"/>

    </junit>

</target>

<!--
   ========================================================================
     クライアント側 JUnit テストケースの実行
   ========================================================================
-->
<target name="test">

    <junit printsummary="yes" haltonfailure="yes" haltonerror="yes"
        fork="yes">

        <classpath>
            <!-- Cactus.propertie および log_client.properties を
		 クラスパスに含める必要があります -->
            <pathelement location="${target.conf.dir}"/>
            <pathelement location="${target.classes.sample.dir}"/>
            <pathelement location="${target.classes.unit.dir}"/>
            <path refid="project.class.path"/>
        </classpath>

        <formatter type="plain" usefile="false"/>
        <test name="org.apache.cactus.unit.TestAll"/>
        <test name="org.apache.cactus.sample.TestAll"/>

    </junit>

</target>

The list of jars to include in your classpath is explained and detailed in the Classpath Howto guide.

自分のクラスパスに入れる jar のリストは、 Classpath Howto ガイドで詳しく述べられています。

Example :

例 :

<!--
   ========================================================================
     Stop Tomcat 4.0
   ========================================================================
-->
<target name="stop.tomcat.40">

    <java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
        <jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
        <jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
        <arg value="stop"/>
        <classpath>
          <fileset dir="${tomcat.home.40}">
              <include name="bin/bootstrap.jar"/>
          </fileset>
        </classpath>
    </java>

</target>

<!--
   ========================================================================
     Tomcat 4.0 の停止
   ========================================================================
-->
<target name="stop.tomcat.40">

    <java classname="org.apache.catalina.startup.Bootstrap" fork="yes">
        <jvmarg value="-Dcatalina.home=${tomcat.home.40}"/>
        <jvmarg value="-Dcatalina.base=${target.tomcat40.dir}"/>
        <arg value="stop"/>
        <classpath>
          <fileset dir="${tomcat.home.40}">
              <include name="bin/bootstrap.jar"/>
          </fileset>
        </classpath>
    </java>

</target>