コードカバレッジ

あるタイミングでアプリケーションのどの箇所がテストされていて、どの箇所がテストされていないのか確認したくなると思います。 そのような状況にコードカバレッジが使われます。 カバレッジレポートを収集するためにテストを実行すると、そのテストによって実行されたすべてのクラス、メソッド、そして行の統計情報を取得します。 スクリプトの全行数と通過した行数との比率が、主要なカバレッジ基準となります。理想論では100%のカバレッジを取得する必要がありますが、実際には80%で十分でしょう。なぜなら、100%のカバレッジであったとしても致命的なエラーやクラッシュを防ぐことができないからです。

カバレッジを収集するためにはxdebugが必要です。

カバレッジデータはローカルとリモートの両方のテストのために手動で収集することができます。 リモートのテストは、異なるノード上またはローカルのWebサーバーを利用して実行可能です。 SeleniumやPhpBrowserによるテストはコードカバレッジを収集するのは難しいように見えるかもしれませんが、Codeceptionはローカルと同じようにリモートのコードカバレッジをサポートしています。

設定

コードカバレッジを有効にするためには次の内容をグローバル設定ファイルcodeception.ymlに設定します。

coverage:
    enabled: true

いまはこれで大丈夫ですが、最終的なカバレッジレポートにはどのファイルが表示されるべきなのでしょうか？次のように、ブラックリストとホワイトリストのフィルターを提供することで、ファイルをフィルタリングすることができます。

coverage:
    enabled: true
    whitelist:
        include:
            - app/*
        exclude:
            - app/cache/*
    blacklist:
        include:
            - app/controllers/*
        exclude:
            - app/cache/CacheProvider.php

ホワイトリストとブラックリストはなんでしょうか？

• whitelist 通過しなかったとしてもレポートに含まれるべきファイルの一覧です
• blacklist 通過したとしてもレポートから除外すべきファイルの一覧です

include/excludeセクションにファイルまたはディレクトリーの配列を渡します。'*'で終わるパスはディレクトリーにマッチします。 また、'*'マスクをファイル名に使用することができます。たとえば、app/models/*Model.phpはすべてのモデルにマッチします。

複雑なフィルターが必要ない場合のショートカットがあります：

coverage:
    enabled: true
    include:
        - app/*
    exclude:
        - app/cache/*

このincludeとexcludeオプションはホワイトリストにファイルを追加または削除するためのものです。

以上のすべての設定は各テストスイートの設定ファイルにて再定義することができます。

ローカルコードカバレッジ

基本的なコードカバレッジは機能テストと単体テストで収集することができます。 もし上に書いた設定を行っているのであれば準備完了です。 必要なことはCodeceptionを--coverageオプションとともに実行することです。

CloverのXMLレポートや良い感じのHTMLレポートを生成するためには、--coverage-xmlと--coverage-htmlのオプションについても追加します。

codecept run --coverage --coverage-xml --coverage-html

XMLとHTMLレポートは_outputディレクトリーに格納されます。レポートを確認するための一番の方法は、tests/_output/coverageディレクトリーからindex.htmlをブラウザーで開くことです。 CloverのXMLレポートはPHPStormのようなIDEやJenkinsのような継続的インテグレーションサーバーで利用されます。

リモートコードカバレッジ

ローカルサーバー

もしアプリケーションをウェブサーバー（Apache, Nginx, PHP WebServer）を介して実行している場合、テストされたコードに直接アクセスすることができないため、 カバレッジを収集することは簡単なことではありません。同様のことが、異なるノード上でテストされたスクリプトに対しても言えます。 これらのコードにアクセスするためにはxdebugをremote_enableオプションを有効にしてインストールする必要があります。 Codeceptionもまた、アプリケーションとやり取りするためのちょっとしたスパイを必要とします。 スタンドアローンでアプリケーションを実行する際に、テストされているかどうかに関わらず、コードカバレッジ情報を収集するために小さなファイルをインクルードしてください。

このファイルはc3.phpと呼ばれ、GitHubから利用可能です。 c3.phpをダウンロードし、アプリケーションのコントローラーの最初でインクルードしてください。 特別なヘッダー情報を送信することにより、Codeceptionはアプリケーションに対して、いつコードカバレッジの収集を開始し、いつ終了するか命令します。 テストスイートが終了した後、レポートが出力され、Codeceptionはアプリケーションからそれを取得します。

インストール方法はreadme fileの説明に従ってください。

c3への接続のために、CodeceptionはPhpBrowserやWebDriverモジュールのURL設定を利用しますが、 c3.phpがインクルードされるインデックスファイルのURLをc3_urlパラメーターにより明示的に指定することができます。

coverage:
    # url of file which includes c3 router.
    c3_url: 'http://127.0.0.1:8000/index-test.php/'

c3.phpがアプリケーションにインクルードされたのち、カバレッジの収集を開始することができます。 ローカルでアプリケーションを実行する場合に変更となる設定はありません。 すべてのコードカバレッジレポートは普段どおり収集され、その後マージされます。 考えてみてください、Codeceptionはローカルと同じようにリモートカバレッジを実行できるのです。

リモートサーバー

もしテストを異なるサーバー上で実行している場合（もしくはウェブサーバーがカレントディレクトリーのコードを使用していない場合）、設定ファイルにremoteオプションを追加してください。 たとえば、受け入れテストでのリモートカバレッジをacceptance.suite.ymlにて有効にしてみます。

coverage:
    remote: true

このオプションが有効となった場合、リモートコードカバレッジの結果はローカルのものとマージされません。 リモートとローカルのファイル群が同じパス上に存在する場合のみマージは行われます。 けれども、リモートサーバー上でテストを行う場合、同じパス上に存在するかどうかはわかりません。

リモートサーバーからのコードカバレッジの結果はtests/_outputに保存されます。すでに述べた理由により、コンソールにはコードカバレッジの結果が表示されないことに注意してください。ローカルとリモートの結果はマージされませんし、コンソールにはローカルのコードカバレッジの結果が表示されます。

リモートコンテキストオプション

HTMLレポートの生成にはデフォルトのタイムアウト30秒よりも少し時間がかかることがあります。また、SSLの設定を変更したい場合があるかもしれません（たとえばverifypeerオプション）。 c3がウェブサーバー（ローカル、リモートのどちらであろうとも）に対してサービス要求をする方法を変更するには、coverage設定の`remotecontext_options`キーを使用します。

coverage:
    remote_context_options:
        http:
            timeout: 60
        ssl:
            verify_peer: false

コンテキストオプションについてはphp.netのドキュメントに良くまとまっています。

まとめ

ローカルとリモートのコードカバレッジ設定はこれまでになく簡単です。たった1つの設定を行い、1ファイルをインクルードするだけです！ Codeceptionを使えばSeleniumテストのコードカバレッジレポートを簡単に生成することができます（他の受け入れテストやAPIテストについても）。acceptance、functional、そしてunitの各スイートが統合されたレポートは、アプリケーションのどの箇所がテストされていて、どの箇所がテストされていないのか、最も完全な情報を提供します。