An elixir library that reports test coverage statistics, with the option to post to coveralls.io service. It uses Erlang's cover to generate coverage information, and posts the test coverage results to coveralls.io through the json API.
Currently, it's under trial for travis-ci integration. coverage_sample is an example using from a project.
Add the following parameters.
test_coverage: [tool: ExCoveralls]in the project function.test_coverage: [test_task: "espec"]if you use Espec.:excoverallsin the deps function.
def project do
[ app: :excoveralls,
version: "1.0.0",
elixir: "~> 0.xx.yy",
deps: deps(Mix.env),
test_coverage: [tool: ExCoveralls]
]
end
defp deps do
[{:excoveralls, "~> 0.3", only: :test}]
endRun the MIX_ENV=test mix coveralls command to show coverage information on localhost.
This task locally prints out the coverage information. It doesn't submit the results to the server.
$ MIX_ENV=test mix coveralls
...
----------------
COV FILE LINES RELEVANT MISSED
100.0% lib/excoveralls/general.ex 28 4 0
75.0% lib/excoveralls.ex 54 8 2
94.7% lib/excoveralls/stats.ex 70 19 1
100.0% lib/excoveralls/poster.ex 16 3 0
95.5% lib/excoveralls/local.ex 79 22 1
100.0% lib/excoveralls/travis.ex 23 3 0
100.0% lib/mix/tasks.ex 44 8 0
100.0% lib/excoveralls/cover.ex 32 5 0
[TOTAL] 94.4%
----------------Specifying the --help option displays the options list for available tasks.
$ MIX_ENV=test mix coveralls --help
Usage: mix coveralls
Used to display coverage
-h (--help) Show helps for excoveralls mix tasks
Usage: mix coveralls.detail [--filter file-name-pattern]
Used to display coverage with detail
[--filter file-name-pattern] can be used to limit the files to be displayed in detail
Usage: mix coveralls.travis
Used to post coverage to Travis CI server
Usage: mix coveralls.post [options] [coveralls-token]
Used to post coverage from local server using a token.
The [coveralls-token] should be specified here or in the COVERALLS_REPO_TOKEN
environment variable.
-n (--name) Service name ('VIA' column at coveralls page)
-b (--branch) Branch name ('BRANCH' column at coveralls page)
-c (--committer) Committer name ('COMMITTER' column at coveralls page)
-m (--message) Commit message ('COMMIT' column at coveralls page)Specify mix coveralls.travis in the .travis.yml.
This task is for submiting the result to the coveralls server when Travis-CI build is executed.
language: erlang
otp_release:
- R16B
before_install:
- git clone https://github.com/elixir-lang/elixir
- cd elixir && make && cd ..
before_script: "export PATH=`pwd`/elixir/bin:$PATH"
script:
- "MIX_ENV=test mix do deps.get, compile, coveralls.travis"
Acquire the repository token of coveralls.io in advance, and run the mix coveralls.post command.
It is for submitting the result to coveralls server from localhost.
The token can be specified as a mix task argument, or as an environment variable (COVERALLS_REPO_TOKEN).
$ MIX_ENV=test mix coveralls.post [YOUR_TOKEN]
...
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 16958 100 64 100 16894 23 6330 0:00:02 0:00:02 --:--:-- 7644
{"message":"Job #xx.1","url":"https://coveralls.io/jobs/xxxx"}This task displays coverage information at the source-code level with colored text.
Green indicates a tested line, and red indicates lines which are not tested.
When reviewing many source files, pipe the output to the less program (with the -R option for color) to paginate the results.
$ MIX_ENV=test mix coveralls.detail | less -R
...
----------------
COV FILE LINES RELEVANT MISSED
100.0% lib/excoveralls/general.ex 28 4 0
...
[TOTAL] 94.4%
--------lib/excoveralls.ex--------
defmodule ExCoveralls do
@moduledoc """
Provides the entry point for coverage calculation and output.
This module method is called by Mix.Tasks.Test
...Also, displayed source code can be filtered by specifying arguments (it will be matched against the FILE column value). The following example lists the source code only for general.ex.
$ MIX_ENV=test mix coveralls.detail --filter general.ex
...
----------------
COV FILE LINES RELEVANT MISSED
100.0% lib/excoveralls/general.ex 28 4 0
...
[TOTAL] 94.4%
--------lib/excoveralls.ex--------
defmodule ExCoveralls do
@moduledoc """
Provides the entry point for coverage calculation and output.
This module method is called by Mix.Tasks.Test
...coveralls.json provides a setting for excoveralls.
The default coveralls.json file is stored in deps/excoveralls/lib/conf, and custom coveralls.json files can be placed in the mix project root. The custom definition is prioritized over the default one (if definitions in custom file are not found, then the definitions in the default file are used).
Stop words defined in coveralls.json will be excluded from the coverage calculation. Some kernal macros defined in Elixir are not considered "covered" by Erlang's cover library. It can be used for excluding these macros, or for any other reasons. The words are parsed as regular expression.
- treat_no_relevant_lines_as_covered
- By default, coverage for [files with no relevant lines] are displayed as 0% for aligning with coveralls.io behavior. But, if
treat_no_relevant_lines_as_coveredis set totrue, it will be displayed as 100%.
- By default, coverage for [files with no relevant lines] are displayed as 0% for aligning with coveralls.io behavior. But, if
{
"default_stop_words": [
"defmodule",
"defrecord",
"defimpl",
"def.+(.+\/\/.+).+do"
],
"custom_stop_words": [
],
"coverage_options": {
"treat_no_relevant_lines_as_covered": true
}
}- If mock library is used, it will show some warnings during execution.
- In case Erlang clashes at
mix coveralls, executingmix testin advance might avoid the error. - When erlang version 17.3 is used, an error message
(MatchError) no match of right hand side value: ""can be shown. Refer to issue #14 for the details.
- It might not work well on projects which handle multiple project (Mix.Project) files.
- Needs improvement on file-path handling.