Run test examples from docs (#17)

Run the test examples as docs by creating a dbt_project in the docs to run the test for and directly referencing example macros in the docs.

.github/workflows/workflow.yml

@@ -29,7 +29,7 @@ jobs:
        shell: bash
        run: pre-commit run --all-file
 
-  tox:
+  tests:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -56,11 +56,14 @@ jobs:
     - name: Test with tox
       run: tox
 
+    - name: Test docs with tox
+      run: tox -e docs
+
   test-release:
     if: contains(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     needs:
-    - tox
+    - tests
     - "pre-commit"
     steps:
     - uses: actions/checkout@v2

.gitignore

@@ -132,3 +132,7 @@ dmypy.json
 
 # Version
 src/pytest_dbt_core/_version.py
+
+# dbt
+.user.yml
+dbt_packages/

.pre-commit-config.yaml

@@ -52,7 +52,7 @@ repos:
   rev: v1.0.4
   hooks:
   - id: python-bandit-vulnerability-check
-    args: [-l, --recursive, -x, tests]
+    args: [-l, --recursive, -x, "tests,docs/source/_static/dbt_project/tests"]
     name: Check for vulnerabilities in code with bandit
     files: .py$
 - repo: /~https://github.com/Lucas-C/pre-commit-hooks-safety

CHANGELOG.md

@@ -1,3 +1,4 @@
+- Run test examples from docs ([issue](/~https://github.com/godatadriven/pytest-dbt-core/issues/14), [PR](/~https://github.com/godatadriven/pytest-dbt-core/pull/17))
 - Add target flag ([issue](/~https://github.com/godatadriven/pytest-dbt-core/issues/11), [PR](/~https://github.com/godatadriven/pytest-dbt-core/pull/13))
 - Delete session module [is included in dbt-spark](/~https://github.com/dbt-labs/dbt-spark/issues/272)
 - Add Github templates

README.md

@@ -1,7 +1,9 @@
 <p align="center">
-  <a href="/~https://github.com/godatadriven/pytest-dbt-core/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache%202-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://pypi.org/project/pytest-dbt-core/"><img alt="Pypi pytest-dbt-core" src="https://img.shields.io/badge/pypi-pytest%20dbt%20core-green.svg"></a>
-  <a href="/~https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml"><img alt="build pytest-dbt-core" src="/~https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml/badge.svg"></a>
+  <a href="/~https://github.com/godatadriven/pytest-dbt-core/blob/main/LICENSE"><img alt="License: Apache 2.0" src="https://img.shields.io/badge/license-Apache%202-blue.svg"></a>
+  <a href="https://pypi.org/project/pytest-dbt-core/"><img alt="pypi: pytest-dbt-core" src="https://img.shields.io/badge/pypi-pytest%20dbt%20core-green.svg"></a>
+  <a href="/~https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml"><img alt="build: pytest-dbt-core" src="/~https://github.com/godatadriven/pytest-dbt-core/actions/workflows/workflow.yml/badge.svg"></a>
+  <a href="/~https://github.com/psf/black"><img alt="code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+  <a href="https://pepy.tech/badge/pytest-dbt-core/"><img alt="downloads" src="https://pepy.tech/badge/pytest-dbt-core/month"></a>
 </p>
 
 Pytest dbt core is a [pytest](https://docs.pytest.org) plugin for testing your

docs/source/_static/dbt_project/dbt_project.yml

@@ -0,0 +1,6 @@
+name: dbt_project
+profile: dbt_project
+version: '0.3.0'
+config-version: 2
+require-dbt-version: [">=1.0.0", "<2.0.0"]
+macro-paths: ["macros"]

docs/source/_static/dbt_project/packages.yml

@@ -0,0 +1,3 @@
+packages:
+- package: dbt-labs/spark_utils
+  version: 0.3.0

docs/source/_static/dbt_project/profiles.yml

@@ -0,0 +1,8 @@
+dbt_project:
+  target: test
+  outputs:
+    test:
+      type: spark
+      method: session
+      schema: test
+      host: NA        # not used, but required by `dbt-core`

docs/source/_static/dbt_project/tests/test_spark_get_tables.py

@@ -0,0 +1,16 @@
+import pytest
+from dbt.clients.jinja import MacroGenerator
+from pyspark.sql import SparkSession
+
+
+@pytest.mark.parametrize(
+    "macro_generator", ["macro.spark_utils.get_tables"], indirect=True
+)
+def test_get_tables(
+    spark_session: SparkSession, macro_generator: MacroGenerator
+) -> None:
+    """The get tables macro should return the created table."""
+    expected_table = "default.example"
+    spark_session.sql(f"CREATE TABLE {expected_table} (id int) USING parquet")
+    tables = macro_generator()
+    assert tables == [expected_table]

docs/source/configuration.rst

@@ -11,6 +11,13 @@ point the `---dbt-project-dir`
 `option <https://docs.pytest.org/en/6.2.x/usage.html#getting-help-on-version-option-names-environment-variables>`_
 to the root of your project.
 
+Target
+************************
+If you want to use another
+`target <https://docs.getdbt.com/reference/dbt-jinja-functions/target>`_
+than the default, you set the `--dbt-target`
+`option <https://docs.pytest.org/en/6.2.x/usage.html#getting-help-on-version-option-names-environment-variables>`_.
+
 Profiles directory
 **********************
 If you want to change dbt's profiles directory, use the `DBT_PROFILES_DIR` environment `variable <https://docs.getdbt.com/dbt-cli/configure-your-profile/#advanced-customizing-a-profile-directory>`_.

docs/source/index.rst

@@ -24,26 +24,8 @@ Usage
 
 Unit test a macro:
 
-.. code-block:: python
-
-   from __future__ import annotations
-
-   import pytest
-   from dbt.clients.jinja import MacroGenerator
-   from pyspark.sql import SparkSession
-
-
-   @pytest.mark.parametrize(
-       "macro_generator", ["macro.spark_utils.get_tables"], indirect=True
-   )
-   def test_create_table(
-       spark_session: SparkSession, macro_generator: MacroGenerator
-   ) -> None:
-       expected_table = "default.example"
-       spark_session.sql(f"CREATE TABLE {expected_table} (id int) USING parquet")
-       tables = macro_generator()
-       assert tables == [expected_table]
-
+.. literalinclude :: _static/dbt_project/tests/test_spark_get_tables.py
+   :language: python
 
 .. toctree::
    :maxdepth: 2

setup.cfg

@@ -89,3 +89,18 @@ deps =
     pip >= 19.3.1
 extras = test
 commands = pytest {posargs:tests}
+
+[testenv:docs]
+description = run the tests in docs
+setenv =
+    PIP_DISABLE_PIP_VERSION_CHECK = 1
+    {py27,pypy}: PYTHONWARNINGS=ignore:DEPRECATION::pip._internal.cli.base_command
+    DBT_PROFILES_DIR = {env:DBT_PROFILES_DIR:{toxinidir}/docs/source/_static/dbt_project}
+passenv =
+    PYTEST_*
+    PIP_CACHE_DIR
+deps =
+    pip >= 19.3.1
+extras = test
+commands_pre = dbt deps --project-dir {toxinidir}/docs/source/_static/dbt_project
+commands = pytest {posargs:docs/source/_static/dbt_project/tests} --dbt-project-dir={toxinidir}/docs/source/_static/dbt_project