Permalink
Newer
Older
100644 172 lines (115 sloc) 7.42 KB
Dec 17, 2015 @nno BIG: major refactoring
1 # MOcov [![Build Status](https://travis-ci.org/MOcov/MOcov.svg?branch=master)](https://travis-ci.org/MOcov/MOcov)
2
3 MOcov is a coverage report generator for Matlab and GNU Octave.
4
Jan 26, 2016 @nno DOC: explain some limitations
5
Dec 17, 2015 @nno BIG: major refactoring
6 ### Features
7
8 - Runs on both the [Matlab] and [GNU Octave] platforms.
Jan 26, 2016 @nno DOC: explain 'file' method better
9 - Can be used directly with continuous integration services, such as [coveralls.io] and [Shippable].
10 - Integrates with [MOxUnit], a unit test framework for Matlab and GNU Octave.
Jan 26, 2016 @nno DOC: more info in README
11 - Supports the Matlab profiler.
12 - Writes coverage reports in HTML, JSON and XML formats.
Dec 17, 2015 @nno BIG: major refactoring
13 - Distributed under the MIT license, a permissive free software license.
14
15
16 ### Installation
17
18 - Using the shell (requires a Unix-like operating system such as GNU/Linux or Apple OSX):
19
20 ```bash
21 git clone https://github.com/MOcov/MOcov.git
22 cd MOcov
23 make install
24 ```
Jan 26, 2016 @nno DOC: explain 'file' method better
25 This will add the MOcov directory to the Matlab and/or GNU Octave search path. If both Matlab and GNU Octave are available on your machine, it will install MOcov for both.
Dec 17, 2015 @nno BIG: major refactoring
26
27 - Manual installation:
28
Jan 26, 2016 @nno DOC: explain 'file' method better
29 + Download the zip archive from the [MOcov] website.
Dec 17, 2015 @nno BIG: major refactoring
30 + Start Matlab or GNU Octave.
Jan 26, 2016 @nno DOC: explain 'file' method better
31 + On the Matlab or GNU Octave prompt, `cd` to the `MOcov` root directory, then run:
Dec 17, 2015 @nno BIG: major refactoring
32
33 ```matlab
34 cd MOcov % cd to MOcov subdirectory
35 addpath(pwd) % add the current directory to the Matlab/GNU Octave path
36 savepath % save the path
37 ```
38
Jan 26, 2016 @nno DOC: explain some limitations
39
Jan 26, 2016 @nno DOC: explain 'file' method better
40 ### Determining coverage
Dec 17, 2015 @nno BIG: major refactoring
41
Jan 26, 2016 @nno DOC: explain 'file' method better
42 Coverage can be determined for evaluating a single expression or evaluation of a single function handle; for typical use cases this invokes running a test suite.
Dec 17, 2015 @nno BIG: major refactoring
43
Jan 26, 2016 @nno DOC: explain 'file' method better
44 There are two methods to generate coverage while evaluating such an expression or function handle:
45
Jan 27, 2016 @nno DOC: avoid markdown to be interpreted as code literal
46 1. the 'file' method (default)
47
Jan 26, 2016 @nno DOC: explain 'file' method better
48 - Coverage information is stored internally by the function `mocov_line_covered`, which keeps this information through the use of persistent variables. Initially the coverage information is reset to being empty.
49 - This method considers all files in a directory (and its subdirectories).
50 - A temporary directory is created where modified versions of each file is stored.
51 - Prior to evaluting the expression or function handle, for each file, MOcov determines which of its lines can be executed. Each line that can be executed is prefixed by a call to `mocov_line_covered`, which cause it to update internal state to record the filename and line number that was executed, and the result stored in the temporary directory.
52 - The search path is updated to include the new temporary directory.
53
54 After evaluating the expression or function handle, the temporary directory is deleted and the search path restored. Line coverage information is then extracted from the internal state of `mocov_line_covered`.
55
56 This method runs on both GNU Octave and Matlab, but is typically slow.
Dec 17, 2015 @nno BIG: major refactoring
57
Jan 27, 2016 @nno DOC: avoid markdown to be interpreted as code literal
58 2. the 'profile' method
Jan 27, 2016 @nno DOC: explain coverage methods better
59 - It uses the Matlab profiler.
60 - This method runs on Matlab only (not on GNU Octave), but is generally faster.
Dec 17, 2015 @nno BIG: major refactoring
61
Jan 26, 2016 @nno DOC: explain some limitations
62
Dec 17, 2015 @nno BIG: major refactoring
63 ### Use cases
64
65 Typical use cases for MOcov are:
66
Jan 26, 2016 @nno DOC: explain use cases better
67 - Locally run code with coverage for code in a unit test framework on GNU Octave or Matlab. Use
Dec 17, 2015 @nno BIG: major refactoring
68
69 ```matlab
70 mocov('-cover','path/with/code',...
71 '-expression','run_test_command',...
72 '-cover_json_file','coverage.json',...
73 '-cover_xml_file','coverage.xml',...
74 '-cover_html_dir','coverage_html',
75 '-method','file');
76 ```
77
Jan 26, 2016 @nno DOC: more info in README
78 to generate coverage reports for all files in the `'path/with/code'` directory when `running eval('run_test_command')`. Results are stored in JSON, XML and HTML formats.
Dec 17, 2015 @nno BIG: major refactoring
79
Jan 26, 2016 @nno DOC: explain use cases better
80 - As a specific example of the use case above, when using the [MOxUnit] unit test platform such tests can be run as
Dec 17, 2015 @nno BIG: major refactoring
81
Jan 26, 2016 @nno DOC: more info in README
82 ```matlab
Dec 17, 2015 @nno BIG: major refactoring
83 success=moxunit_runtests('path/with/tests',...
84 '-with_coverage',...
85 '-cover','/path/with/code',...
86 '-cover_xml_file','coverage.xml',...
87 '-cover_html_dir','coverage_html');
88 ```
89
Jan 26, 2016 @nno DOC: explain use cases better
90 where `'path/with/tests'` contains unit tests. In this case, `moxunit_runtests` will call the `mocov` function to generate coverage reports.
Dec 17, 2015 @nno BIG: major refactoring
91
Jan 26, 2016 @nno DOC: more info in README
92 - On the Matlab platform, results from `profile('info')` can be stored in JSON, XML or HTML formats directly. In the following:
93
94 ```matlab
95 % enable profiler
96 profile on;
97
98 % run code for which coverage is to be determined
99 <your code here>
100
101 % write coverage based on profile('info')
102 mocov('-cover','path/with/code',...
103 '-profile_info',...
104 '-cover_json_file','coverage.json',...
105 '-cover_xml_file','coverage.xml',...
Jan 26, 2016 @nno DOC: explain use cases better
106 '-cover_html_dir','coverage_html');
Jan 26, 2016 @nno DOC: more info in README
107 ```
108
109 coverage results are stored in JSON, XML and HTML formats.
110
Jan 26, 2016 @nno DOC: explain 'file' method better
111 - Use with continuous integration service, such as [Shippable] or [travis-ci] combined with [coveralls.io]. See the [travis.yml configuration file] in the [MOxUnit] project for an example.
Dec 17, 2015 @nno BIG: major refactoring
112
113
114 ### Use with travis-ci and Shippable
Jan 26, 2016 @nno DOC: explain 'file' method better
115 MOcov can be used with the [Travis-ci] and [Shippable] services for continuous integration testing. This is achieved by setting up a `travis.yml` file. Due to recursiveness issues, MOcov cannot use these services to generate coverage reports for itself; for an example in the related [MOxUnit] project, see the [travis.yml configuration file] file.
Dec 17, 2015 @nno BIG: major refactoring
116
Jan 26, 2016 @nno DOC: explain some limitations
117
Dec 17, 2015 @nno BIG: major refactoring
118 ### Compatibility notes
119 - Because GNU Octave 3.8 and 4.0 do not support `classdef` syntax, 'old-style' object-oriented syntax is used for the class definitions.
120
121
Jan 26, 2016 @nno DOC: explain some limitations
122 ### Limitations
123 - The 'file' method uses a very simple parser, which may not work as expected in all cases.
124 - Currently there is only support to generate coverage reports for files in a single directory (and its subdirectory).
125
126
Dec 17, 2015 @nno BIG: major refactoring
127 ### Contact
128 Nikolaas N. Oosterhof, nikolaas dot oosterhof at unitn dot it
129
130
Feb 26, 2016 @nno ACK: Thank #Scott Lowe# for his contributions
131 ### Contributions
Dec 25, 2016 @nno ACK: add #Anderson Bravalheri# to REEADME contributions
132 - Thanks to Scott Lowe and Anderson Bravalheri for their contributions.
Feb 26, 2016 @nno ACK: Thank #Scott Lowe# for his contributions
133
134
Dec 17, 2015 @nno BIG: major refactoring
135 ### License
136
137 (The MIT License)
138
May 8, 2017 @nno ENH: support for "hash" function in more recent version of Octave
139 Copyright (c) 2015-2017 Nikolaas N. Oosterhof
Dec 17, 2015 @nno BIG: major refactoring
140
141 Permission is hereby granted, free of charge, to any person obtaining
142 a copy of this software and associated documentation files (the
143 "Software"), to deal in the Software without restriction,
144 including without limitation the rights to use, copy, modify, merge,
145 publish, distribute, sublicense, and/or sell copies of the Software,
146 and to permit persons to whom the Software is furnished to do so,
147 subject to the following conditions:
148
149 The above copyright notice and this permission notice shall be
150 included in all copies or substantial portions of the Software.
151
152 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
153 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
154 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
155 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
156 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
157 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
158 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
159
160
161
162 [GNU Octave]: http://www.gnu.org/software/octave/
163 [Matlab]: http://www.mathworks.com/products/matlab/
164 [MOxUnit]: https://github.com/MOxUnit/MOxUnit
Jan 27, 2016 @nno DOC: add URL for MOcov
165 [MOcov]: https://github.com/MOcov/MOcov
Dec 17, 2015 @nno BIG: major refactoring
166 [MOxUnit .travis.yml]: https://github.com/MOxUnit/MOxUnit/blob/master/.travis.yml
167 [Travis-ci]: https://travis-ci.org
Jan 26, 2016 @nno DOC: more info in README
168 [coveralls.io]: https://coveralls.io/
Jan 27, 2016 @nno DOC: use proper link to .travis.yml file
169 [travis.yml configuration file]: https://github.com/MOxUnit/MOxUnit/blob/master/.travis.yml
Dec 17, 2015 @nno BIG: major refactoring
170 [Shippable]: https://shippable.com
171