Mac OS X/Linux¶

MacとLinuxでは Node のパッケージマネージャー npm を使ってインストールできます。

$ npm install -g buster

Windows¶

VMにインストール¶

VirtualBoxを使って Buster.JS をインストールする。 この方法ならWindowsであっても同様の環境を構築できる

try-busterjs¶

VirtualBox を使うためホストOSに関係なく、 同じ方法を使ってVirtualBox上で動く Buster.JS 環境を構築できます。 あくまで、用意されたお試しの環境をVirtualBoxに作るものなので、ちゃんとやりたい場合は 自分で同じように作ったほうがいいかもしれません。

Note

今回はホストOSがWindowsを例にする

まずは、VirtualBox - Download と Vagrant - Downloads から それぞれのインストーラーをダウンロードしてインストールします。

Vagrant は任意のディレクトリにインストールし、コマンドラインから利用するためにPATHを通す必要があります。 今回は D:\ruby\vagrant\ にインストールし、 D:\ruby\vagrant\bin へPATHを通すようにしました。

Ruby + VirtualBox + Vagrant が揃ったら、まずはvagrantで利用できるVMイメージをbaseという名前で取得する

$ vagrant box add base http://files.vagrantup.com/lucid32.box

次に try-busterjs のリポジトリをcloneしてVagrantのセットアップを行います。

$ git clone https://github.com/mroderick/try-busterjs.git
$ cd try-busterjs
$ vagrant up

vagrant up するとVirtualBox上でUbuntuが立ち上がるので、 このゲストOSに対してSSHで接続して Buster.JS を動かす事ができます。

MacやLinuxではsshがコマンドラインから利用できるので、 vagrant ssh を行うだけでSSH接続できますが、 Windowsでは別途 PuTTY や RLogin といったSSHクライアントとして 動作するソフトウェアを使用してSSH接続を行います。 [1]

Note

今回は RLogin を使用

SSHクライアントでの接続方法は vagrant ssh を行うと表示されますが、

HOST     : 127.0.0.1
Username : vagrant
Password : vagrant
Private key : ~/.vagrant.d/insecure_private_key
Port     : 2222

上記のような設定で、SSHの鍵はユーザーのホームディレクトリ以下に /.vagrant.d/insecure_private_key と いうものができているため、それを指定します。

SSH接続ができたら、後は通常のLinuxでの Buster.JS 環境と同様になります buster コマンドがインストールされているかを確認して、もしインストールされてないならnpmでインストールしておきます。

$ sudo npm install -g buster
# パスワードは vagrant

これで、 try-busterjs を使ってVirtualbox上に Buster.JS 環境を構築できましたが、 もっと詳細に設定等をしたい場合はSSHで利用するLinux on VM [2] などを作成するのがよいと思われます。

ホストOS:Windows、ゲストOS:Ubuntuとして、VBoxHeadlessTray などを利用して、 ヘッドレスでVM上にLinuxを動作させて、SSH接続して利用すれば、普通の利用の範囲なら速度やメモリ消費量的にも問題無い程度で動作させることができると思われます。

[1]	Get Started With Vagrant On Windows — zamboni 0.8 documentation

[2]	WindowsからVM上のLinuxをSSH経由で利用する開発環境の構築 | Web scratch

設定ファイル-buster.js¶

Buster.JSではコンフィグファイルを作成し、そこへテストで使用するソースファイルやテストファイルの読み込みの定義や ブラウザ、Node環境どちらで実行するテストなのかなどを指定する必要があります。

デフォルトでは buster.js というファイル名のjsファイルが設定ファイルとして利用されます。

以下のような Buster-Project というディレクトリ直下に buster.js(設定ファイル) が有る場合はそれが利用され、 spec または test ディレクトリに buster.js(設定ファイル) が置かれている場合はそちらが利用されます。

Buster-Project
├── buster.js
├── spec/
│   └── buster.js
└── test/
    └── buster.js

通常はtestかspec ディレクトリに置いておくのが良いですが、任意のディレクトリにおいて buster test の --config オプションで任意の場所にある設定ファイルのパスを指定して利用できます。

$ buster test
// test/buster.js or spec/buster.js

$ buster test --config path/to/buster.js
// 任意の場所の設定ファイルを指定できる

シンプルなNodeテストを動かしてみよう¶

使用するサンプルは以下のリポジトリにまとめられているので git clone するなどして取得して下さい

• azu/busterjs-kumite
• git clone https://github.com/azu/busterjs-kumite.git

今回の動かすサンプルは getting-started/ ディレクトリにあります。 まずは動かしてみましょう。

Buster.JS のインストール を参考にBuster.JSがインストール済みならば、 次のように getting-started/ ディレクトリで buster test コマンドを叩くことで テストが実行されテスト結果が表示されます。

$ cd getting-started/
$ buster test
My Test Case: ....
1 test case, 4 tests, 4 assertions, 0 failures, 0 errors, 0 timeouts

getting-started/ ディレクトリ直下には buster.js(設定ファイル) が置かれているので、 今回は --config オプションで設定ファイルのパスを指定しなくても自動で読み込まれます。

./getting-started/
├── ./buster.js
└── ./test
    └── ./test/simple-node-test.js

buster test によりテストが実行が確認出来たので、 buster.js(設定ファイル) の中身を見ていきます。

/busterjs-kumite/getting-started/buster.js

var config = module.exports;

config["My tests"] = {
    env : "node", // or "browser"
    tests : [
        "test/*-test.js"
    ]
};

BusterJSでは JsTestDriver の jsTestDriver.conf のように 設定ファイルを読み込んでテストを実行しますが、 buster.js(設定ファイル) は名前の通りテスト設定もJavaScriptファイルで定義されます。

今回の設定ではnode環境で、testディレクトリにある *-test.js にマッチするテストファイルを読み込んで実行するという定義がされています。 testディレクトリ以下には simple-node-test.js しか無いので、そこに書かれているテストが実行されます。

/busterjs-kumite/getting-started/test/simple-node-test.js

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

var buster = require("buster");// for Node env
buster.testCase("My Test Case", {
    "assert.euqals a === B" : function(){
        assert.equals("foo", "foo");
    },
    "should be true" : function(){
        assert(true);
    },
    "should be false" : function(){
        refute(false);
    },
    "refute.euqals a !== B" : function(){
        refute.equals("foo", "bar");
    }
});

1行目は env : "node" の時に必要なだけなので、ブラウザテストの場合はなくても問題ありません。

buster.testCase 内で それぞれ以下のような形でテストケースを定義して使います。

"テスト名" : function(){
    // テストの中身
}

Buster.JSのアサーション関数の多く [1] は assert/refute メソッドからなっています。

assert と refure は対になる関係で、 assertは assert(true); ならテストがパスされ、 refuteは refute(false); ならテストがパスされます。

assert/refute はそれぞれ同様のメソッド(equalsやsame等)を持っているので、 この２つのアサーション関数を利用してテストを書いていくことになります。

Node環境の場合¶

上記の buster.js(設定ファイル) には、Nodeとブラウザの二種類のテスト設定が書かれています。 Buster.JSでは一つの buster.js(設定ファイル) に複数の設定ファイルを書くことができるようになっています。

env : "node" と設定されているNode環境向けのテストを見ていきます。

テストを実行するには config-patterns ディレクトリにいる状態で、 buster test の -e/--environment オプションをnodeに指定して実行します。

$ cd config-patterns
$ buster-test -e node
type: .
Multi-environment: .
Skipping Multi-environment dependent on dom context, unsupported requirement: DOM

2 test cases, 2 tests, 2 assertions, 0 failures, 0 errors, 0 timeouts

-e/--environment オプションを指定すると、 buster.js(設定ファイル) で envが該当してるコンフィグのテストを実施します。 つまりこの場合は、 -e node と指定したので config[“node tests”] のテストが実行されます。

hybrid-test.js はとりあえず置いておいて、以下のテストファイルが読みこまれて実行されます。

/busterjs-kumite/config-patterns/test/node-test.js

var buster = require("buster");
buster.testCase("type", {
    "isNull is null" : function(){
        assert.isNull(null);
    }
});

テスト自体は 簡単なテストを動かしてみよう と代わり映えしないので、次はブラウザ環境のテストを見ていきます。

ブラウザ環境の場合¶

Buster.JSでブラウザを使ったテストを行う場合は、Node環境のテストと違って少し準備が必要です。

大まかな手順を書くと以下のようになります。

1. buster server を立ち上げる
2. テストしたいブラウザで http://localhost:1111/capture へアクセスする
3. buster test でテストを実行する

$ buster server
buster-server running on http://localhost:1111
$ open http://localhost:1111/capture # もしくは手動で開く
$ buster test -e browser # configがbrowserしかない場合は-eは指定しなくてもいい

実際に config-patterns ディレクトリのテストを動かしてみましょう。

$ buster server
$ open http://localhost:1111/capture
$ buster test -e browser
Chrome 19.0.1084.56, OS X 10.7 (Lion):
Firefox 13.0.1, OS X 10.7 (Lion):Ï
4 test cases, 6 tests, 8 assertions, 0 failures, 0 errors, 0 timeouts

ブラウザテストを実行すると、それぞれのブラウザで実行したテストの合計が表示されているので、 実際に書かれている テストケースの数 * ブラウザ数 の結果が表示されています。

config[“browser tests”] の中身を見ていきます。

/busterjs-kumite/config-patterns/test/browser-test.js

buster.testCase("DOM", {
    "test exist DOM API" : function(){
        var div = document.createElement("div");
        assert.tagName(div, "div");// div or DIV
        assert.tagName(div, "DIV");// 大文字小文字はどちらもいい
    }
});

Node環境とは違い、最初に手動で var buster = require("buster"); する必要はありません。 また、実際にブラウザで動作するテストのため、DOM APIを使ったテストを実行する事ができます。

Buster.JSではassert.tagNameのようにDOMに関するassertionメソッドも用意されています。

ハイブリッドなテスト¶

最後にどちらの config でも読み込まれている、 hybrid-test.js について見ていきます。

このテストファイルでは、Node、ブラウザ どちらから読み込んでも動作し、また特定の環境でのみ評価されるようなテストも書かれています。

/busterjs-kumite/config-patterns/test/hybrid-test.js

if (typeof module == "object" && typeof require == "function"){
    var buster = require("buster");// node環境なら読み込む
}

buster.testCase("Multi-environment", {
    "runs in all environments" : function(){
        assert(true);
    },

    "dependent on dom context" : {
        // requiresSupportFor で trueの場合のみ、contextのテストが実行される
        requiresSupportFor : { "DOM" : typeof document !== "undefined" },
        "only runs in browser-like environments" : function(){
            var el = document.createElement("p");
            el.className = "item feed";
            assert.className(el, "item");
        }
    }
});

requiresSupportFor に判定するためのオブジェクトを設定して、その中身がtrueなら そのコンテキスト(この場合は”dependent on dom context”の中)に書かれているテストが実行されます。

つまり、”dependent on dom context” の中に書かれているテストはNodeの場合documentオブジェクトがないため、評価されません。 実際に実行すると

$ buster test -e browser && buster test -e node
Firefox 13.0.1, OS X 10.7 (Lion):
2 test cases, 3 tests, 4 assertions, 0 failures, 0 errors, 0 timeouts
type: .
Multi-environment: .
Skipping Multi-environment dependent on dom context, unsupported requirement: DOM

2 test cases, 2 tests, 2 assertions, 0 failures, 0 errors, 0 timeouts

Nodeの方ではスキップされているため、結果に表示されるテスト数も異なる事が分かります。

このように、Buster.JSでは一つの buster.js(設定ファイル) に複数の設定を書いたり、 一つのテストファイルに複数の実行環境を場合分けして行うのを簡単にできるような仕組みが備わっています。

どの buster.js(設定ファイル) を使うかは buster-test の -c/--config オプションで指定できるので、 buster.js(設定ファイル) 自体を分割してやる方法でもいいと思います。

ブラウザ内でも使える機能が異なる事は多いため、 requiresSupportFor で実行されるブラウザのfeature detectをして、 実行されるテストを分けることでテストが複雑化し過ぎないようにする事もできます。

strftime¶

指定形式にフォーマットされた日時を取得できる関数 strftime を例にテストを書いてみます。

var config = module.exports;

config["My node test"] = {
    env : "node", // or "browser"
    tests : [
        "test/*-test.js"
    ]
};

config["My browser test"] = {
    env : "browser", // or "browser"
    sources : [
        "src/*.js"
    ],
    tests : [
        "test/*-test.js"
    ]
};

1
2
3
4
5

if (typeof require == "function" && typeof module == "object"){
    buster = require("buster");
    // Nodeの場合はbuster.jsのsourcesでは読み込まれない
    require("../src/strftime");
}

$ buster test

$ buster-autotest

// strftimeはDataオブジェクトを拡張する
if (typeof Date.prototype.strftime !== "function"){
    Date.prototype.strftime = (function(){
        function strftime(format){
            var date = this;

            return (format + "").replace(/%([a-zA-Z])/g, function(m, f){
                var formatter = Date.formats && Date.formats[f];

                if (typeof formatter == "function"){
                    return formatter.call(Date.formats, date);
                }else if (typeof formatter == "string"){
                    return date.strftime(formatter);
                }

                return "%" + f;
            });
        }

        // Internal helper
        function zeroPad(num){
            return (+num < 10 ? "0" : "") + num;
        }

        Date.formats = {
            // Formatting methods
            d : function(date){
                return zeroPad(date.getDate());
            },

            m : function(date){
                return zeroPad(date.getMonth() + 1);
            },

            y : function(date){
                return zeroPad(date.getYear() % 100);
            },

            Y : function(date){
                return date.getFullYear() + "";
            },

            j : function(date){
                var jan1 = new Date(date.getFullYear(), 0, 1);
                var diff = date.getTime() - jan1.getTime();

                // 86400000 == 60 * 60 * 24 * 1000
                return Math.ceil(diff / 86400000);
            },

            // Format shorthands
            F : "%Y-%m-%d",
            D : "%m/%d/%y"
        };

        return strftime;
    }());
}

// テストケース
buster.testCase("Date strftime tests", {
    setUp : function(){
        this.date = new Date(2009, 9, 2, 22, 14, 45);
    },

    "test format specifier %Y" : function(){
        assert.same(Date.formats.Y(this.date), "2009",
                "%Y should return full year");
    },

    "test format specifier %m" : function(){
        assert.same(Date.formats.m(this.date), "10",
                "%m should return month");
    },

    "test format specifier %d" : function(){
        assert.same(Date.formats.d(this.date), "02",
                "%d should return date");
    },

    "test format specifier %y" : function(){
        assert.same(Date.formats.y(this.date), "09",
                "%y should return year as two digits");
    },

    "test format shorthand %F" : function(){
        assert.same(Date.formats.F, "%Y-%m-%d",
                "%F should be shortcut for %Y-%m-%d");
    }
});

// assert.same(Date.formats.Y(this.date), "2009");
// ==>
if(Date.formats.Y(this.date) === "2009"){
  // pass test
}else{
  // fail test
}

setup/teardown¶

setUp/tearDownはそれぞれのテストの 実行前(setup)/実行後(teardown) に実行する関数を登録できます。 多くのテストフレームワークで同様の機能が提供されています。

/busterjs-kumite/test-patterns/test/setup-teardown.js

buster.testCase("setup/teardown", {
    setUp : function(){
        this.i = 1
    },
    tearDown : function(){
        delete this.i;
    },
    "one" : function(){
        this.i = 10;
        assert.equals(this.i, 10);
    },
    "two" : function(){
        assert.equals(this.i, 1);
    }
});

上記の例では、 "one" と "two" それぞれの前後でsetUp/tearDownが実行されています。

テスト内で共通のプロパティを使いたい場合は、 this にプロパティを追加して利用できます。 ここでは、 this.i を実行前に値を設定して、実行後に削除しています。 そのため、 "one" の中で this.i の値を変更しても、 "two" には影響がでないようになっています。

Test case contexts¶

Buster.JSでは一つのtestCase内にコンテキストを複数持つことができます。

/busterjs-kumite/test-patterns/test/testcase-context.js

buster.testCase("testCase Context", {
    "test #1" : function(){
        assert.same("test", "test");
    },
    "context" : {
        "test #2" : function(){
            assert(true);
        },
        "Nest Context" : {
            "test #3" : function(){
                refute(false);
            }
        }
    }
});

上記のコードだと、test #1が所属するコンテキスト、test #2が所属するのコンテキスト、test #3が所属するの3つがあることが分かります。 コンテキストにまとめることで、一つのtestCase内でもテストを一定のグループにまとめることができるようになっています。

コンテキストにはそれぞれ、setUp/tearDownを書くことができ、そこで書いたsetUp/tearDownはそのコンテキスト以下のテスト時に使われます。

また、 Test reporters によってはコンテキストを認識して見やすい形で出力してくれる場合もあります。

// Deferred tests¶

Deferred testsとはDeferredを使ったテストという意味ではなくて、そのテストそのものを延期することを示しています。 延期されたテストは、テスト実行時に実行されない用になります。

テスト名を//から始める事でそのテストは Deferred test になります。

/busterjs-kumite/test-patterns/test/deferred-test.js

buster.testCase("Deferred", {
    "// test isn't implement" : function(){
    },
    context : {
        setUp : function(){
            buster.log("doesn't call");
        },
        "// this context all Deferred" : function(){
        }
    }
});

実行するとDeferred された有無も表示されます。 コンソールの場合は、 Deferred - Travis CI のような感じで出力されます。

また、 Test case contexts などで、そのコンテキストにDeferred testsのみしかない場合は、 そのコンテキストに存在するsetUp/tearDownは実行されないようになっています。

そのため、上記の例では buster.log("doesn't call"); は呼ばれない事になります。

非同期テスト¶

Buster.JSでは非同期のテストもサポートされている。 非同期テストの手法は大きく分けて3種類用意されている

• Callback done flag - 引数doneの実行を終了フラグとする
• Promise - Promiseオブジェクトをreturnする
• 非同期をMock/Stub/Fakeなどを使い同期的にする

"test not asynchronous" : function(){
    setTimeout(function(){
        assert(true);
    }, 100);
}
// ✖ My thing test not asynchronous
// No assertions!

buster.testCase("asynchronous", {
    "test asynchronous" : function(done){
        setTimeout(function(){
            assert(true);
            done();// test end
        }, 100);
    }
});

Promiseは"未完"な状態から始まり、"未完"あるいは"完了"あるいは"失敗"の状態へ遷移すること
Promiseは"then"という名前の関数をもったオブジェクトを返すこと
"then"メソッドはPromiseを返しチェインできるようにし、またコールバックでエラーが起きた場合は"失敗"の状態へ遷移すること

buster.testCase("Promise", {
    "test async, use promise" : function(){
        var promise = { // then メソッドの有無が重要
            then : function(callback){
                this.callbacks = this.callbacks || [];
                this.callbacks.push(callback);
            }
        };

        setTimeout(function(){
            buster.assert(true);
            var callbacks = promise.callbacks || [];
            for (var i = 0, l = callbacks.length; i < l; ++i){
                callbacks[i]();
            }
        }, 100);
        // thenを持ったものを返す => promiseと判断 (isPromise)
        return promise;
    },
    "test async ,use when.js" : function(){
        var deferred = when.defer();

        setTimeout(function(){
            buster.assert(true);
            deferred.resolver.resolve();
        }, 100);

        return deferred.promise;
    }
});

Mock/Stub/Spy/Fake¶

Mock/Stub/Fakeを使って非同期のコードを同期的にテストしたり、 依存関係などを緩和してテストを実行したり、テストを楽にしてくれます。

buster.testCase("SinonJS", {
    setUp : function(){
        this.myLib = {
            method : function(str){
                return str;
            }
        }
    },
    "test a spy" : function(){
        var spy = this.spy(this.myLib, "method");// sinon.spy
        this.myLib.method("test");
        assert.calledOnce(spy);
    },
    "test a stub" : function(){
        var stub = this.stub(this.myLib, "method");// sinon.stub
        stub.withArgs("hello").returns("world");// "hello" を渡すと "world" を返す
        assert.equals(this.myLib.method("hello"), "world");// return "world"
    },
    "test a mock" : function(){
        var mock = this.mock(this.myLib);// sinon.stub
        mock.expects("method").withArgs("hello");// 期待値を設定
        this.myLib.method("hello");
        assert(mock);
    },
    "test async in sandbox" : {
        setUp : function(){
            // SandboxにFakeを作る
            this.sandbox.useFakeServer();
            this.sandbox.useFakeTimers();
        },
        tearDown : function(){
            // Sandboxを戻す
            this.sandbox.restore();
        },

        "test FakeTimer" : function(){
            var spy = this.spy();
            setTimeout(function(){
                spy();
            }, 16);
            this.sandbox.clock.tick(16);
            assert.called(spy);
        },
        "test FakeServer" : function(){
            var expectRes = {
                status : "OK"
            };
            var xhr = new XMLHttpRequest();
            xhr.open('GET', '/get', true);
            xhr.onreadystatechange = function(){
                if (this.readyState === XMLHttpRequest.DONE && this.status === 200){
                    var res = JSON.parse(this.responseText);
                    assert.match(res, expectRes);
                }
            };
            xhr.send();
            this.sandbox.server.requests[0].respond(200, {}, JSON.stringify(expectRes));
        }
    }
});

reportersの種類¶

現在利用できるreportersの種類は下記に書かれているものと、独自に定義したreporterを利用できます。

• Test reporters
• buster-test/lib/reporters at master · busterjs/buster-test · GitHub

デフォルトでは、 dots が使用され、buster-test の -r/--reporter オプションで指定することができます。 -r/--reporter オプションの詳細は、コマンドライン上で下記のようにして見ることができます。

$ buster test -h reporters

独自に定義したreporterを使う¶

reporter機能は自分で作成したものを利用する事ができます。

まずは、custom reporterを作成します。

/busterjs-kumite/reporters/reporter/myReporter.js

var terminal = require("buster-terminal");

module.exports = {
    create : function(opt){
        var reporter = buster.create(this);
        opt = opt || {};
        reporter.io = opt.io || require("util");
        reporter.term = terminal.create(opt);
        reporter.testCount = 0;
        reporter.contexts = [];

        return reporter;
    },

    listen : function(runner){
        runner.bind(this, {
            "suite:end" : "suiteEnd", "context:start" : "contextStart",
            "context:end" : "contextEnd", "test:success" : "testSuccess",
            "test:start" : "testStart", "test:deferred" : "testDeferred",
            "test:failure" : "testFailure", "test:error" : "testEnd",
            "test:timeout" : "testEnd", "context:unsupported" : "contextUnsupported"
        });

        return this;
    },

    suiteEnd : function(){
        this.io.puts("1.." + this.testCount);
    },

    contextStart : function(context){
        if (this.contexts.length == 0){
            this.testCount = 0;
            this.contexts.push(context.name);
            this.io.puts("Browser : " + context.name);
        }else{
            this.contexts.push(context.name);
            var space = new Array(this.contexts.length);
            var color = "yellow";
            this.io.puts(space.join("\t") + this.term[color]("<" + context.name + ">"));
        }
    },

    contextEnd : function(){
        this.contexts.pop();
    },

    contextUnsupported : function(data){
        var name = data.context.name;
        var features = data.unsupported;
        var plural = features.length > 1 ? "s" : "";
        this.testCount += 1;
        this.io.puts("not ok " + this.testCount + " " + name + " # SKIP " +
                "Unsupported requirement" + plural + ": " + features.join(", "));
    },

    testStart : function(test){
        this.testCount += 1;
        var space = new Array(this.contexts.length + 1);
        this.spacer = space.join("\t");
        this.test = test;
    },

    testSuccess : function(test){
        this.test.passed = true;
        this.testEnd(test);
    },

    testDeferred : function(test){
        this.test.deferred = true;
        this.test.comment = test.comment;
        this.testEnd(test);
    },

    testEnd : function(test){
        this.io.puts(this.spacer + label(this.test) + this.testCount + " " +
                this.test.name);
    },
    testFailure : function(test){
        this.io.puts(test.error.stack);
    }
};
function label(test){
    var label = "";
    if (test.deferred){
        label = "✎ ";
    }else if (test.passed){
        label = "✔ ";
    }else{
        label = "✘ ";
    }
    return label;
}

module.exports["test:error"] = module.exports.testEnd;
module.exports["test:timeout"] = module.exports.testEnd;

とりあえず、このcustom reporter(myReporter)を使ってテストを実行してみます。

buster server を行なって、ブラウザをキャプチャさせた状態で、 busterjs-kumite/reporters に、test.sh というファイルが用意されているのでそれを実行します。

$ sh test.sh
Browser : Firefox 13.0.1, OS X 10.7 (Lion)
  <My Test Case>
    <Context>
      <Context NEST>
        ✎ 1 TEST Three
      ✔ 2 TEST TWO
    ✔ 3 TEST ONE
Browser : Chrome 20.0.1132.57, OS X 10.7 (Lion)
  <My Test Case>
    <Context>
      <Context NEST>
        ✎ 1 TEST Three
      ✔ 2 TEST TWO
    ✔ 3 TEST ONE

これのように、自作のmyReporterを使ったテスト結果を実行するには、 -r/--reporter オプションでmyReporterと指定する必要がありますが、 適当な場所に作っただけではnodeの require() からは読み込めないため、 NODE_PATH に myReporter.jsがあるディレクトリを追加して、 require("myReporter") で読み込めるような状態で buster test -r myReporter して実行します。

つまり、以下のように NODE_PATH を設定してテストを実行させています。

NODE_PATH=reporter/ buster test -r myReporter

Buster.JSの仕組み的に、 buster-test / reporters.js にて、 -r/--reporter オプションで指定したモジュール(又は BUSTER_REPORTER の環境変数でも指定可能) を読み込む処理が行われています。

この読み込む処理は、単純に require("reporter名") しているため、NODE_PATHを使ったモジュールへのパスの通し方以外でも、 buster test 実行前にrequireで読み込めるように準備しておけば良いことになります。

custom reporterの書き方の詳細はドキュメントや既存のreporterが参考になります。

• Test reporters
• Test runner
• buster-test/lib/reporters at master · busterjs/buster-test · GitHub

reporterに色を付ける¶

既存はspecification等のreporterには色が付けて出力されますが、 このようなターミナル上の色を付けるのには buster-terminal が利用できます。

taps reporterを参考に見ていくと、最初に var terminal = require("buster-terminal"); というように buster-terminal モジュールを読み込んでいます。

/busterjs-kumite/reporters/reporter/taps.js

var buster = require("buster-core");
var terminal = require("buster-terminal");

module.exports = {
    create: function (opt) {
        var reporter = buster.create(this);
        opt = opt || {};
        reporter.io = opt.io || require("util");
        reporter.term = terminal.create(opt);
        reporter.testCount = 0;
        reporter.contexts = [];

        return reporter;
    },

このように、読み込むにはbuster-terminalモジュールへのパスが通ってないといけないので、 package.jsのdependenciesにモジュールを追加して置くのが楽でいいです。

相対パスしていでも読み込めるので該当するパスにファイルを置く方法でもできなくはないです。

"dependencies": {
    "buster-core": ">=0.6.2",
    "buster-terminal": ">=0.4.1",
}

使い方として、reporterのcreateで terminal.create(opt); して返って来たインスタンスを使います。

buster-terminal/lib/buster-terminal.js を 見ると、

term["green"]("色をつけたい文字列")

などのようにANSIカラーをつけたり、文字の一度調整等ができる関数が入ってるようです。

このように、Buster.JSのreporterはJavaScriptで比較的簡単にいじれるので、オレオレreporterを作って見るのもいいかもしれません。

コンソールにログを出力する¶

コンソールへのログ出力には buster.log(message) を利用できます。 これは buster.console.log() と同等で、buster.consoleにはよく見かけるコンソールAPIが存在しています。

buster.log(buster.console);
// => コンソールにフォーマットされて出力される
[LOG] {
      contexts: { log: [undefined] },
      debug: function () {},
      error: function () {},
      format: function () {},
      level: "debug",
      levels: ["error", "warn", "log", "debug"],
      listeners: { log: [function () {}] },
      log: function () {},
      logFunctions: true,
      warn: function () {}
    }

buster.log(message) による出力は formatio により整形されて出力されます。 そのため、オブジェクトならオブジェクトをある程度展開した状態で出力されるようになっています。

DOMオブジェクトも同様に、HTMLタグの状態に展開されて出力されるようになっています。

var p = document.createElement("p");
p.id = "sample";
p.className = "notice";
p.setAttribute("data-custom", "42");
p.innerHTML = "Hey there, here's some text for ya there buddy";

buster.log(p);
// => [LOG] <p id="sample" class="notice" data-custom="42">Hey there, here's so[...]</p>
// 20文字で短縮される

また、デフォルトではウェブで一般に使われるコンソールAPIの window.console は buster.console にバインディングされています。 つまり、 console.log などの基本的なコンソールAPIはそのまま使うことが可能です。

assert.same(console.log, buster.console.log);// pass

このバインディングを無効にするには、 buster test コマンドのオプションに -o, --release-console オプションを指定することで行えます。 (ブラウザ側のコンソールに出力されるようになります)

失敗したテストを眺める¶

上記のサンプルで buster.js(設定ファイル) のconfigグループの”Failure tests” を指定して実行する事で見られます。 -g/–config-group オプションを指定することで特定のconfigグループを実行できます

buster test -g "Failure tests"

大きく分けてテストの失敗には3つぐらいあるので、それを見ていきます。

/busterjs-kumite/debug/test/failure-test.js

if (typeof module == "object" && typeof require == "function"){
    var buster = require("buster");// node環境なら読み込む
}
buster.testCase("My Failure Test", {
    "Assertion failure" : {
        "refute should fail" : function(){
            refute(true);
            // => [refute] Expected true to be falsy
        },
        "assert.same should fail" : function(){
            assert.same("A"); // 本来は比較対象の第二引数が必要
            // => [assert.same] Expected to receive at least 2 arguments
        }
    },
    "Async failure" : {
        "doesn't call assert" : function(){
            setTimeout(function(){
                assert(true);// 非同期なので呼ばれない
            }, 100);
            // => No assertions!
        }
    },
    "Exception failure" : {
        "exception test" : function(){
            throw new Error("cause error");
            assert(true);
        } // => Error
    }

});

実行結果　:

Error.stackの情報¶

テストが失敗した結果にはメッセージ以外にもJavaScriptのスタックトレースが表示されます。 ブラウザでJavaScriptのスタックトレースを見た事がある方は分かると思いますが、 スタックトレースはJavaScriptエンジンによって形式が異なります。

• occ/TraceKit · GitHub
• strawman:error_stack [ES Wiki]
• Latest topics > JavaScriptのスタックトレース - outsider reflex

本来なら、スタックトレースにはテストファイル以外にも Buster.JS 自体に関するトレース等も出るはずですが、 デフォルトでは (./test/failure-test.js:15:20) といったようなテストファイルに関係する部分しか出ていないことが分かります。

Failure: Chrome Failure Test Assertion failure assert.same should fail
[assert.same] Expected to receive at least 2 arguments
at Object.buster.testCase.Assertion failure.assert.same should fail (./test/failure-test.js:15:20)

Buster.JS には Stack filter というモジュールがあり、 デフォルトで入っている dots や specification といった Test reporters ではそれによりフィルターされるようになっています。 (testacularのような整形までの仕組みは今のところ入っていませんが、 Test reporters 等でも実現できるとは思います)

このフィルターを外すオプションもあり、 f/--full-stacks オプションを指定することでフィルターなしの結果が出力されるようになります。 (通常はあんまり出す必要は無い気もしますが)

buster test -e browser -g "Failure tests" -f
// =>
Failure: Chrome My Failure Test Assertion failure assert.same should fail
    [assert.same] Expected to receive at least 2 arguments
    at Object.ba.fail (./buster/bundle-0.6.js:1483:25)
    at assertEnoughArguments (./buster/bundle-0.6.js:1252:16)
    at Function.ba.(anonymous function).(anonymous function) [as same] (./buster/bundle-0.6.js:1264:18)
    at Object.buster.testCase.Assertion failure.assert.same should fail (./test/failure-test.js:15:20)
    at asyncFunction (./buster/bundle-0.6.js:6640:19)
    at callTestFn (./buster/bundle-0.6.js:6746:27)
    at ./buster/bundle-0.6.js:790:27
    at ./buster/bundle-0.6.js:790:27
    at p.then (./buster/bundle-0.6.js:71:31)
    at Object.then (./buster/bundle-0.6.js:177:11)

以上で、 buster.log でのログ出力やテストの失敗するケースやエラースタックの内容について簡単に紹介しました。

WebStormのデバッガー連携¶

Buster.JS はテストの実行環境として buster server と buster static のコマンドがあります。 buster server とは違い buster static はウェブページとして静的なテストページを用意され、 ブラウザでそのURLにアクセスするとQUnitなどのようにテストが実行されます。

つまり、 buster static を使った場合は通常のウェブサイトをデバッグする方法が利用できるため、 ブラウザのデバッガーを使ってテストケースのデバッグなども行いやすいです。

それを利用して、 WebStorm のJavaScriptデバッガーを使って、 WebStormからtestacularでテストとデバッグをする方法 のようにBuster.JSのデバッグを行うことも可能です。

WebStorm¶

WebStorm では自分が公開してるBuster.JSについてのJSDocファイルを利用できます。

WebStormの Settings ‣ JavaScript ‣ Libraries に下記のjsファイルを追加する事で、 BusterJSのメソッドを補完候補に加えたり、IDE上から簡単なドキュメント(Quick Lookup)を参照できます。

• azu/BusterJSDoc
• JavaScript Testing FrameworkのBusterJSを使う

Emacs¶

Emacsは作者の一人が作られてるbuster-mode.elが公開されています。

• buster-mode in Buster - Gitorious
• An introduction to Emacs Lisp

また別の方が、Buster.JSのYasnippetsを公開しています。

• magnars/buster-snippets.el

Vim¶

Vimはvim-busterというものが公開されています。 Vim上からテストの実行やキーワードのハイライトなどに対応しています。

• malclocke/vim-buster

TextMate¶

TextMateのbundleが公開されています。

• magnars/buster.tmbundle

npm package.json¶

まず、Travis CI にはBuster.JSは入ってないので、テストを走らせる前にそれらをTravis CIにインストールさせるようにします。

Buster.JSはnpmで配布されているので、テストの依存関係の設定をnpmの package.json にまとめて置くと、 npm install するだけで準備が出来るので、package.jsonを書いていきます。

また、 package.jsonを作っておくと、githubを見た人も npm install でテスト環境を作れるようになるので、 このように設定をまとめておくのは有用だと思います。

実際に azu/BusterJS-TravisCI に書かれている BusterJS_TravisCI/package.json を見てみます。

{
    "author" : "azu",
    "name" : "BusterJS_TravisCI",
    "description" : "Buster.JS with Travis CI example",
    "version" : "0.0.1",
    "scripts" : {
        "test" : "node_modules/.bin/buster-test"
    },
    "dependencies" : {
        "buster" : "~0.5.0"
    },
    "engines" : {
        "node" : "~0.6"
    }
}

dependencies を見るとbusterの”~0.5.0”に依存していると書かれています。 “~0.5.0”とは0.5.0以上で0.6.0未満で一番バージョン番号が新しいものがインストールされるという意味になります。 同じように engines でnodeのバージョン番号を指定しています。

scripts では npm test とコマンドを叩いた時に実行される動作を指定できます。 ここでは npm install でインストールしたnode_modules/のbuster-testコマンドを実行するようにしています。

npm test については以下が参考になります。

• npmでtestを実行する - 四角革命前夜
• Travis CIでNodeのテスト - hokaccha.hamalog v2

この状態で、 npm install してから npm test すると、同じディレクトリにある buster.js の設定ファイルを元に Buster.JSのテストが走ることが確認できます。

他にもpackage.jsonでは色々設定できますが、package.jsonで設定できることを詳しく知りたい場合は以下を見るのがいいでしょう。

• Specifics of npm’s package.json

.travis.yml¶

.travis.yml では Travis CI がテストを実行する前に行うことや通知の設定や実行するテストコマンドなどを指定できます。

before_script:
  - export DISPLAY=:99.0
  - sh -e /etc/init.d/xvfb start
  - sleep 5
  - node_modules/.bin/buster-server &
  - sleep 5
  - firefox http://localhost:1111/capture &
  - sleep 5
  - phantomjs node_modules/buster/script/phantom.js http://localhost:1111/capture &
  - sleep 5

script:
  - "npm test"

language: node_js

node_js:
  - 0.6

テストの実行環境はnodeを使うため、languageにnode_jsとし、node_jsのバージョンも指定します。 scriptではテスト実行時に行うコマンドを指定できるので npm test とします。(無指定でもこれが使われる)

Buster.JSではテスト実行前にブラウザをキャプチャしておかないと行けないので、 before_script でscriptの行われる前に Buster.JSでテストを行う準備の設定を記述します。

Travis CIでのブラウザを使ったテストについては Travis CI: GUI & Headless browser testing on travis-ci.org にも 書かれていますが、GUIが必要な場合はxvfbを動かすようにします。

次に、 buster-server コマンドでBuster.JSのサーバをたちあげたら、 キャプチャするURLに対して、Travis CIに入ってるFirefoxとphantomJSを使ってそこへアクセスするようにします。

Buster.JSではPhantom.js用のスクリプトが buster/script/phantom.js に用意されてるので、それを利用してキャプチャURLにアクセスさせます。 最近のPhantom.jsではXvfbに依存しなくなったので、Phantom.jsだけを使う場合はxvfbはstartしなくてもいいかもしれません。

• Pure headless PhantomJS (no X11 or Xvfb) - don’t code today what you can’t debug tomorrow

これで、Travis CI上で次のようにテストが走って失敗なら通知をおくってくれるようになるので、 Githubで公開してるJavaScriptプロジェクトのCIが簡単に行うことができるようになります。

• azu/BusterJS_TravisCI

サンプルプロジェクト

• 

• azu/BusterJS-TravisCI

Travis CI ではビルドステータスの画像を取得するURLもあるので、Githubにreadmeなどに貼り付けておくと分かりやすい。

また、このドキュメントで使用されているコードも同様にBuster.JSとTravisCIを使いテストされています

• 

• azu/busterjs-kumite

他のCIサービスについて¶

Travis CI 以外にも Drone.io やJenkins系の BuildHive 等CIサービスは色々あります。

また、今回は Travis CI にデフォルトでインストールされてるFirefoxとPhantomJSでのみでテストを動かしましたが、 少し設定を加えればChromeも同様にテストを動かすことができます。

それらのことについてまとめた記事が以下で公開されています。