STP へのテストの移植方法

概要

Scalable Test Platform はユーザが新しいテストを簡単に追加できるように設計されています。ここでは新しいテストを追加する方法について説明します。STP テストは次の条件を満たしている必要があります。

自己完結

一般的な Linux/GNU/Unix ユーティリティ以外、テストに必要なすべてのコードはテストキット内で提供される必要があります。当文書でいくつかの例を示します。

完全自動

以下で説明するように、STP エンジンではテストキット内にドライバスクリプトが提供されている必要があります。テストはすべてこのドライバスクリプトで駆動されます。オペレータが介入することはできません。

法的要件

結果とテストコードは、OSDL が配布できるよう適切なオープンソースライセンスを適用する必要があります。使用許諾を得ていないコード、またはオープンソースライセンス以外のコードを提供しないでください。ライセンス問題に関するメーリングリストがあります。

テストは STP 固有のものである必要はありません。すべてのテストコードを歓迎いたします。

連絡手段と組織

はじめに、組織サイドの事柄について説明します。このセクションは OSDL の STP（www.osdl.org） にテストを提出する場合にのみあてはまります。独自の STP のローカルコピーを使用している場合は、このセクションは無視していただいて結構です。技術的な面については、以降のセクションで説明します。

STP の情報は次のメーリングリストを介して提供されます。

- 一般告知用のメーリングリスト

- テスト開発者向けの情報

これらのメーリングリストに参加する必要があります。新しいテストを提供する準備が整ったら、stp-tests 上で公表します。

STP テストコードは Sourceforge 上の CVS に保存されています（http://sourceforge.net/cvs/?group_id=35146）。STP テストのコピーを取得してサンプルとして使用することをお勧めします。モジュール名は「tests」で、このガイドで参照するサンプルテスト「exampletest」が準備されています。匿名コピーを取得する場合は Sourceforge の CVS の指示に従ってください。

重要事項 : 多くの場合、実際のテストコード（STP ラッパ以外）には、STP とは別に独自のホームがあります（STP CVS に収録されているのはコピーです）。たとえば、LMBench は BitMover によって保守が行なわれ、http://www.bitmover.com/lmbench/ で公開されています。OSDL データベーステストは、Sourceforge（ http://sourceforge.net/projects/osdldbt）で公開されています。 テストラッパではなくテスト本体を変更する場合は、テストコードの実際の所有者に連絡をとる必要があります。したがって、DBT-1 に対する変更は、STP ではなく、OSDL の DBT Sourceforge プロジェクトを介して行う必要があります。そうすると新しいバージョンのテストが STP 上で追加またはアップデートされます。テストにホームがない場合、STP バージョンがオフィシャルとなり、以降の更新は STP CVS で行なわれます（AIM テストがその例です。もう保守されていないようです）。全く新しいテストを作成している場合、そのテストコード専用のホーム（Sourceforge など）を用意しておくことをお勧めします。ホームが重複しても問題ありません。

OSDL リポジトリにテストを追加するには、次の 2 つの方法があります。

• CVS に対する書き込みアクセス権を取得します。電子メールを送信すると、権限が与えられます。Sourceforge は ssh を採用しているため、SSH キーをアップロードして簡単にアクセスできます。書き込みアクセス権を取得した場合、他の人との緊密な連絡が必要になります。Sourceforge で加えられた変更が自動的に OSDL ラボの STP 装置に採用されるわけではありません。STP の CVS アクセス権がある場合、変更の際に OSDL に通知していただければ、STP 装置への採用を働きかけます。
• 電子メールを送信いただければ、CVS の作業と OSDL への導入をこちらが代わりに行います。喜んでお受けいたします。すべてのプロジェクト管理者は喜んで対応し、お役に立てることをうれしく思います。テストの保守担当者になりたくはないがテストを追加したいという方には、お勧めの方法です。

今後について : 複数のバージョンのテストコードを保存でき、より柔軟性がある、テストの新しいレポジトリ方法に取り組んでいます。stp-devel メーリングリストへのご参加と計画へのご協力をお待ちしております。

テスト環境

テスト環境は非常にシンプルです。

• 各テストには独自のディレクトリがあります。例として CVS をご覧ください。ディレクトリにはテストの名前が付いています。ディレクトリごとに 1 つまたは一連のテストがあります。テストの提出方法にかかわらず、テストコードは .tar 形式でアーカイブ可能な 1 つの完結したディレクトリである必要があります。 実行時には、テストコードはテストマシン上のこのディレクトリに配置されます。CVS に対する書き込みアクセス権がある場合、CVS アップロードの一環としてこのディレクトリを作成します。
• すべてのパスは、テストコードディレクトリ（一般に「/root/テスト名」）からの相対パスで指定します。テストコードでは絶対パスは使用しません。
• 各テストにはドライバスクリプトがあり、このスクリプトの名前は「wrap.sh」でなければなりません。このスクリプトは shell、Perl、または Python で記述できます。
• このスクリプトが「results」ディレクトリを作成し、そこに結果を配置します。結果は STP エンジンによって自動的に回収されます。STP エンジンは「results」の中だけを見ます。
• スクリプトは結果を表示する「index.html」ファイルを用意するか作成する必要があります。この例として STP テスト結果をもう一度参照してください。サンプルスクリプトも参照してください。
• テストスクリプトは root ユーザによって実行されます。非 root ユーザはテストスクリプトによって作成される必要があります。- 非 root ユーザとしてコマンドを実行するには「su -c」を使用します。

手順

準備

はじめに、テストの実行に必要なものがすべて揃っていることを確認します。何を提供すべきかを判断するために、できればいくつかの異なるディストリビューションやインストールで確認してください。たとえば、テストが ReiserFS に依存している場合、あるバージョンの reiserfsprog を組み込み、wrap スクリプトでそれらのツールをビルドおよびインストールする必要があります（例として tiobench を参照してください）。あるいはまず reiserfsprogs の有無を調べ、次にバージョンをチェックし、それらが失敗した場合にはテストに同梱したバージョンをビルドするようにします。この種の依存性を持つテストの動作は、まず確認し、存在しない場合はメッセージを表示して停止する、あるいは必要なファイルを提供する、という流れになります。STP では「標準」 のディストリビューションをインストールするため、必要となる標準的なツールがすべて組み込まれているはずですが、不明な場合は確認のコードをテストに含めてください。

次に、テストを適切にセットアップするため何が必要かを決定します。多くの場合、テスト実行時に STP マシン上でソースを展開しテストコードをコンパイルする方法がとられます。こうするとテストを長期間使用でき、移植性も高まります。テストをあらかじめビルドした状態でインストールする方法もあります。

そして、テストの自動化に何が必要であるかを判断します。何を入力し、テストの実行前に何をセットアップし、どのようなリソースを必要としているのかを判断します。そしてテストが何を出力し、その出力がどのように取り込まれて解析されるのかを判断します。また、そのテストの実行方法を確認します。何をもって「正常」、「失敗」とするかの判断基準を明確にします。

最後に、すべての制約を文書化します。STP はシングル CPU から 8-way 以上のプラットフォームを提供しています。テストがすべてのプラットフォームに適しているとは限りません。

推奨される作業手順は次のとおりです。開発用ディレクトリを作成してテストコードを保存します。テストコードを .tar 形式アーカイブで保存します。各テストランの前に、開発用ディレクトリ内のファイルをすべて削除し、開発用マシンをリブートします。ディレクトリが空でマシンがブートしたての状態でテストを開始する習慣をつけます。そして STP エンジンが行う動作を実行します。.tar 形式アーカイブを展開して、「sh -x wrap.sh」を実行します。

開発用の設定を一定にするには、Makefile を使用します。

Makefile の例

        # This is so i can do multiple runs while developing
        DATE := $(shell /bin/date '+%d_%m_%H%M')
        results:
                mkdir run.${DATE}; cp results/* run.${DATE}

        clean:
                # remove the previous test 
                rm -rf dbt1 
                rm -f sapdb-server* 
                rm -f sapdb-web* 
                #clean config files 
                cat /etc/services | grep -v sql[6,30] > /tmp/foo 
                mv /tmp/foo /etc/services

        run:    wrap.sh
                # this is what STP will do 
                sh -x ./wrap.sh > run.output 2>&1

テストコード

例として、非常に簡単なテストを作成してみます。このテストの .tar 形式アーカイブは以下のようになります。

        $ tar tvf example.tar 
        drwxr-xr-x cliffw/staff      0 2002-10-25 09:14:56 example/ 
        -rw-r--r-- cliffw/staff    292 2002-10-25 09:12:59 example/Makefile 
        -rw-r--r-- cliffw/staff     26 2002-07-02 12:45:00 example/index_foot.html 
        -rw-r--r-- cliffw/staff    234 2002-07-02 12:44:38 example/index_head.html 
        -rwxr-xr-x cliffw/staff    179 2002-10-25 09:14:34 example/upt.sh 
        -rwxr-xr-x cliffw/staff    156 2002-10-25 09:14:18 example/cpu.sh 
        -rwxr-xr-x cliffw/staff    157 2002-10-25 09:14:25 example/mem.sh 

「テスト」は 3 つの shell スクリプトから成ります。make を使用してテストコードのビルドとインストールを行えるよう、Makefile を用意します。次に、テストを実行し、出力を取り込み、結果ページを作成します。

Makefile

        all:cpu mem upt 
        cpu:cpu.sh
                cp cpu.sh cpu; 
                rm -f cpu.sh 
                chmod 755 cpu

        mem:mem.sh
                cp mem.sh mem; 
                rm -f mem.sh 
                chmod 755 mem

        upt:upt.sh
                cp upt.sh upt; 
                rm -f upt.sh 
                chmod 755 upt

念のため実行権限を設定している点に注意してください。テストパッケージには結果ページ用の定型 html が含まれています（index_head.html と index_foot.html）。

Wrap.sh スクリプト

簡単な wrap.sh を分析してどのように行っているか示します。実際のスクリプトは CVS の exampletest ディレクトリにあります。

 
#!/bin/sh 
#
# wrap.sh:for dummy workload 
# Copyleft 2002 Cliff White  
#
#   This program is free software; you can redistribute it and/or modify 
#   it under the terms of the GNU General Public License as published by 
#   the Free Software Foundation; either version 2 of the License, or 
#   (at your option) any later version.
# [ rest removed ] 

ライセンス表示を常に含めるようにします。

        echo "This is a dummy test for the STP " 
        VERSION=0.0.1 
        echo "$0 version $VERSION"
# The STP engine captures standard out and standard error from your
# test script and stores it in a log file.Make sure your log file is
# informative 

        MYHOME=`pwd` 
        RESDIR='./results'
#We establish two environment variables.$MYHOME
#will be used for all relative paths.  

        echo "Cleaning up the environment" 
        if [ -d $RESDIR ]; then
                rm -rf $RESDIR
        fi 
        mkdir $RESDIR

        if [ -d $RESDIR ]; then
                echo "Directory created!"
        else
                echo "Error - no results directory"
        fi

# Create the output directory, using the Paranoid Method.(check before, 
# act, check after) 
# Now we'll do the test setup section: 
# unpack the test 
        tar xvf ./example.tar

# go to our test directory and
# check for success 
        cd example 
        if [ -f ./cpu.sh ]; then
                echo "Tarball successfully unpacked"
        else
                echo "Tarball failed to unpack" 
                exit 1
        fi

# build the test 
        make

# Test for build success 
        if [ -f ./cpu ]; then
                echo "Make succeeded"
        else
                echo "Make failed" 
                exit 1
        fi

これは標準的な手順です。再度、正常に行われたことを確認し、 失敗した場合にはエラーを報告します。ここで、テストを実行します。

        echo "Starting tests" 
# be sure to capture raw data for your results 
        ./cpu > ../results/cpu.r 
        ./mem > ../results/mem.r 
        ./upt > ../results/upt.r

結果の処理

まず、テスト提出者にテストログが電子メールで通知されます。テストがシンプルな場合、重要な結果を標準出力するとともに、 結果ファイルにも保存してください。これにより、十分な情報が電子メールでユーザに送信されるので、ウェブサイト上の結果を検索する必要がなくなります。

ウェブサイト用に index.html を作成する必要があります。そのページにはテスト結果を表示するロジックがなければなりません。 有益で、専門家以外の人にも役に立つページを作成するようにしてください。 結果は各種フォーマットで提供することをお勧めします。テキストや、 スプレッドシートへインポートできるコンマ区切り（CSV）フォーマット、あるいは解釈が容易であればバイナリでもいいでしょう。 次のように行います。

 
# I use some boilerplate to start 
cat ./example/index_head.html > ./index.html 
echo "

" >> ./index.html 
cat ./results/mem.r >> ./index.html 
echo "

" >> ./index.html 
cat ./example/index_foot.html >> ./index.html 

これが最も簡単な方法でしょう。

STP では、テストランの一環として自動的に一部のシステム設定情報を提供します。 「environment」および「environment/machine_info」ディレクトリにマシン設定が保存されます。 次の 3 行を index.html に追加します （これらは、サンプル footer.html の一部です）。

 
<a href="environment/machine_info">Summary Information on Machine</a> 
<a href="environment/">System Environment Documentation</a>
<a href="COPYING">Results Copyright License</a> 

堅牢なテストのビルド

このセクションは問題がいくつか発生した後に追加されました。テストは常に何らかの結果をウェブページのフォームに返す必要があります。たとえ「Your test died 00 minutes 03 seconds after the start of the run（テストは実行開始後 00 分 03 秒後に停止しました）」という結果であっても、結果が返されている限りテストは堅牢だと言えます。

次に、堅牢なテストを作成するために現在行われていることを示します。 他のことを行う前に、wrap.sh は次の 2 つのスクリプトをバックグラウンドで開始します。

timeout.sh - このスクリプトは他の方法では検出できないタイムアウト状態を検出します。このスクリプトは

長時間スリープ状態に入ります（3 時間）

スリープから復帰すると、テストが実行中か調べます

テストが停止している場合、データの復旧を試みます（blowup.sh を参照）

エラー番号 1 で exit します

STP エンジンが（最終的に）システムをリブートします。正常なテストでは、timeout.sh は通常のリブートにより強制終了されます。

safety.sh - このスクリプトは、テストが予期せず停止した場合にデータを復旧し、

results ディレクトリに index.html ページを作成します。このページには、通常「Your test died unexpectedly...（テストは異常終了しました）」と表示され、データへのリンクが掲載されます。

/var/log/messages の最後の 200 行を上記の index ページ上の ./results リンクにコピーします（原因となるデータを捕捉するため。行数はこれ以上必要かもしれません）。

10 分間スリープ状態になります

スリープから復帰すると、テストが実行中か調べます

テストが実行中の場合、syslog のコピーを取り直し、またスリープ状態に入ります

テストが実行中でない場合は、データ回復を試みます

エラー番号 1 で exit します

テストが正常に終了した場合、このスクリプトは通常、結果が処理される前に wrap.sh によって強制終了されます。

テストが失敗した時に原因特定データを回収するためのスクリプトを作成する必要があります。ここではそのスクリプト「blowup.sh」とします。致命的なエラーが検出された場合、wrap.sh は exit() を呼び出す前に blowup.sh を呼び出します。

このスクリプトは次のことを行います。

safety.sh を強制終了します

既存のアプリケーション / テスト固有のデータをすべて取り込みます 例 : SAPDB の knldiag ファイル

参考となるシステムデータを取り込みます （/var/log/messages や dmesg など）

STP エンジンが回収できるよう ./results ディレクトリへデータをすべてコピーします

上記のすべてのファイルにリンクを張ったウェブページ（index.html）をビルドします

エラー番号 1 で exit します

その他の例

ディスクマウント

STP は「disk.info」ファイルにディスク情報を保存しています。 STP のこの部分はまもなく改善される予定です。

       #/dev/hdb,/mnt/hdb,65000,0,4,D /dev/sda,/mnt/sda,68369,0,4,D
        /dev/sdb,/mnt/sdb,68369,0,4,D /dev/sdc,/mnt/sdc,85461,0,4,D 

現在のところ、このファイルの最初のフィールドのみが有効です。 このファイルはテストディレクトリより上のディレクトリにあるため、テストスクリプトは「../disk.info」としてこのファイルにアクセスできます。 現在、デバイスのマウントを簡単に行えるいくつかのスクリプトツールを開発中です。 現時点では、見本となる方式が 2 つあります。

DBT1-1tier テストは Perl スクリプト「mp_crt.pl」を使用しています。 このスクリプトは disk.info ファイルおよび mount.info ファイルを読み取ります（CVS 中の dbt1-1tier ディレクトリを参照してください）。 「tiobench」テストはスクリプトのペア「getmountinfo.sh」および「putmountinfo.sh」を使用します。

私たちはこのためのよりよいツールの開発に取り組んでいます。ニュースグループへのご参加と開発へのご協力をお待ちしております。