txt: ## dist_zef-atroxaper-App-RaCoCo.md
  [![Ubuntu](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/ubuntu.yml)
  [![MacOS](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/macos.yml/badge.svg)](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/macos.yml)
  [![Windows](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/windows.yml/badge.svg)](https://github.com/atroxaper/raku-RaCoCo/actions/workflows/windows.yml)
  [![Coverage Status](https://coveralls.io/repos/github/atroxaper/raku-RaCoCo/badge.svg?branch=master)](https://coveralls.io/github/atroxaper/raku-RaCoCo?branch=master)
  
  # NAME
  
  `App::RaCoCo` - Raku Code Coverage tool.
  
  # SYNOPSIS
  
  ```
  > racoco -l
  [...]
  All tests successful.
  Files=16, Tests=114,  6 wallclock secs
  Result: PASS
  Coverage: 89.2%
  
  > racoco --fail-level=95
  [...]
  Coverage: 89.2%
  # exit code: 6
  
  > racoco --html --silent
  Visualisation: file://.racoco/report.html
  Coverage: 89.2%
  > browsername .racoco/report.html
  
  ```
  
  # INSTALLATION
  
  If you use zef, then `zef install App::RaCoCo`, or `pakku add App::RaCoCo` if you use Pakku.
  
  # DESCRIPTION
  
  `App::RaCoCo` provides the `racoco` application, which can be used to run tests and calculate code coverage.
  
  You may specify the following options:
  
  * **--exec** - command, which needs to be executed to run tests. For example, you may pass `--exec='prove --exec raku'` to use Perl's `prove` util instead of default `prove6`. Use `--/exec` option to not run tests and use coverage data from the previous run;
  * **-l** - short-cut for `--exec='prove6 -l'`;
  * **-I** - short-cut for `--exec='prove6 -I.'`;
  * **--lib** - path to directory with target source files (`'./lib'` by default);
  * **--raku-bin-dir** - path to directory with `raku` and `moar` binaries, which supposed to be used in the `--exec` (`$*EXECUTABLE.parent` by default);
  * **--fail-level** - integer number - if the coverage level will be less than it then `racoco` will exit with a non-zero exit code;
  * **--cache-dir** - path to directory where project related files racoco will be stored (`'./.racoco'` by default);
  * **--silent** - hide test result output;
  * **--append** - append the previous run result to the new one;
  * **--html** - produce a simple HTML page to visualize results. It is short-cut for `--reporter=html`;
  * **--color-blind** - use with `--html` option to make more readable colors than green/red pare. It is short-cut for `--reporter=html-color-blind`;
  * **--reporter** - name of a custom result reporter;
  * **--properties** - pass custom properties here;
  * **configuration-name** - name of section with properties in `racoco.ini` to use in tests (see below [CONFIGURATION FILE](#configuration-file))
  
  # NOTES
  
  * RaCoCo application works only with MoarVM backended Raku compiler;
  * It is common practice to not include `use lib 'lib'` line in test files. In a such case, we need to run tests with a command like `prove6 -l`. RaCoCo has a special short-cut option `-l` for you, then you do not need to write `racoco --exec='prove6 -l'`;
  * Unfortunately, the current Rakudo implementation may produce a little different coverage log from run to run. Probably, it is because of some runtime optimisations.
  
  # CONFIGURATION FILE
  
  Tests are a thing that it is customary to run frequently. If you run tests with a command more complicated than just `racoco -l`, then you will like the fact that you can write all the configurations to a special `racoco.ini` file. For example, you regularly run `racoco -l` and `racoco -l --silent --html --fail-level=82` before commit. Then you can create a `racoco.ini` file in the root directory of your project with the following content:
  
  ```
  exec = prove6 -l
  
  [commit]
  silent = true
  reporter = html
  fail-level = 82
  
  ```
  
  After that just run `racoco` regularly and `racoco commit` before commit. As an alternative for configuration file you can use environment variables with appropriate names, or `--property=name:value;name:value` command-line option, or a combination of them. The priority is: command-line arguments > `--property` option > environment variables > `racoco.ini` file.
  
  # CUSTOM REPORTERS
  
  In addition to the output of results to the console, Racoco supports additional reporters with the `--reporter` option. Examples of such reporters are `html` or `html-color-blind` which build a simple HTML page with results. Please look for other reporters in the [Ecosystem](https://raku.land/?q=racoco).
  
  ## Information for Developers
  
  A custom reporter must implement `App::Racoco::Report::Reporter` role, has full qualified name like `App::Racoco::Report::ReporterTheName` and live in `App::Racoco::Report::ReporterTheName` compilation unit (file). Then you can address to it through `--reporter=the-name`. For example, see `ReportHtmlColorBlind.rakumod`.
  
  # AUTHOR
  
  Mikhail Khorkov <atroxaper[at]cpan.org>
  
  Sources can be found at: [github](https://github.com/atroxaper/raku-RaCoCo). The new Issues and Pull Requests are welcome.
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2023 Mikhail Khorkov
  
  This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.
  