simplecov-ruby / simplecov

SimpleCov [ ][Continuous Integration] ========= **Code coverage for Ruby** • [Source Code] • [API documentation] • [Changelog] • [Rubygem] • [Continuous Integration] [Coverage]: https://docs.ruby-lang.org/en/master/Coverage.html "API doc for Ruby's Coverage library" [Source Code]: https://github.com/simplecov-ruby/simplecov "Source Code @ GitHub" [API documentation]: http://rubydoc.info/gems/simplecov/frames "RDoc API Documentation at Rubydoc.info" [Configuration]: http://rubydoc.info/gems/simplecov/SimpleCov/Configuration "Configuration options API documentation" [Changelog]: https://github.com/simplecov-ruby/simplecov/blob/main/CHANGELOG.md "Project Changelog" [Rubygem]: http://rubygems.org/gems/simplecov "SimpleCov @ rubygems.org" [Continuous Integration]: https://github.com/simplecov-ruby/simplecov/actions?query=workflow%3Astable "SimpleCov is built around the clock by github.com" [Dependencies]: https://gemnasium.com/simplecov-ruby/simplecov "SimpleCov dependencies on Gemnasium" [simplecov-html]: https://github.com/simplecov-ruby/simplecov-html "SimpleCov HTML Formatter Source Code @ GitHub" SimpleCov is a code coverage analysis tool for Ruby. It uses [Ruby's built-in Coverage][Coverage] library to gather code coverage data, but makes processing its results much easier by providing a clean API to filter, group, merge, format, and display those results, giving you a complete code coverage suite that can be set up with just a couple lines of code. SimpleCov/Coverage track covered ruby code, gathering coverage for common templating solutions like erb, slim and haml is not supported. In most cases, you'll want overall coverage results for your projects, including all types of tests, Cucumber features, etc. SimpleCov automatically takes care of this by caching and merging results when generating reports, so your report actually includes coverage across your test suites and thereby gives you a better picture of blank spots. The official formatter of SimpleCov is packaged as a separate gem called [simplecov-html], but will be installed and configured automatically when you launch SimpleCov. If you're curious, you can find it [on GitHub, too][simplecov-html]. Contact *Code and Bug Reports* • Issue Tracker • See CONTRIBUTING for how to contribute along with some common problems to check out before creating an issue. *Questions, Problems, Suggestions, etc.* • Mailing List "Open mailing list for discussion and announcements on Google Groups" Getting started --------------- • Add SimpleCov to your and : • Load and launch SimpleCov **at the very top** of your (*or , , cucumber , or whatever your preferred test framework uses*): **Note:** If SimpleCov starts after your application code is already loaded (via ), it won't be able to track your files and their coverage! The **must** be issued **before any of your application code is required!** This is especially true if you use anything that keeps your tests application loaded like spring, check out the **spring section**. SimpleCov must be running in the process that you want the code coverage analysis to happen on. When testing a server process (e.g. a JSON API endpoint) via a separate test process (e.g. when using Selenium) where you want to see all code executed by the , and not just code executed in your actual test files, you need to require SimpleCov in the server process. For rails for instance, you'll want to add something like this to the top of , but below the "shebang" line ( ) and after config/boot is required: • Run your full test suite to see the percent coverage that your application has. • After running your tests, open in the browser of your choice. For example, in a Mac Terminal, run the following command from your application's root directory: in a debian/ubuntu Terminal, **Note:** This guide can help if you're unsure which command your particular operating system requires. • Add the following to your file to ensure that coverage results are not tracked by Git (optional): If you're making a Rails application, SimpleCov comes with built-in configurations (see below for information on profiles) that will get you started with groups for your Controllers, Models and Helpers. To use it, the first two lines of your test_helper should be like this: Example output **Coverage results report, fully browsable locally with sorting and much more:** **Source file coverage details view:** Use it with any framework! Similarly to the usage with Test::Unit described above, the only thing you have to do is to add the SimpleCov config to the very top of your Cucumber/RSpec/whatever setup file. Add the setup code to the **top** of (for Cucumber) or (for RSpec). Other test frameworks should work accordingly, whatever their setup file may be: You could even track what kind of code your UI testers are touching if you want to go overboard with things. SimpleCov does not care what kind of framework it is running in; it just looks at what code is being executed and generates a report about it. Notes on specific frameworks and test utilities For some frameworks and testing tools there are quirks and problems you might want to know about if you want to use SimpleCov with them. Here's an overview of the known ones: Framework Notes Issue parallel_tests As of 0.8.0, SimpleCov should correctly recognize parallel_tests and supplement your test suite names with their corresponding test env numbers. SimpleCov locks the resultset cache while merging, ensuring no race conditions occur when results are merged. #64 & #185 knapsack_pro To make SimpleCov work with Knapsack Pro Queue Mode to split tests in parallel on CI jobs you need to provide CI node index number to the SimpleCov.command_name in KnapsackPro::Hooks::Queue.before_queue hook. Tip RubyMine The RubyMine IDE has built-in support for SimpleCov's coverage reports, though you might need to explicitly set the output root using #95 Spo…