|
| 1 | +--- |
| 2 | +layout: doc |
| 3 | +title: Codeception - Documentation |
| 4 | +--- |
| 5 | + |
| 6 | +## Code Coverage |
| 7 | + |
| 8 | +At some point you want to review which parts of your appliaction are tested well and which are not. |
| 9 | +Just for this case the [CodeCoverage](http://en.wikipedia.org/wiki/Code_coverage) is used. When you execute your tests to collect coverage report, |
| 10 | +you will receive statisitcs of all classes, methods, and lines triggered by these tests. |
| 11 | +The ratio between all lines in script and all touched lines is a main coverage criteria. In the ideal world you should get a 100% code coverage, |
| 12 | +but in reality 80% are just enough. And even 100% code coverage rate doesn't save you from fatal errors and crashes. |
| 13 | + |
| 14 | +**Codeception has CodeCoverage tools since 1.5. To collect coverage information `xdebug` is required**. |
| 15 | + |
| 16 | +Coverage data can be collected manually for local tests and remote tests. Remote tests may be executed on different node, |
| 17 | +or locally, but behind the web server. It may look hard to collect code coverage for Selenium tests or PhpBrowser tests. But Codeception |
| 18 | +supports remote codecoverage as well as local. |
| 19 | + |
| 20 | +### Configuration |
| 21 | + |
| 22 | +To enable codecoverge put these lines to the global configuration file `codeception.yml`: |
| 23 | + |
| 24 | +{% highlight yaml %} |
| 25 | + yml |
| 26 | +coverage: |
| 27 | + enabled: true |
| 28 | + |
| 29 | +{% endhighlight %} |
| 30 | + |
| 31 | +that's ok for now. But what files should be present in final coverage report? You can filter files by providing blacklist and whitelist filters. |
| 32 | + |
| 33 | +{% highlight yaml %} |
| 34 | + yml |
| 35 | +coverage: |
| 36 | + enabled: true |
| 37 | + whitelist: |
| 38 | + include: |
| 39 | + - app/* |
| 40 | + exclude: |
| 41 | + - app/cache/* |
| 42 | + blacklist: |
| 43 | + include: |
| 44 | + - app/controllers/* |
| 45 | + exclude: |
| 46 | + - app/cache/CacheProvider.php |
| 47 | + |
| 48 | + |
| 49 | +{% endhighlight %} |
| 50 | +What are whitelists and blacklists? |
| 51 | + |
| 52 | +* A **whitelist** is a list of files that should be included in report even they were not touched. |
| 53 | +* A **blacklist** is a list of files that should be excluded from report even they were touched. |
| 54 | + |
| 55 | +Pass an array of files or directory to include/exclude sections. The path ending with '*' matches the directory. |
| 56 | +Also you can use '*' mask in a file name, i.e. `app/models/*Model.php` to match all models. |
| 57 | + |
| 58 | +There is a shortcut if you don't need that complex filters: |
| 59 | + |
| 60 | +{% highlight yaml %} |
| 61 | + |
| 62 | +coverage: |
| 63 | + enabled: true |
| 64 | + include: |
| 65 | + - app/* |
| 66 | + exclude: |
| 67 | + - app/cache/* |
| 68 | + |
| 69 | +{% endhighlight %} |
| 70 | + |
| 71 | +These `include` and `exclude` options are to add or remove files from a whitelist. |
| 72 | + |
| 73 | +All these settings can be redefined for each suite in their config files. |
| 74 | + |
| 75 | +## Local CodeCoverage |
| 76 | + |
| 77 | +The basic codecoverage can be collected for functional and unit tests. |
| 78 | +If you performed configurations steps from above you are ready to go. |
| 79 | +All you need is to execute codeception with `--coverage` option. |
| 80 | +To generate a clover xml report or a tasty html report append also `--xml` and `--html` options. |
| 81 | + |
| 82 | +{% highlight yaml %} |
| 83 | + |
| 84 | +codecept run --coverage --xml --html |
| 85 | + |
| 86 | +{% endhighlight %} |
| 87 | + |
| 88 | +XML and HTML reports are stored to the `_logs` directory. The best way to review report is to open `index.html` from `tests/_logs/coverage` in your browser. |
| 89 | +XML clover reports are used by IDEs (like PHPStorm) or Conitinious Integration servers (Like Jenkins). |
| 90 | + |
| 91 | +## Remote CodeCoverage |
| 92 | + |
| 93 | +If you run your application via Webserver (Apache, Nginx, PHP WebServer) you don't have a direct access to tested code, |
| 94 | +so collecting coverage becomes a non-trivial task. The same goes to scripts that are tested on different node. |
| 95 | +To get access to this code you need `xdebug` installed with `remote_enable` option turned on. |
| 96 | +Codeception also requires a little spy to interact with your application. As your application run standalone, |
| 97 | +without even knowing it is being tested, a small file should be included in order to collecto coverage info. |
| 98 | + |
| 99 | +This file is called `c3.php` and is [available on GitHub](https://github.com/Codeception/c3). |
| 100 | +`c3.php` should be downloaded and included in your application in a very first line of it's from controller. |
| 101 | +By sending special headers Codeception will command your appliaction when to start codecoverage collection and when to stop it. |
| 102 | +After the suite is finished, a report will be stored and Codeception will grab it from your application. |
| 103 | + |
| 104 | +Please, follow installation instructions described in a [readme file](https://github.com/Codeception/c3). |
| 105 | + |
| 106 | +After the `c3.php` file is included in application you can start gather coverage. |
| 107 | +In case you execute your application locally there is nothing to be changed in config. |
| 108 | +All codecoverage reports will be collected as usual and marged afterwards. |
| 109 | +Think of it: Codeception runs remote coverage in the same way as local. |
| 110 | + |
| 111 | +It's never been easier to setup remote codecoverage for your application. In ay other framework. Really. |
| 112 | + |
| 113 | +But if you run tests on different server (or your webserver doesn't use code from current directory) a single option `remote` should be added to config. |
| 114 | +For example, let's turn on remote coverage for acceptance suite in `acceptance.suite.yml` |
| 115 | + |
| 116 | +{% highlight yaml %} |
| 117 | + |
| 118 | +coverage: |
| 119 | + enabled: true |
| 120 | + remote: true |
| 121 | + |
| 122 | +{% endhighlight %} |
| 123 | + |
| 124 | +In this case remote Code Coverage results won't be merged with local ones if this option is enabled. |
| 125 | +Merging is possible only in case a remote and local file have th same path. |
| 126 | +But in case of running tests on a remote server we are not sure of it. |
| 127 | + |
| 128 | +## Conclusion |
| 129 | + |
| 130 | +It's never been easier to setup local and remote code coverage. Just one config and one additional file to incldue! |
| 131 | +**With Codeception you can easily generate CodeCoverage reports for your Selenium tests** (or other acceptance or api tests). Mixing reports for `acceptance`, `functional`, and `unit` suites provides |
| 132 | +you the most complete information on which parts of your applications are tested and which are not. |
| 133 | + |
| 134 | + |
0 commit comments