読者です 読者をやめる 読者になる 読者になる

Keep on moving

あんまりまとまってないことを書きますよ

Drillbit資料和訳

Titanium Mobile JavaScript テスト

Drillbitの勉強用に資料を翻訳しておきます。

http://developer.appcelerator.com/doc/mobile/drillbit

Drillbit

A unit testing framework, harness, and driver for Titanium
Titanium用のユニットテストフレームワーク、ハーネス、ドライバー

Drillbitテストの書き方

Drillbit resembles a JSSpec test and uses some of their conventions.
DrillbitはJSSpecテストに似ていて、書き方のいくつかを使います。
To define a test suite, you have several options:
テストスイートの定義用に、いくつかのオプションがあります:

  • Create a standalone Javascript file, For example, foo.js under the drillbit/tests folder would define a test suite for foo.
  • 独立したJavascriptファイルを作成し、例えば、drillbit/testsフォルダーの下のfoo.jsはfoo用にテストスイートを定義します。
  • Create a directory with a Javascript file using the same name under it. For example, foo/foo.js under the drillbit/tests folder would define a test suite for foo.
  • 同じ名前を使って、ディレクトリとJavascriptファイルを作成してください。例えば、drillbit/testsフォルダの下にfoo/foo.jsをおくことでfoo用のテストスイートを定義します。
    • Any other resources under the test suite's directory will be recursively copied into the Test Harness application's root before it is deployed
    • デプロイされる前に、テストスイートのディレクトリ下のいかなるリソースもTest Harnessアプリケーションのルートに再帰的にコピーされます。
  • For platform specific test suites, create either of the above under one of the special platform directories. For example, android/foo.js would define a test suite for foo that only ran on the Android emulator.
  • プラットホームに特有なテストスイートに関しては、特別なプラットホームディレクトリの1つの下で上記のどちらかを作成してください。 例えば、android/foo.jsはAndroidエミュレータでのみ実行されるfoo用にテストスイートを定義するでしょう。


You can also specify extra test directories for Drillbit to pull test suites from by using the --tests-dir argument. See the Running Drillbit section below.

また、---test-dir引数を使うことで、Drillbitで実行するテストスイートへ追加テストディレクトリを指定できます。 下のDrillbitの実行を見てください。

In a test suite's Javascript file, you simply need to call the Drillbit function describe to give a description and test spec for your test suite. For example, a simple math test suite with just two tests might look like:

テストスイートのJavascriptファイルで、テストスイート用の記述とテスト仕様を与えるためにDrillbit機能を呼ぶ必要があります。例えば、以下のようなシンプルな計算のテストです。

describe("test simple math", {
    testAdd: function() {
        valueOf(1+1).shouldBe(2);
    },
    
    testSubtract: function() {
        valueOf(2-1).shouldBe(1);
    }
});


The first parameter is the description for your test, and the second parameter is your test spec. Any functions inside the test spec are considered tests to be run by Drillbit.

最初のパラメーターはテストの記述であり、2番目のパラメーターはテスト仕様です。 テスト仕様に基づくどんな関数もDrillbitによって実行されるテストであると考えられています。

Optionally, you may also define these special functions inside your test spec:
また、任意に、テスト仕様に基づいて、これらの特殊関数を定義できます:

before_all 全テスト実行前に呼ばれます
after_all 全テスト実行後に呼ばれます
before 各テストメソッドの前に呼ばれます
after 各テストメソッドの後に呼ばれます
timeout テストがかかる最大時間(ミリ秒)
アサーション

All assertions are executed on the return value of the valueOf method. They all start with the word should:
全ての主張がvalueOfメソッドの返り値で実行されます。 アサーションは全てshouldで始まります。

shouldBe(other) 値がotherと等しい (==)
shouldNotBe(other) 値がotherと等しくない (!=)
shouldBeExactly(other) 値がotherと厳密に等しい (===)
shouldNotBeExactly(other) 値がotherと厳密に等しくない (!==)
shouldBeGreaterThan(number) 値が number より大きい
shouldBeGreaterThanEqual(number) 値が number より大きい、または、等しい
shouldBeLessThan(number) 値が number より小さい
shouldBeLessThanEqual(number) 値が number より小さい、または、等しい
shouldBeTrue() 値がtrue (boolean) である
shouldBeFalse() 値が false (boolean) である
shouldBeNull() 値が null である
shouldNotBeNull() 値がnullでない
shouldBeUndefined() 値が undefined である
shouldNotBeUndefined() 値が undefined でない
shouldBeFunction() 値が 関数 である
shouldBeObject() 値が オブジェクト である
shouldBeArray() 値が 配列 である
shouldBeString() 値が 文字列 である
shouldBeNumber() 値が 数字 である
shouldBeBoolean() 値が boolean である
shouldContain(object) 値が object を含む (indexOf(object) != -1)
shouldBeOneOf(array) 値が array 内にある
shouldMatchArray(array) 値が配列であり、 array の値と一致する
shouldThrowException(function) 値が関数ならば、実行され、例外を投げる.そうでなければ失敗する
shouldNotThrowException(function) 値が関数ならば、実行され、例外を投げない.そうでなければ失敗する
shouldBeZero() 値は 0(number) である

Examples:

valueOf(1+1).shouldBe(2);
valueOf(1*3).shouldNotBe(4);
valueOf(2).shouldBeGreaterThan(1);
valueOf(Ti.App).shouldBeObject();
valueOf(userAgent).shouldContain('Titanium/');
valueOf('a').shouldBeOneOf(['a','b','c']);
valueOf([1, 2, 3]).shouldMatchArray([1, 2, 3]);
valueOf(function() {
    throw new Exception("error");
}).shouldThrowException();
非同期テスト

You can make a test asynchronous by appending _as_async to the end of the function name. Asynchronous tests receive one argument: the callback object.
関数名の最後に "_as_async" をつけることで非同期テストを作成できます。非同期テストはコールバックオブジェクトを引数として受け取ります。

The callback object has two functions:
コールバックオブジェクトには2つの関数があります。

  • passed() The asynchronous test should call this when the test passes.
  • passed() : 非同期テストはテストが通ると呼ばれます。
  • failed(error) The asynchronous test should call this when the test fails, and pass in an exception or an error message
  • failed(error) 非同期テストはテストが失敗、例外、または、エラーメッセージで呼ばれます。

When asserting using the should functions, if an assertion fails, an exception is thrown by Drillbit. In a normal test, this exception is automatically caught and handled by Drillbit, but in an asynchronous test, you will need to surround assertions with try and catch, and call callback.failed(exception).

should関数でアサートするときに、アサーションが失敗すれば、例外がDrillbitによって投げられます。
普通のテストでは、例外は自動的にDrillbitによって、catchされ、扱われます。しかし、非同期テストでは、自分でtry/catchし、callback.failed(exception)を呼ぶ必要があります。

An example using Asynchronous XHR and a timeout fallback

非同期XHRとタイムアウトを使う例

describe("test", {
    test_as_async: function(callback) {
        var xhr = Ti.Network.createHTTPClient();
        var timer = 0;
        xhr.onload = function() {
            clearTimeout(timer);
            try {
                valueOf(this.responseText.length).shouldBeGreaterThan(0);
                callback.passed();
            } catch (e) {
                callback.failed(e);
            }
        };
        xhr.onerror = function(e) {
            clearTimeout(timer);
            callback.failed(e.error);
        };
        xhr.open('GET', 'http://www.test.com');
        xhr.send();
        
        // Wait 10s for response
        timer = setTimeout(function() {
            callback.failed("Timed out waiting for HTTP response");
        }, 10000);
    }
});

Drillbit also provides convenience functions for asynchronous tests:
Drillbitはまた、非同期テスト用の便利な関数を提供します。

asyncTest(args): Creates a function suitable for use as an asynchronous test
asyncTest(args): 非同期テストに適した関数を作成します。

  • args Either a function that starts the asynchronous task or an object with named arguments:
  • args 非同期タスク、または、命名された引数があるオブジェクトを開始します:
    • args.start A function that starts the asynchronous task (required). The return value of this function will be passed to onTimeout, if it is specified.
    • args.start (必要な)非同期タスクを開始する関数。 指定されると、この関数の返り値はonTimeoutに渡されます。
    • args.timeout A timeout in milliseconds. After the timeout is reached, if args.onTimeout is defined, it is called with a try/catch wrapper. Otherwise, the test will fail with a timeout error message. (optional)
    • args.timeout ミリ病単位でタイムアウト。タイムアウト後、args.onTimeout が定義されていれば, try/catch ラッパーから呼ばれます.そうでなければ、タイムアウトエラーメッセージで失敗します。
    • args.onTimeout : A function that is called after args.timeout is reached. The return value of the start function is passed as a parameter (optional)
    • args.onTimeout : 関数は args.timeout後に実行されます。関数への返り値はパラメータで渡されます。
    • args.timeoutError : A custom error to report after args.timeout is reached (optional)
    • args.timeoutError : カスタムエラーを args.timeout後にレポートします。

this.async(function): Returns a function wrapper that surrounds function in a try/catch and calls callback.passed if it is successful, or callback.failed if an exception is caught. (only available within an asyncTest object)

this.async(function): 成功してcallback.passedが呼ばれる、または例外がcatchされてcallback.failedが呼ばれる、トライ/キャッチにおける関数をラップする関数を返します。 (非同期テストが利用可能な場合のみ)

  • function The function with Drillbit assertions
  • Drillbitアサーションを伴った関数function

Here's an example that does the same as above, but uses the convenience APIs to simplify it:
上と同じ例を、シンプルにするために便利なAPIを使います。

describe("test", {
    test: asyncTest({
        start: function(callback) {
            var xhr = Ti.Network.createHTTPClient();
            xhr.onload = this.async(function() {
                valueOf(this.responseText.length).shouldBeGreaterThan(0);
            });
            xhr.onerror = this.async(function(e) {
                throw e.error;
            });
            xhr.open('GET', 'http://www.test.com');
            xhr.send();
        },
        timeout: 10000,
        timeoutError: "Timed out waiting for HTTP response"
    })
});
Drillbit の実行

Before running Drillbit, you'll need to install Titanium Desktop 1.1 either by building and installing from git, or using a recent build from the Continuous Integration server.
Dirllbitの実行前に、gitからビルド/インストール、または、 継続的インテグレーションサーバーからrecent buildを使ってTitaniium Desktop 1.1 をインストールする必要があります。

The drillbit script lives under the Titanium Mobile repository at drillbit/drillbit.py. The script expects the MobileSDK zip to be built using scons before it is run. The zip is extracted into dist/mobilesdk and all tests are built from there.
drillbitスクリプトはTitanium Mobileレポジトリ下の drillbit/drillbit.py にあります。スクリプトは実行前にsconsを使ってビルドされたMobileSDK zipを要求します。zipはdist/mobilesdkに展開され、全てのテストはそこでビルドされます。

drillbit/drillbit.py can be run without arguments, but there are extra arguments that provide extended functionality and customization
drillbit/drillbit.py は引数なしで実行できますが、追加引数が存在し、拡張機能、カスタマイズ機能を提供します。


Drillbit Usage

./drillbit/drillbit.py [--platforms=PLATFORMS] [--tests-dir=DIR] [--results-dir=DIR] [--tests=TESTS] [platform specific args..]

    Common Arguments
    --platforms=PLATFORMS           Drillbitで実行するプラットフォームのリスト (default: android,iphone)
    --tests-dir=DIR                 DIRから追加テストをロードします。
    --results-dir=DIR               DIRにテスト結果(HTML & JSON)を出力
    --tests=TESTS                   実行するテストを(カンマ(,)で区切って)指定します。 

    UI Specific arguments:
    --autorun                       Drillbit開始後なるべく早くテスト実行を開始します。
    --autoclose                     全テスト実行後なるべく早くDirllbitを閉じます。
    --web-console                   (Drillbitのデバッグ用)Drillbit実行時にWeb / Javascript コンソールを表示

    iPhone Specific Arguments
    --iphone-version=DIR            ビルドするiPhone SDK のバージョン(default: 4.0)
    
    Android Specific Arguments
    --android-sdk=DIR               DIRからAndroid SDKをロード
    --android-version=VERSION       ビルドするAndroidプラットフォームのバージョン(default: 4)
    --android-force-build           テストが通過すると、テストハーネスがビルドします
    --android-device=DEVICE         でバイス引数をADBを通して渡します。 (default: -e)

For example, to only run the network.httpclient test suite for Android:
例)Andoridプラットフォームでnetwork.httpclinetテストのみを実行

./drillbit/drillbit.py --platforms=android --tests=network.httpclient