ExCoveralls Documentation

To use ExCoveralls, you must add it to your project's dependencies and configure the test_coverage and preferred_cli_env keys in your mix.exs file.

Dependency Setup

Add :excoveralls to your deps function, typically restricted to the :test environment:

defp deps do
  [
    {:excoveralls, "~> 0.18", only: :test}
  ]
end

Configuration Options

In your project function, you can use the following keys:

• test_coverage: [tool: ExCoveralls]: Enables ExCoveralls for coverage reporting.
• test_coverage: [tool: ExCoveralls, export: "cov"]: Enables reporting and exports data to cover/cov.coverdata.
• test_coverage: [tool: ExCoveralls, test_task: "espec"]: Use this if you are using Espec instead of the default ExUnit.
• preferred_cli_env: [coveralls: :test]: (Optional) Allows you to skip specifying MIX_ENV=test when running mix coveralls tasks by setting the default environment.
• Application.put_env(:excoveralls, :base_path, "/path/to/root"): (Optional) Explicitly sets the application root path. By default, this is the directory containing mix.exs.

def project do
  [
    app: :excoveralls,
    version: "1.0.0",
    elixir: "~> 1.0.0",
    deps: deps(),
    test_coverage: [tool: ExCoveralls],
    preferred_cli_env: [
      coveralls: :test,
      "coveralls.detail": :test,
      "coveralls.post": :test,
      "coveralls.html": :test,
      "coveralls.cobertura": :test
    ]
  ]
end

defp deps do
  [
    {:excoveralls, "~> 0.18", only: :test}
  ]
end

The coverage_options object in coveralls.json allows fine-tuning of the coverage engine:

• treat_no_relevant_lines_as_covered (boolean): If true, files with no relevant lines show 100% coverage instead of 0%.
• output_dir (string): The directory for HTML reports. Defaults to cover/.
• template_path (string): Custom path for HTML report templates.
• minimum_coverage (number 0-100): If the coverage falls below this threshold, mix coveralls and mix coveralls.html will exit with status code 1 (useful for CI).
• html_filter_full_covered (boolean): If true, files with 100% coverage are hidden from the HTML report.
• floor_coverage (boolean): If false, coverage values are ceiled instead of floored.
• xml_base_dir (string): Custom path for XML reports.

{
  "coverage_options": {
    "treat_no_relevant_lines_as_covered": true,
    "output_dir": "cover/",
    "template_path": "custom/path/to/template/",
    "minimum_coverage": 90,
    "xml_base_dir": "custom/path/for/xml/reports/",
    "html_filter_full_covered": true
  }
}

ExCoveralls uses a coveralls.json file for configuration. You can place a custom coveralls.json in your Mix project root to override the default settings located in deps/excoveralls/lib/conf. If a key is missing in your custom file, the default value is used.

Stop Words

Use default_stop_words or custom_stop_words to define regular expressions for words that should be excluded from coverage calculations (e.g., certain Elixir kernel macros).

Exclude Files

Use the skip_files key to provide an array of file paths (as Elixir regex strings) to ignore from coverage.

Note for Umbrella Projects: skip_files in the umbrella root does not work for individual apps. To exclude files within a specific app, create a coveralls.json at the root of that specific app's folder. Paths should be relative to that app's folder.

Terminal Report Output

Customize how the report appears in your terminal using terminal_options:

• file_column_width: Sets the column width for file names.
• print_files: Set to false to show only the total coverage summary without the per-file table.

{
  "skip_files": [
    "folder_to_skip",
    "folder/file_to_skip.ex"
  ],
  "terminal_options": {
    "file_column_width": 40,
    "print_files": false
  }
}

The following options are common across most coveralls mix tasks:

• -o, --output-dir: Write coverage information to a specific directory.
• -u, --umbrella: Show overall coverage for an umbrella project.
• -v, --verbose: Show the JSON string used for posting.
• --subdir: Add a prefix to file paths. Use this if your source files reside in a subfolder of the git repo (e.g., if your file is test.ex but its relative path in the repo is src/lib/test.ex, use src/lib).
• --rootdir: Strip this path from file paths to resolve relative paths. This must be the exact path to your git repo's root on the CI environment.
• --flagname: Set the job flag name shown in the Coveralls UI.
• --import-cover: Directory from which to import .coverdata files to add to the report.

To see the full list of options, run mix coveralls --help.

Usage: mix coveralls <Options>
  Used to display coverage

  <Options>
    -h (--help)         Show helps for excoveralls mix tasks

    Common options across coveralls mix tasks

    -o (--output-dir)   Write coverage information to output dir.
    -u (--umbrella)     Show overall coverage for umbrella project.
    -v (--verbose)      Show json string for posting.
    --subdir            Git repo sub directory...
    --rootdir           This will be stripped from the file path...
    --flagname          Job flag name which will be shown in the Coveralls UI
    --import-cover      Directory from where '.coverdata' files should be imported...