{"id":13703850,"url":"https://github.com/slidoapp/dbt-coverage","last_synced_at":"2025-12-29T23:26:10.686Z","repository":{"id":37279336,"uuid":"421022206","full_name":"slidoapp/dbt-coverage","owner":"slidoapp","description":"One-stop-shop for docs and test coverage of dbt projects.","archived":false,"fork":false,"pushed_at":"2024-03-13T14:13:06.000Z","size":1010,"stargazers_count":167,"open_issues_count":13,"forks_count":22,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-15T14:44:51.045Z","etag":null,"topics":["cli","coverage","dbt","docs","documentation","python","testing","tests","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slidoapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-10-25T12:51:58.000Z","updated_at":"2024-06-19T09:00:16.078Z","dependencies_parsed_at":"2024-04-23T11:48:11.162Z","dependency_job_id":"7927d4c3-fc6a-4e57-9b25-1b50acbaaa60","html_url":"https://github.com/slidoapp/dbt-coverage","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slidoapp%2Fdbt-coverage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slidoapp%2Fdbt-coverage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slidoapp%2Fdbt-coverage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slidoapp%2Fdbt-coverage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slidoapp","download_url":"https://codeload.github.com/slidoapp/dbt-coverage/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224431310,"owners_count":17310092,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","coverage","dbt","docs","documentation","python","testing","tests","tool"],"created_at":"2024-08-02T21:01:00.780Z","updated_at":"2025-12-29T23:26:10.680Z","avatar_url":"https://github.com/slidoapp.png","language":"Python","readme":"# dbt-coverage\n\n\u003ca href=\"https://pypi.org/project/dbt-coverage/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/dbt-coverage\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pepy.tech/project/dbt-coverage\"\u003e\u003cimg alt=\"Downloads\" src=\"https://pepy.tech/badge/dbt-coverage\"\u003e\u003c/a\u003e\n![GitHub last commit](https://img.shields.io/github/last-commit/slidoapp/dbt-coverage)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/dbt-coverage)\n![PyPI - Format](https://img.shields.io/pypi/format/dbt-coverage)\n![dbt versions](https://img.shields.io/badge/dbt-1.0-blue)\n\u003ca href=\"https://github.com/slidoapp/dbt-coverage/blob/main/LICENSE.md\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/github/license/slidoapp/dbt-coverage\"\u003e\u003c/a\u003e\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- ✨ **zero-config**: just install it and run it, there is nothing to set up\n- 🏁 **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- 📦 **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[![Demo video](assets/demo.png)](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\n```console\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` or `--model-path-exclusion-filter`\n\nYou can also choose a subset of tables to compare using one or multiple `--model-path-filter` and/or `--model-path-exclusion-filter` options. Here are some examples.\n\nUse the `--model-path-filter`.\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/\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\nUse the `--model-path-exclusion-filter`.\n\n```console\n$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-exclusion-filter models/staging/\n\nCoverage report (doc)\n=====================================================================\ndbt_sweco.customers                                    6/7      85.7%\ndbt_sweco.orders                                       9/9     100.0%\ndbt_sweco.raw_customers                                0/3       0.0%\ndbt_sweco.raw_orders                                   0/4       0.0%\ndbt_sweco.raw_payments                                 0/4       0.0%\n=====================================================================\nTotal                                                 15/27     55.6%\n```\n\nUse multiple paths. The same can be done with `--model-path-exclusion-filter`.\n\n```console\n$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-filter models/orders.sql --model-path-filter models/staging/\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\nUse both `--model-path-filter` and `--model-path-exclusion-filter`.\n\n```console\n$ dbt-coverage compute doc --cov-report coverage-doc.json --model-path-filter models/staging --model-path-exclusion-filter models/staging/stg_customers\n\nCoverage report (doc)\n=====================================================================\ndbt_sweco.stg_orders                                   0/4       0.0%\ndbt_sweco.stg_payments                                 0/4       0.0%\n=====================================================================\nTotal                                                  0/8       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%)  -\u003e    15/39   (38.46%)\n=========================================================================\n- jaffle_shop.customers          6/7    (85.71%)  -\u003e     6/8    (75.00%)\n-- new_col                       -/-       (-)    -\u003e     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| \u003c0.20       | not tested     |\n| 0.20 - 0.21 | 0.1            |\n| 1.0 - 1.9   | 0.2 - 0.4      |\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## Contributing\n\nClone this repo including submodules, create a virtual environment and install dependencies:\n```bash\ngit clone --recurse-submodules git@github.com:slidoapp/dbt-coverage.git\ncd dbt-coverage\npip install poetry\npoetry shell\npoetry install\npre-commit install\n```\n\nTo run all integration tests locally, run:\n```bash\ntox\n```\n\n## License\n\nLicensed under the MIT license (see [LICENSE.md](LICENSE.md) file for more\ndetails).\n\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fslidoapp%2Fdbt-coverage?ref=badge_large)\n","funding_links":[],"categories":["Packages"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslidoapp%2Fdbt-coverage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslidoapp%2Fdbt-coverage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslidoapp%2Fdbt-coverage/lists"}