yamachan's Ajax lab

proto-webtools

proto-webtools は Prototype ベースのWeb用Ajaxツールキットです。

移動可能なカレンダー
ソート可能な表
展開可能なセクション
マウスに反応する画像

などのWeb部品を簡単に利用することができるようになります。

【200/08/29 現在、ドキュメント整備中...。】

proto-webtools

proto-webtools は Prototype ベースのWeb用Ajaxツールキットです。ライセンスはすべて "3-clause BSD license"　です。

Test ツール

Test ツール (jp.rinco.test) はテスト・ファーストを実現する JavaScript ライブラリです。 1つの html ファイルに仕様とともにテストケースを記述し、それをそのまま実行する仕組みになっています。取り扱いが簡単でシンプルなツールです。

proto-webtools 作成のために開発されました。前提となるライブラリは Prototype だけです。詳細はこちら。

Core ライブラリ

Core ライブラリは proto-webtools の基本ライブラリです。 JavaScript/Prototype のオブジェクトの拡張や、便利関数の追加など、小規模なコードの集まりです。

あったらいいな、という機能が実装されていますので、Prototype の拡張として、使ってみてください。必要な機能だけ、コピペで利用するのもOKです。前提となるライブラリは Prototype だけです。詳細はこちら。

UI ライブラリ

Simple ツール

Game ライブラリ

【200/08/29 現在、ドキュメント整備中...。】

過去の blog はこちら

yamachan 日々のメモ

yamachan GAME メモ

yamachan Ajax/.NET/C# メモ

yamachan's Notes/Domino メモ

proto-webtools Test ツールについて

proto-webtools Test ツール (jp.rinco.test) はテスト・ファースト(Test first) を実現する JavaScript ライブラリです。

特徴

テスト・ファーストは非常に重要な考え方だとおもいます。僕自身、開発スタイルに大きな、良い影響がありました。そこでもっと活用するため、実際のテストコードとテスト仕様書がきちんと連動できないか？と考え始めました。 Java Doc の「Java コードから仕様書が自動生成」する感じをテストケースにも取り入れたかったのです。

実装としては、テストケースを htmlで記述するようにしてみました。仕様ページに書かれたサンプルコードを、そのまま実行してしまおうというアイデアです。適用できる範囲は限られますが、JsUnit より簡単に利用できるとおもいます。

以下のような特徴があります。

htmlの知識があればテストケースを作成できます
テストケースがそのまま機能ドキュメントとして公開できます
様々な環境でテストするのが簡単です
- ユーザーにテストページを開いてもらい、エラーが出てないか見てもらえばOK

proto-webtools の開発に実際に利用しています。 proto-webtools Core テストページなど参照してみてください。

前提条件とライセンス

proto-webtools Test ツール実行には Prototype v1.6 以降が必要です。

proto-webtools Core/UI ツールは必須ではありません。無くても動作します。ただしその場合は、一部の拡張機能が動作しませんので、一緒に使用するのがお勧めです。

proto-webtools ツールのライセンスは "3-clause BSD license"　となっています。ご自由にお使いください。ダウンロード用のリンクはこのページの最後にあります。

利用例1 簡単な例

以下は Math.max() 関数の動作を確認するサンプルです。そのまま html として保存していただければ、動作の確認ができるはずです。

<html><head>
<link type="text/css" rel="stylesheet" href="http://rinco.jp/js/jp-rinco-test.css"></link>
<script type="text/javascript" src="http://rinco.jp/js/prototype.js" charset="utf-8"></script>
<script type="text/javascript" src="http://rinco.jp/js/jp-rinco-test.js" charset="utf-8"></script>
</head><body>
<div class="jp_rinco_test_autoTest">
	<div class="title">Math.max()</div>
	<table>
		<tr>
			<th>code</th>
			<th>expect</th>
			<th>result</th>
		</tr>
		<tr class="test">
			<td><pre class="code">Math.max(4,8);</pre></td>
			<td><pre class="expect">8</pre></td>
			<td class="result"></td>
		</tr>
	</table>
</div>
</body></html>

html の形式は自由ですが、表形式がわかりやすいでしょう。実際には関数の説明など、仕様に関する情報も加えることができます。

ページが表示されると、Testツールはまず <div class="jp_rinco_test_autoTest"> が存在するか調べます。存在すればその中身を、1つのテストケースとして処理してくれます。 html 中に、テストケースは幾つあってもかまいません。

今回は 6～20行が1つのテストケースですね。テストケースの中に、class="title" が指定された要素があれば、それをそのテストケースのタイトルとして認識します。上記の例ではタイトルは「Math.max()」になりますね。

テストケースの中に、class="test" が指定された要素があれば、それを1つのテストとして処理します。テストケースの中に、テストは幾つあってもかまいません。

さて、実際のテストの内容をみてみましょう。今回は 14～18行が1つのテストケースですね。

テストの中 15行目に class="code" が指定された要素があります。 Testツールは、それをテスト用のJavaScriptコードと認識します。上記の例では「Math.max(4,8);」がコード部分ですね。

同じくテストの中 16行目に class="expect" が指定された要素があります。ここに期待する実行結果を記載します。先ほどのコードが正しく実行された場合に、得られるべき正しい値を指定するわけです。なお値は JSON 形式で記載してください。

同じくテストの中 17行目に class="result" が指定された要素があります。これは Test ツールが実際の実行結果を表示するためのエリアなので、中身は空でかまいません。

なお、class="code" と class="expect" は <pre> タグに対して指定しています。こうしておくと、改行などに気を使わなくてもいいので、少し楽になります。

さて、実際の Web 表示をみてみましょう。

Math.max()

code	expect	result
Math.max(4,8);	8

まずテストケースのタイトル部分「Math.max()」に注目します。ここが緑色であれば、そのテストケース全体が成功、つまり中の全テストが問題なく実行されています。実際にテストの記載された行も、緑になっていますね。

なお、この緑色の表示は標準のCSS (jp-rinco-test.css) による設定です。 CSS を変更すればお好みの表示に変更することができます。

利用例2 結果に問題がある場合

利用例1 に、テスト項目を1つ追加してみましょう。

<html><head>
<link type="text/css" rel="stylesheet" href="http://rinco.jp/js/jp-rinco-test.css"></link>
<script type="text/javascript" src="http://rinco.jp/js/prototype.js" charset="utf-8"></script>
<script type="text/javascript" src="http://rinco.jp/js/jp-rinco-test.js" charset="utf-8"></script>
</head><body>
<div class="jp_rinco_test_autoTest">
	<div class="title">Math.max()</div>
	<table>
		<tr>
			<th>code</th>
			<th>expect</th>
			<th>result</th>
		</tr>
		<tr class="test">
			<td><pre class="code">Math.max(4,8);</pre></td>
			<td><pre class="expect">8</pre></td>
			<td class="result"></td>
		</tr>
		<tr class="test">
			<td><pre class="code">Math.max(4,9);</pre></td>
			<td><pre class="expect">4</pre></td>
			<td class="result"></td>
		</tr>
	</table>
</div>
</body></html>

19～23行が追加したテストになります。 21行にある class="expect" 要素に、わざと間違った値を指定してあります。

　(テストケースが間違っているなんて、とんでもないのですが...。説明のためですので勘弁してください)

さて、実際の Web 表示をみてみましょう。

Math.max()

code	expect	result
Math.max(4,8);	8
Math.max(4,9);	4

まずテストケースのタイトル部分「Math.max()」に注目します。ここが赤色になっていますね。これは、テストケースの中に、問題の発生したテストが存在することを示しています。 2つめのテスト項目の列も、同様に赤になっていますね。

この赤色の表示も標準のCSS (jp-rinco-test.css) による設定です。 CSS を変更すればお好みの表示に変更することができます。

利用例3 エラーが発生する場合

次は String.substring() 関数を使用したサンプルです。まずは html をざっとみてみてください。

<html><head>
<link type="text/css" rel="stylesheet" href="http://rinco.jp/js/jp-rinco-test.css"></link>
<script type="text/javascript" src="http://rinco.jp/js/prototype.js" charset="utf-8"></script>
<script type="text/javascript" src="http://rinco.jp/js/jp-rinco-test.js" charset="utf-8"></script>
</head><body>
<div class="jp_rinco_test_autoTest">
	<div class="title">String.substring()</div>
	<div><pre class="init">var str = "abcdefg";</pre></div>
	<table>
		<tr>
			<th>code</th>
			<th>expect</th>
			<th>result</th>
		</tr>
		<tr class="test">
			<td><pre class="code">str.substring(3);</pre></td>
			<td><pre class="expect">"defg"</pre></td>
			<td class="result"></td>
		</tr>
		<tr class="test">
			<td><pre class="code">str.substring(0,3);</pre></td>
			<td><pre class="expect">"abc"</pre></td>
			<td class="result"></td>
		</tr>
		<tr class="test">
			<td><pre class="code">str.substrinf(0,3);</pre></td>
			<td><pre class="expect">"abc"</pre></td>
			<td class="result"></td>
		</tr>
		<tr class="test">
			<td><pre class="code">str.substrinf(0,3);</pre></td>
			<td><pre class="expect">TypeError</pre></td>
			<td class="result"></td>
		</tr>
	</table>
</div>
</body></html>

まず 8行目に注目です。 class="init" が指定された要素が追加されています。

前章で class="title" はテストケースのタイトルを指定する要素でした。それに対し class="init" に指定された要素は、そのテストケースにおける初期化JavaScriptコードとして扱われます。

初期化コードは、各テストの実行前に1度、実行されるコードです。テストケースの開始時に1回ではなく、テスト実行のたびに1回、ですのでお間違えなく。テストに使用する値の準備などを記述するとよいでしょう。

また今回は4つのテストが含まれていますが、下の2つに注目です。説明は、Web 表示をみたあとにしましょう。

String.substring()

var str = "abcdefg";

code	expect	result
str.substring(3);	"defg"
str.substring(0,3);	"abc"
str.substrinf(0,3);	"abc"
str.substrinf(0,3);	TypeError

さて、結果をみてみましょう。 3つ目のテストのみ赤(問題あり)になっているとおもいます。予想通りだったでしょうか？

3つ目のテストの失敗の理由は簡単です。単なるタイプミスで、str.substring を str.substrinf となってます。これはエラーになりますよね。

ここで、4つ目のテストに注目してみましょう。同様にタイプミスしていますが、緑色(問題なし)の表示になっています。不思議ですね？

expect の欄に答えはあります。 4つ目のテスト、期待値としては TypeError と記載されています。つまりエラーになるのは、想定の範囲内ってやつです。

JavaScript の実行は失敗していますが、エラーが出るのは想定どおりなので、、、テストとしては成功していってわけ。

実は、このへんにテスト・ファーストの極意があります。コードは完璧じゃなくてもいい、変な値を指定されたら Error を発生してもいいんですよ。 null 指定されたり、NaN 指定された場合とか。ただしどんな場合にはどんな Error を出すのか、は仕様としてテストケースに入れておくべきです。ある日突然、違う Error を出すようになっちゃ困りますからね。

Core/UI ツールとの連動

Test ツールは単体でも動作しますが、Core/UI ツールと一緒に読み込まれた場合、より便利に利用できます。各テストケースがそれぞれ、展開可能なセクション表示になります。

<script type="text/javascript" src="http://rinco.jp/js/jp-rinco.js" charset="utf-8"></script>
<script type="text/javascript" src="http://rinco.jp/js/jp-rinco-ui.js" charset="utf-8"></script>

すべて成功したテストケースはセクションが閉じられ、問題のあったテストケースのみ展開されて表示されます。テスト/テストケースの数が非常に多い場合、問題をすぐに把握することができます。

また以下のような class 指定をした html をページに記載すると、セクションの一括展開/格納の機能が自動的に付与されます。

<div id="jp_rinco_test_autoTestPanel">
	<span class="expandall">Expand all</span>
	<span class="collapseall">Collapse all</span>
</div>

実際に利用したページとして、proto-webtools Core テストページなどがあります。

カスタマイズに関して

最低限の表示の設定は jp-rinco-test.css ファイルで設定されています。この内容を書き換えれば表示をカスタマイズできます。

既存のクラス名を使用したい場合は、以下のように使用しているクラス名を置き換えることができます。このコードは js ファイルを読み込んだ後であれば、html のどこに配置してもかまいません。

<script type="text/javascript">
	// 成功の場合に使用されるクラス名 (ok) を変更する
	jp.rinco.test.classNameOk = 'testOk';
	// 失敗の場合に使用されるクラス名 (ng) を変更する
	jp.rinco.test.classNameNg = 'testNg';
</script>

またテスト対象の指定のしかたや、動作条件も変更することができます。

<script type="text/javascript">
	// テストケースの選択CSSパターン (.jp_rinco_test_autoTest) を変更する
	jp.rinco.test.selectAutoTest = '.testCase';
	// タイトルの選択CSSパターン (.title) を変更する
	jp.rinco.test.selectTitle = '.label';
	// Core/UI ツールが読み込まれていても、自動セクション化はしない
	jp.rinco.test.enableAutoTestExpand = false;
</script>

動作指定には他にも設定項目があります。詳細は js ファイルを参照してください。

ダウンロード

ファイルは以下からダウンロードしてください。

【200/08/29 現在、ドキュメント整備中...。】

see this

【200/08/29 現在、ドキュメント整備中...。】