# dbt-coverage
<a href="https://pypi.org/project/dbt-coverage/"><img alt="PyPI" src="https://img.shields.io/pypi/v/dbt-coverage"></a>
<a href="https://pepy.tech/project/dbt-coverage"><img alt="Downloads" src="https://pepy.tech/badge/dbt-coverage"></a>
<a href="https://github.com/slidoapp/dbt-coverage/blob/main/LICENSE.md"><img alt="License: MIT" src="https://img.shields.io/github/license/slidoapp/dbt-coverage"></a>
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage?ref=badge_shield)
_One-stop-shop for docs and test coverage of [`dbt`](https://github.com/dbt-labs/dbt) projects._
Optimized for dbt 1.0, see [full support matrix](#supported-dbt-versions).
## Why do I need something like this?
_**[`dbt-coverage`](https://github.com/slidoapp/dbt-coverage) is to [`dbt`](https://github.com/dbt-labs/dbt) what [`coverage.py`](https://github.com/nedbat/coveragepy) and [`interrogate`](https://interrogate.readthedocs.io/en/latest/) 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`](https://github.com/dbt-labs/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 `dbt` project 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 are [`click`](https://click.palletsprojects.com/en/8.0.x/) (already installed with [`dbt`](https://github.com/dbt-labs/dbt)) and [`typer`](https://typer.tiangolo.com/tutorial/)
- 📦 **very small**: at ~480 [SLOC](https://en.wikipedia.org/wiki/Source_lines_of_code), you can easily validate it works as advertised
## Demo
The package was presented during [Coalesce](https://coalesce.getdbt.com/),
the annual dbt conference, as a part of the talk
[_From 100 spreadsheets to 100 data analysts: the story of dbt at Slido_](https://www.getdbt.com/coalesce-2021/from-spreadsheets-to-data-analysts-the-story-of-dbt-at-slido/).
Watch a demo in the video below.
[](https://youtu.be/YA0yqYSs9BQ?t=936)
## 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](https://github.com/dbt-labs/jaffle_shop).
To choose between documentation and test coverage, pass `doc` or `test` as the CLI argument.
```console
$ 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%
```
#### Filtering model paths with `--model-path-filter`
You can also choose a subset of tables to compare using one or multiple `--model-path-filter` options.
```console
$ 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 --model-path-filter models/staging/ # Compute doc coverage for a subset of tables, print it and write it to coverage-doc.json file
Coverage report
======================================================
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 0/11 0.0%
$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-filter models/orders.sql --model-path-filter models/staging/ # Compute doc coverage for a subset of tables, print it and write it to coverage-doc.json file
Coverage report
======================================================
jaffle_shop.orders 0/9 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 0/20 0.0%
```
#### Markdown output with `--cov-format`
You can also choose to print the output in the Markdown table format by specifying the `--cov-format` option.
This can be especially useful when using `dbt-coverage` in CI/CD pipelines.
```console
$ cd jaffle_shop
$ dbt run # Materialize models
$ dbt docs generate # Generate catalog.json and manifest.json
$ dbt-coverage compute doc --model-path-filter models/staging/ --cov-format markdown
# Coverage report
| Model | Columns Covered | % |
|:------|----------------:|:-:|
| 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 | 0/11 | 0.0% |
```
#### Custom run artifacts path with `--run-artifacts-dir`
To compute the coverages, `dbt-coverage` looks up the artefacts from the `dbt run` execution in the
`./target/` folder in the current directory. You can specify a custom path via the `--run-artifacts-dir`
option.
```console
$ dbt-coverage compute doc --run-artifacts-dir jaffle_shop/target --cov-report coverage-doc.json # Compute doc coverage from the artefacts located in jaffle_shop/target, print it and write it to coverage-doc.json file
Coverage report
================================================
jaffle_shop.customers 0/7 0.0%
jaffle_shop.orders 0/9 0.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 0/38 0.0%
```
### 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.
```console
$ 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
```console
$ 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
```
## Supported `dbt` versions
Different version of `dbt-coverage` support different versions of `dbt`. Here is
the support matrix.
| `dbt` | `dbt-coverage` |
|-------------|----------------|
| <0.20 | not tested |
| 0.20 - 0.21 | 0.1 |
| 1.0 - 1.6 | 0.2, 0.3 |
## Related packages
- https://github.com/mikaelene/dbt-test-coverage
- [interrogate](https://interrogate.readthedocs.io/en/latest/) (docs coverage for Python)
- [coverage.py](https://github.com/nedbat/coveragepy) (execution coverage for Python)
## License
Licensed under the MIT license (see [LICENSE.md](LICENSE.md) file for more
details).
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage?ref=badge_large)
Raw data
{
"_id": null,
"home_page": "https://github.com/slidoapp/dbt-coverage",
"name": "dbt-coverage",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Andrej \u0160vec",
"author_email": "asvec@slido.com",
"download_url": "https://files.pythonhosted.org/packages/02/b9/d2e310d4a59ad5ba32f0d627dfa66a440ca795ff6b48d4aab27f35241139/dbt_coverage-0.3.5.tar.gz",
"platform": null,
"description": "# dbt-coverage\n\n<a href=\"https://pypi.org/project/dbt-coverage/\"><img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/dbt-coverage\"></a>\n<a href=\"https://pepy.tech/project/dbt-coverage\"><img alt=\"Downloads\" src=\"https://pepy.tech/badge/dbt-coverage\"></a>\n\n\n\n\n<a href=\"https://github.com/slidoapp/dbt-coverage/blob/main/LICENSE.md\"><img alt=\"License: MIT\" src=\"https://img.shields.io/github/license/slidoapp/dbt-coverage\"></a>\n[](https://app.fossa.com/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage?ref=badge_shield)\n\n\n_One-stop-shop for docs and test coverage of [`dbt`](https://github.com/dbt-labs/dbt) projects._\n\nOptimized for dbt 1.0, see [full support matrix](#supported-dbt-versions).\n\n## Why do I need something like this?\n\n_**[`dbt-coverage`](https://github.com/slidoapp/dbt-coverage) is to [`dbt`](https://github.com/dbt-labs/dbt) what [`coverage.py`](https://github.com/nedbat/coveragepy) and [`interrogate`](https://interrogate.readthedocs.io/en/latest/) are to Python.**_\n\nIt is a single CLI tool which checks your `dbt` project for missing documentation and tests.\n\nKeeping 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`](https://github.com/dbt-labs/dbt) project?\n\nThat is exactly where `dbt-coverage` comes in. It will\n\n- Give you a better sense of the level of documentation and test coverage in your project;\n- Help your CI/CD pipeline make sure new changes include documentation and tests;\n- Let you quickly assess the documentation and tests of a new `dbt` project you get your hands on.\n\nStill not convinced? Here are some more features:\n\n- \u2728 **zero-config**: just install it and run it, there is nothing to set up\n- \ud83c\udfc1 **minimal dependences**: the only dependencies are [`click`](https://click.palletsprojects.com/en/8.0.x/) (already installed with [`dbt`](https://github.com/dbt-labs/dbt)) and [`typer`](https://typer.tiangolo.com/tutorial/)\n- \ud83d\udce6 **very small**: at ~480 [SLOC](https://en.wikipedia.org/wiki/Source_lines_of_code), you can easily validate it works as advertised\n\n\n## Demo\nThe package was presented during [Coalesce](https://coalesce.getdbt.com/),\nthe annual dbt conference, as a part of the talk\n[_From 100 spreadsheets to 100 data analysts: the story of dbt at Slido_](https://www.getdbt.com/coalesce-2021/from-spreadsheets-to-data-analysts-the-story-of-dbt-at-slido/).\nWatch a demo in the video below.\n\n[](https://youtu.be/YA0yqYSs9BQ?t=936)\n\n## Installation\n\n```\npip install dbt-coverage\n```\n\n## Usage\n\n`dbt-coverage` comes with two basic commands: `compute` and `compare`. The\ndocumentation for the individual commands can be shown by using the `--help`\noption.\n\n### Compute\n\nCompute coverage from `target/catalog.json` and `target/manifest.json` files\nfound in a dbt project, e.g.\n[jaffle_shop](https://github.com/dbt-labs/jaffle_shop). \n\nTo choose between documentation and test coverage, pass `doc` or `test` as the CLI argument.\n\n```console\n$ cd jaffle_shop\n$ dbt run # Materialize models\n$ dbt docs generate # Generate catalog.json and manifest.json\n$ dbt-coverage compute doc --cov-report coverage-doc.json # Compute doc coverage, print it and write it to coverage-doc.json file\n\nCoverage report\n=====================================================================\njaffle_shop.customers 6/7 85.7%\njaffle_shop.orders 9/9 100.0%\njaffle_shop.raw_customers 0/3 0.0%\njaffle_shop.raw_orders 0/4 0.0%\njaffle_shop.raw_payments 0/4 0.0%\njaffle_shop.stg_customers 0/3 0.0%\njaffle_shop.stg_orders 0/4 0.0%\njaffle_shop.stg_payments 0/4 0.0%\n=====================================================================\nTotal 15/38 39.5%\n\n$ dbt-coverage compute test --cov-report coverage-test.json # Compute test coverage, print it and write it to coverage-test.json file\n\nCoverage report\n=====================================================================\njaffle_shop.customers 1/7 14.3%\njaffle_shop.orders 8/9 88.9%\njaffle_shop.raw_customers 0/3 0.0%\njaffle_shop.raw_orders 0/4 0.0%\njaffle_shop.raw_payments 0/4 0.0%\njaffle_shop.stg_customers 1/3 33.3%\njaffle_shop.stg_orders 2/4 50.0%\njaffle_shop.stg_payments 2/4 50.0%\n=====================================================================\nTotal 14/38 36.8%\n```\n\n#### Filtering model paths with `--model-path-filter`\n\nYou can also choose a subset of tables to compare using one or multiple `--model-path-filter` options.\n\n```console\n$ cd jaffle_shop\n$ dbt run # Materialize models\n$ dbt docs generate # Generate catalog.json and manifest.json\n$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-filter models/staging/ # Compute doc coverage for a subset of tables, print it and write it to coverage-doc.json file\n\nCoverage report\n======================================================\njaffle_shop.stg_customers 0/3 0.0%\njaffle_shop.stg_orders 0/4 0.0%\njaffle_shop.stg_payments 0/4 0.0%\n======================================================\nTotal 0/11 0.0%\n\n$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-filter models/orders.sql --model-path-filter models/staging/ # Compute doc coverage for a subset of tables, print it and write it to coverage-doc.json file\n\nCoverage report\n======================================================\njaffle_shop.orders 0/9 0.0%\njaffle_shop.stg_customers 0/3 0.0%\njaffle_shop.stg_orders 0/4 0.0%\njaffle_shop.stg_payments 0/4 0.0%\n======================================================\nTotal 0/20 0.0%\n```\n\n#### Markdown output with `--cov-format`\n\nYou can also choose to print the output in the Markdown table format by specifying the `--cov-format` option.\nThis can be especially useful when using `dbt-coverage` in CI/CD pipelines.\n\n```console\n$ cd jaffle_shop\n$ dbt run # Materialize models\n$ dbt docs generate # Generate catalog.json and manifest.json\n$ dbt-coverage compute doc --model-path-filter models/staging/ --cov-format markdown\n\n# Coverage report\n| Model | Columns Covered | % |\n|:------|----------------:|:-:|\n| jaffle_shop.stg_customers | 0/3 | 0.0% |\n| jaffle_shop.stg_orders | 0/4 | 0.0% |\n| jaffle_shop.stg_payments | 0/4 | 0.0% |\n| Total | 0/11 | 0.0% |\n```\n\n#### Custom run artifacts path with `--run-artifacts-dir`\n\nTo compute the coverages, `dbt-coverage` looks up the artefacts from the `dbt run` execution in the\n`./target/` folder in the current directory. You can specify a custom path via the `--run-artifacts-dir`\noption.\n\n```console\n$ dbt-coverage compute doc --run-artifacts-dir jaffle_shop/target --cov-report coverage-doc.json # Compute doc coverage from the artefacts located in jaffle_shop/target, print it and write it to coverage-doc.json file\n\nCoverage report\n================================================\njaffle_shop.customers 0/7 0.0%\njaffle_shop.orders 0/9 0.0%\njaffle_shop.raw_customers 0/3 0.0%\njaffle_shop.raw_orders 0/4 0.0%\njaffle_shop.raw_payments 0/4 0.0%\njaffle_shop.stg_customers 0/3 0.0%\njaffle_shop.stg_orders 0/4 0.0%\njaffle_shop.stg_payments 0/4 0.0%\n================================================\nTotal 0/38 0.0%\n```\n\n### Compare\n\nCompare two `coverage.json` files generated by the `compute` command. This is\nuseful to ensure that the coverage does not drop while making changes to the\nproject.\n\n```console\n$ dbt-coverage compare coverage-after.json coverage-before.json\n\n# Coverage delta summary\n before after +/-\n=============================================\nCoverage 39.47% 38.46% -1.01%\n=============================================\nTables 8 8 +0/+0\nColumns 38 39 +1/+0\n=============================================\nHits 15 15 +0/+0\nMisses 23 24 +1/+0\n=============================================\n\n# New misses\n=========================================================================\nCatalog 15/38 (39.47%) -> 15/39 (38.46%) \n=========================================================================\n- jaffle_shop.customers 6/7 (85.71%) -> 6/8 (75.00%) \n-- new_col -/- (-) -> 0/1 (0.00%) \n=========================================================================\n```\n\n### Combined use-case\n\n```console\n$ cd my-dbt-project\n\n$ dbt run # Materialize models\n$ dbt docs generate # Generate catalog.json and manifest.json\n$ dbt-coverage compute doc --cov-report before.json --cov-fail-under 0.5 # Fail if coverage is lower than 50%\n\n# Make changes to the dbt project, e.g. add some columns to the DWH, document some columns, etc.\n\n$ dbt run # Materialize the changed models\n$ dbt docs generate # Generate catalog.json and manifest.json\n$ 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\n$ dbt-coverage compare after.json before.json # Generate a detailed coverage delta report\n```\n\n## Supported `dbt` versions\n\nDifferent version of `dbt-coverage` support different versions of `dbt`. Here is\nthe support matrix.\n\n| `dbt` | `dbt-coverage` |\n|-------------|----------------|\n| <0.20 | not tested |\n| 0.20 - 0.21 | 0.1 |\n| 1.0 - 1.6 | 0.2, 0.3 |\n\n## Related packages\n\n- https://github.com/mikaelene/dbt-test-coverage\n- [interrogate](https://interrogate.readthedocs.io/en/latest/) (docs coverage for Python)\n- [coverage.py](https://github.com/nedbat/coveragepy) (execution coverage for Python)\n\n## License\n\nLicensed under the MIT license (see [LICENSE.md](LICENSE.md) file for more\ndetails).\n\n[](https://app.fossa.com/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage?ref=badge_large)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "One-stop-shop for docs and test coverage of dbt projects",
"version": "0.3.5",
"project_urls": {
"Documentation": "https://github.com/slidoapp/dbt-coverage",
"Homepage": "https://github.com/slidoapp/dbt-coverage",
"Repository": "https://github.com/slidoapp/dbt-coverage"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "18ec5de422da0f29f214aab033222e6d29337df2013bfbba65e6e5d3bd90da4e",
"md5": "63d1a1218398b8846f2b4b640f3b0e3e",
"sha256": "a51a8bc1390d9efee5e0de14fe371f2dae6e478bc698f4e5db2cdfd0e0f15def"
},
"downloads": -1,
"filename": "dbt_coverage-0.3.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63d1a1218398b8846f2b4b640f3b0e3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 12288,
"upload_time": "2023-11-08T23:31:24",
"upload_time_iso_8601": "2023-11-08T23:31:24.942430Z",
"url": "https://files.pythonhosted.org/packages/18/ec/5de422da0f29f214aab033222e6d29337df2013bfbba65e6e5d3bd90da4e/dbt_coverage-0.3.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "02b9d2e310d4a59ad5ba32f0d627dfa66a440ca795ff6b48d4aab27f35241139",
"md5": "26c854d8d277742c784dff3925da975e",
"sha256": "1f750ba1d49b464f35cb394731a665de61af526cfb5173829832ca9e5251884a"
},
"downloads": -1,
"filename": "dbt_coverage-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "26c854d8d277742c784dff3925da975e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 14561,
"upload_time": "2023-11-08T23:31:26",
"upload_time_iso_8601": "2023-11-08T23:31:26.747755Z",
"url": "https://files.pythonhosted.org/packages/02/b9/d2e310d4a59ad5ba32f0d627dfa66a440ca795ff6b48d4aab27f35241139/dbt_coverage-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-08 23:31:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slidoapp",
"github_project": "dbt-coverage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "dbt-coverage"
}
JSON
