dbt-coverage
One-stop-shop for docs and test coverage of dbt projects.
Why do I need something like this?
dbt-coverage is to dbt what coverage.py and interrogate are to Python.
It is a single CLI tool which checks your dbt project for missing documentation and tests.
Keeping documentation and tests close to the actual SQL code that generates the final model is one of the best design choices of dbt. It ensures documentation is actually useful and tests are actually used. But how do you make adding those a habit in your dbt project?
That is exactly where dbt-coverage comes in. It will
- Give you a better sense of the level of documentation and test coverage in your project;
- Help your CI/CD pipeline make sure new changes include documentation and tests;
- Let you quickly assess the documentation and tests of a new
dbtproject you get your hands on.
Still not convinced? Here are some more features:
-
✨ zero-config: just install it and run it, there is nothing to set up -
🏁 minimal dependences: the only dependencies areclick(already installed withdbt) andtyper -
📦 very small: at ~480 SLOC, you can easily validate it works as advertised
Installation
pip install dbt-coverage
Usage
dbt-coverage comes with two basic commands: compute and compare. The documentation for the individual commands can be shown by using the --help option.
Compute
Compute coverage from target/catalog.json and target/manifest.json files found in a dbt project, e.g. jaffle_shop.
To choose between documentation and test coverage, pass doc or test as the CLI argument.
$ cd jaffle_shop
$ dbt run # Materialize models
$ dbt docs generate # Generate catalog.json and manifest.json
$ dbt-coverage compute doc --cov-report coverage-doc.json # Compute doc coverage, print it and write it to coverage-doc.json file
Coverage report
=====================================================================
jaffle_shop.customers 6/7 85.7%
jaffle_shop.orders 9/9 100.0%
jaffle_shop.raw_customers 0/3 0.0%
jaffle_shop.raw_orders 0/4 0.0%
jaffle_shop.raw_payments 0/4 0.0%
jaffle_shop.stg_customers 0/3 0.0%
jaffle_shop.stg_orders 0/4 0.0%
jaffle_shop.stg_payments 0/4 0.0%
=====================================================================
Total 15/38 39.5%
$ dbt-coverage compute test --cov-report coverage-test.json # Compute test coverage, print it and write it to coverage-test.json file
Coverage report
=====================================================================
jaffle_shop.customers 1/7 14.3%
jaffle_shop.orders 8/9 88.9%
jaffle_shop.raw_customers 0/3 0.0%
jaffle_shop.raw_orders 0/4 0.0%
jaffle_shop.raw_payments 0/4 0.0%
jaffle_shop.stg_customers 1/3 33.3%
jaffle_shop.stg_orders 2/4 50.0%
jaffle_shop.stg_payments 2/4 50.0%
=====================================================================
Total 14/38 36.8%
Compare
Compare two coverage.json files generated by the compute command. This is useful to ensure that the coverage does not drop while making changes to the project.
$ dbt-coverage compare coverage-after.json coverage-before.json
# Coverage delta summary
before after +/-
=============================================
Coverage 39.47% 38.46% -1.01%
=============================================
Tables 8 8 +0/+0
Columns 38 39 +1/+0
=============================================
Hits 15 15 +0/+0
Misses 23 24 +1/+0
=============================================
# New misses
=========================================================================
Catalog 15/38 (39.47%) -> 15/39 (38.46%)
=========================================================================
- jaffle_shop.customers 6/7 (85.71%) -> 6/8 (75.00%)
-- new_col -/- (-) -> 0/1 (0.00%)
=========================================================================
Combined use-case
$ cd my-dbt-project
$ dbt run # Materialize models
$ dbt docs generate # Generate catalog.json and manifest.json
$ dbt-coverage compute doc --cov-report before.json --cov-fail-under 0.5 # Fail if coverage is lower than 50%
# Make changes to the dbt project, e.g. add some columns to the DWH, document some columns, etc.
$ dbt run # Materialize the changed models
$ dbt docs generate # Generate catalog.json and manifest.json
$ dbt-coverage compute doc --cov-report after.json --cov-fail-compare before.json # Fail if the current coverage is lower than coverage in before.json
$ dbt-coverage compare after.json before.json # Generate a detailed coverage delta report
Related packages
- https://github.com/mikaelene/dbt-test-coverage
- interrogate (docs coverage for Python)
- coverage.py (execution coverage for Python)
License
Licensed under the MIT license (see LICENSE.md file for more details).
3 Nov 18, 2021
1 Jan 05, 2022
2 Dec 28, 2022
21 Jan 06, 2023
9 Dec 09, 2022
1 Nov 15, 2021
422 Dec 30, 2022
72 Oct 09, 2022
9 Sep 28, 2022
5 Aug 17, 2022
6 Aug 04, 2022
1 Feb 03, 2022
455 Dec 24, 2022
3.8k Dec 31, 2022
11 Mar 17, 2022
2 Dec 03, 2021
2 Oct 07, 2021
1 Jan 22, 2022
552 Dec 28, 2022
6 Jan 20, 2022