View on GitHub

Codeception.docs.ja

Codeception docs japanese translation

Download this project as a .zip file Download this project as a tar.gz file

コードカバレッジ

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

Codeceptionはバージョン1.5からコードカバレッジ用のツールを備えています。カバレッジを収集するためには xdebug が必要となります。.

コードカバレッジの例

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

設定

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

coverage:
    enabled: true

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

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

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

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

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

There is a shortcut if you don't need that complex filters: 複雑なフィルタが必要ない場合のショートカットがあります。

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

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

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

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

基本的なコードカバレッジは機能テストと単体テストで収集することができます。 もし上に書いた設定を行っているのであれば準備完了です。 必要なことは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)を介して実行している場合、テストされたコードに直接アクセスすることができないため、 カバレッジを収集することは簡単なことではありません。同様のことが、異なるノード上でテストされたスクリプトに対しても言えます。 これらのコードにアクセスするためには xdebugremote_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の設定を変更したい場合があるかもしれません(たとえばveryfypeerオプション) c3がウェブサーバー(ローカル、リモートのどちらであろうとも)に対してサービス要求をする方法を変更するには、coverage 設定の remotecontext_options` キーを使用します。

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

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

まとめ

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