Description

diff-cover |pypi-version| |conda-version| |build-status| ======================================================================================== Automatically find diff lines that need test coverage. Also finds diff lines that have violations (according to tools such as pycodestyle, pyflakes, flake8, or pylint). This is used as a code quality metric during code reviews. Overview -------- Diff coverage is the percentage of new or modified lines that are covered by tests. This provides a clear and achievable standard for code review: If you touch a line of code, that line should be covered. Code coverage is *every* developer's responsibility! The ``diff-cover`` command line tool compares an XML coverage report with the output of ``git diff``. It then reports coverage information for lines in the diff. Currently, ``diff-cover`` requires that: - You are using ``git`` for version control. - Your test runner generates coverage reports in Cobertura, Clover or JaCoCo XML format, or LCov format. Supported XML or LCov coverage reports can be generated with many coverage tools, including: - Cobertura__ (Java) - Clover__ (Java) - JaCoCo__ (Java) - coverage.py__ (Python) - JSCover__ (JavaScript) - lcov__ (C/C++) __ http://cobertura.sourceforge.net/ __ http://openclover.org/ __ https://www.jacoco.org/ __ http://nedbatchelder.com/code/coverage/ __ http://tntim96.github.io/JSCover/ __ https://ltp.sourceforge.net/coverage/lcov.php ``diff-cover`` is designed to be extended. If you are interested in adding support for other version control systems or coverage report formats, see below for information on how to contribute! Installation ------------ To install the latest release: .. code:: bash pip install diff-cover To install the development version: .. code:: bash git clone https://github.com/Bachmann1234/diff-cover.git cd diff-cover poetry install poetry shell Getting Started --------------- 1. Set the current working directory to a ``git`` repository. 2. Run your test suite under coverage and generate a [Cobertura, Clover or JaCoCo] XML report. For example, using `pytest-cov`__: .. code:: bash pytest --cov --cov-report=xml __ https://pypi.org/project/pytest-cov This will create a ``coverage.xml`` file in the current working directory. **NOTE**: If you are using a different coverage generator, you will need to use different commands to generate the coverage XML report. 3. Run ``diff-cover``: .. code:: bash diff-cover coverage.xml This will compare the current ``git`` branch to ``origin/main`` and print the diff coverage report to the console. You can also generate an HTML, JSON or Markdown version of the report: .. code:: bash diff-cover coverage.xml --format html:report.html diff-cover coverage.xml --format json:report.json diff-cover coverage.xml --format markdown:report.md diff-cover coverage.xml --format html:report.html,markdown:report.md Multiple XML Coverage Reports ------------------------------- In the case that one has multiple xml reports form multiple test suites, you can get a combined coverage report (a line is counted as covered if it is covered in ANY of the xml reports) by running ``diff-cover`` with multiple coverage reports as arguments. You may specify any arbitrary number of coverage reports: .. code:: bash diff-cover coverage1.xml coverage2.xml Quality Coverage ----------------- You can use diff-cover to see quality reports on the diff as well by running ``diff-quality``. .. code :: bash diff-quality --violations=<tool> Where ``tool`` is the quality checker to use. Currently ``pycodestyle``, ``pyflakes``, ``flake8``, ``pylint``, ``checkstyle``, ``checkstylexml``, ``ruff.check``, ``clang`` are supported, but more checkers can (and should!) be supported. See the section "Adding `diff-quality`` Support for a New Quality Checker". NOTE: There's no way to run ``findbugs`` from ``diff-quality`` as it operating over the generated java bytecode and should be integrated into the build framework. Like ``diff-cover``, HTML, JSON or Markdown reports can be generated with .. code:: bash diff-quality --violations=<tool> --format html:report.html diff-quality --violations=<tool> --format json:report.json diff-quality --violations=<tool> --format markdown:report.md diff-quality --violations=<tool> --format html:report.html,markdown:report.md If you have already generated a report using ``pycodestyle``, ``pyflakes``, ``flake8``, ``pylint``, ``checkstyle``, ``checkstylexml``, or ``findbugs`` you can pass the report to ``diff-quality``. This is more efficient than letting ``diff-quality`` re-run ``pycodestyle``, ``pyflakes``, ``flake8``, ``pylint``, ``checkstyle``, or ``checkstylexml``. .. code:: bash # For pylint < 1.0 pylint -f parseable > pylint_report.txt # For pylint >= 1.0 pylint --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" > pylint_report.txt