せっかく Gulp に乗り換えたので、Grunt でやってた単体テスト実行も乗り換えちゃう

Web アプリケーション開発における、クライアント側スクリプト実装の話。

AngularJS を使った Web アプリクライアント側実装について、以前の投稿にて、Gulp の採用によって TypeScript ソースに対応するソースマップ付きでの Bundle & Minify を達成した。
さらに前回の投稿にて AngularJS における依存性注釈の自動生成を達成した。

このように、今更感あるものの、Gulp 採用に伴う開発環境改善を加速中の今日この頃なのだが、さて、単体テストの話。

過去の投稿にて紹介したとおり、クライアント側スクリプトの単体テストを実現するにあたって、テストランナー環境として Grunt とそのプラグイン ( grunt-contrib-jasmine ) を使用していた。

しかしここへ来て、前述のとおり、Bundle & Minify, 依存性注釈の自動生成のために Gulp とそのプラグインを使用するようになった。

となると、すでに Gulp でいろいろタスク実装してるのに、単体テストのためだけに Grunt を併用するのもなんだかなぁ、と思うようになってきた。
お前は Gulp 派なのか Grunt 派なのか、どっちかはっきりしろよ、みたいな。

ということで、その程度の理由・動機ではあったのだけれども、とにかく、Gulp に乗り換えに伴う Grunt 脱却を図ることにした。

Gulp で JavaScript 単体テスト実行を実現するプラグインは?

乗り換えということで、grunt-contrib-jasmine で実現していたのと同じ環境を Gulp 上で再構築するには、どんな Gulp プラグインを採用するのがいいのかな、とネットでいろいろ検索。

そうやって情報収集しているうちに、Gulp のプラグインじゃなくて、
"karma" を使えばいいじゃん
ということがわかってきた。

"karma" とは、コマンドラインツールの名前。

実は "karma" の存在も以前から知っていた。

AngularJS を学習しはじめたときに、某書籍で「AngularJS 界隈では karma 使ってる事例あるよ」的なことが書かれてて、そこで "karma" なるものの存在を知った。

しかしその書籍からは "karma" とはなんなのかその本質がよく掴めなかった。
結果、自分の中では 「karma とは E2E テストの自動化に使う何からしい」という誤った認識で留まってしまっていた。

ところがこうして改めて、JavaScript 単体テストの実行環境を求めているうちに、ようやく見えてきたのだが、
karma って要するにテストランナーだったのですね。
※ほんっと、今更ですみません。

つまり、GUI 操作を伴う E2E テストに限らず、単体テストの実行にも普通に karma 使えるのだということがわかった。

ということで、karma を使った JavaScript 単体テストの実行環境を整えてみた。

karmaによるテスト実行環境の構築

npm パッケージのインストール

まずは必要となる下記 npm パッケージをプロジェクトにインストール。

1. karma の本体(コア機能)と、
2. ヘッドレスブラウザ (GUI を持たない、このようなテストや各種自動化を目的とした特殊な Web ブラウザ) である PhantomJS を karma から起動できるようにするためのランチャー、
3. および、単体テストフレームワークの Jasmine を krama 上で扱うためのアドイン
4. そして、単体テストフレームワーク Jasmine それ自体

> npm install --save-dev karma

> npm install --save-dev karma-phantomjs-launcher

> npm install --save-dev karma-jasmine

> npm-install --save-dev jasmine-core

なお、ヘッドレスブラウザ PhantomJS も、karma-phantomjs-launcher の依存関係解決により、プロジェクトにインストールされる。

ここでちょっと嬉しかったのは、Grunt のプラグイン (grunt-contrib-jasmine) では PhantomJS v.1.x でしか動作しなかったのだが、上記 karma-phantomjs-launcher では PhantomJS v.2.0 がインストールされること。

karma の構成ファイル「karma.conf.js」の作成

さて必要な npm パッケージのインストールが済んだら、karma に対し、どのようにテストを実行したらよいのかを示す設定ファイル「karma.conf.js」を新規作成して記述する。

下記のとおり karma コマンドを実行することで、コンソール上の対話形式で「karma.conf.js」を初期作成することができる。

>  .\node_modules\.bin\karma init

上記を実行すると、karma コマンドから、どのような構成にするかコンソール上での対話が始まる。
下図の要領でこれに応えて、karma.conf.js の初回生成を完遂させる。
こうして karma.conf.js ができたら、続けて下記要領で内容を編集して完成させる。

karma.conf.js は設定項目が多く見た目で怯みがちだが、特記すべき点に絞ると下記の要領となる。

module.exports = function(config) {

  config.set({

    // テストフレームワークに Jasmine を使う指定。

    frameworks: ['jasmine'],



    // テスト実行環境に読み込む JavaScript ファイルの指定。

    // 下記は自分のプロジェクトのフォルダ構成に基づく例。

    files: [

        // vendor

        'Scripts/jquery-2.2.4.js',

        'Scripts/angular.js',

        'Scripts/angular-mocks.js',

        // src

        'bundle.js',

        // spec

        '_spec/**/*Spec.js'

    ],



    // Visual Studio の出力ウィンドウで表示するため、

    // テスト進捗状況の表示は progress ではなく dots を指定。

    reporters: ['dots'],



    // Visual Studio の出力ウィンドウで表示するため、

    // コンソール出力はモノクロを指定。

    colors: false,



    // テスト実行に使うブラウザは PhantomJS を指定。

    browsers: ['PhantomJS'],



    // テストを実行するごとに処理終了させる指定。

    singleRun: true

  })

}

karma によるテストの実行

以上でお膳立てが整ったら、いよいよ実行である。

コマンドプロンプトにて

> .\node_modules\.bin\karma start karma.conf.js

というように、start コマンドと構成ファイル名 (= karma.conf.js) を引数に指定して karma コマンドを実行する。

すると

1. karma コマンドが動き出して karma.conf.js を読み込み、
2. これに記述されているとおり、PhantomJS を起動、単体テストを構成するコンテンツを読み込ませる
3. PhangtmJS は読み込まされたコンテンツ、すなわち jasmine ベースのテストコードを実行
   ( 但し PhantomJS はヘッドレスブラウザということもあり、とくに GUI/ウィンドウが現れたりすることはない )、
4. 最後に karma が結果をすくい上げてレポート表示

された。

バッチリである。

これで grunt-contrib-jasmine による単体テスト実行環境から karma ベースの環境に完全移行できた。
もう grunt は使っていないので、「npm uninstall grunt --save-dev」して大丈夫である。

なお、単体テストフレームワークは jasmine のまま変更しなかったので、既存の単体テストコードは一切変更せずに済んでいる。

さらにソースマップ読み込みも!

さらに、これは予想・期待していたものではなかったのだが、karma であれば、テスト失敗時のレポートなどで、
コンパイル元の TypeScript ソース行で該当箇所をレポートする
ように構成できることがわかった。

まず必要となるのは "karma-sourcemap-loader" という npm パッケージ。
これをプロジェクト構成に追加。

> npm install --save-dev karma-sourcemap-loader

次に、karma.conf.js 中にて、"プリプロセッサ" の指定に karma-sourcemap-loader を追加する。

...

preprocessors: {

  '**/*.js': ['sourcemap']

},

...

こうすることで、TypeScript のコンパイル時に同時生成したソースマップファイルが読み込まれ、テスト実行後のレポート表示において、TypeScript ソースコード上でのファイル名と行番号とで表示されるようになった。

テスト失敗が報告された JavaScript の該当行から、コンパイル元の TypeScript ソースコード上での該当行を人力作業で特定するのは、不可能ではないとはいえまずまずの労力を要する。
そんな非生産的な、機械で解決できるはずの課題が、実際のところ今日まで grunt-contrib-jasmine 環境では解決できていなかったのだから、こうしてこの課題が解決され、大変晴れ晴れしい気分になった。

改めて、karma をはじめ各種ソフトウェアプロダクトに貢献されている方々に感謝である。

おまけ

こうして構築した karma による単体テスト実行環境だが、この単体テストを実行するにあたり、自分の場合、コマンドプロンプトから直接の karma コマンド実行をしていない。

代わりに、npm を一段階挟んでいる。

つまり、packages.json 内に、karma 実行コマンドを記載しておいてある (下記)。

...

"scripts":{

  "test":"karma --silent --no-color start karma.conf.js"

}

...

こうしておくことで、「npm test」を実行することで単体テストが実行されるようになっている。

直接 karma を実行すればよいものを、わざわざ npm を経由しているのなぜか?
それは、自分の主たる開発環境が Visual Studio であることに由来している。

Visual Studio 上の設定で、Ctrl+R, Ctrl+J のキーコンビネーションが打鍵されると、「npm test」を実行して、結果を Visual Studio 内のウィンドウ (出力ウィンドウ) に表示するようにしてあるのだ。

そのため、npm 側で実際のテスト実行コマンドを隠蔽しておくと、

• 従来の gurunt-contrib-jasmine で構築されたプロジェクトでも、
• 今回新規構築した karma によるプロジェクトでも、

どちらでも共通の「npm test」でテストを実行できる。

すなわち、どのプロジェクトを Visual Studio で開いても、共通のキーボード操作 Ctrl+R, Ctrl+J でテストが実行される、という仕掛けである。

なお補足として、上記 package.json に記述した karma コマンドに記載のオプションスイッチだが、

• 「--silent」はテスト結果の表示上、よぶんなバナー表示などを抑止するもので、
• 「--no-color」は、Visual Studio の出力ウィンドウにテスト結果表示をリダイレクトしてる関係上、コンソールの色指定コードは表示を乱してしまうことから、カラー表示コードの出力を抑止するスイッチ

である。

Gist にサンプルコードあります

これまでの内容と、実際に動作している構成フィル類とを、下記 Gist に置いてある。

Jasmine による TypeScript/JavaScript 単体テストを実行する環境を作る - karma 編
https://gist.github.com/jsakamoto/e4a957821216c38cdb7e9e20ba17e569

こちらも適宜参照されるとよいかもしれない。

以上、ご参考までに。