dbt-tests-adapter Framework

The dbt-tests-adapter framework provides a centralized, reusable test suite designed to validate the behavior of dbt adapter plugins. It ensures that different database adapters—such as Postgres, Snowflake, BigQuery, and Redshift—adhere to the core expectations of the dbt ecosystem. The framework is structured to offer both "Basic" tests, which verify fundamental dbt operations, and "Optional" tests for advanced functionality.

Sources: dbt-tests-adapter/README.md:12-25, CLAUDE.md:65-71

Core Architecture and Test Discovery

The framework uses a "Base-to-Test" inheritance pattern. Reusable test cases are defined in classes prefixed with Base. Adapter maintainers enable these tests by inheriting from the Base class into a new class prefixed with Test. This allows pytest to discover and execute the tests while providing a mechanism for adapters to override specific behaviors, SQL fixtures, or configurations as needed.

Test Categories

The suite is divided into two primary logical categories to balance strict requirements with platform flexibility.

Sources: dbt-tests-adapter/README.md:14-25, CLAUDE.md:73-82, dbt-tests-adapter/CHANGELOG.md:10-18

Technical Implementation Details

Fixture Management

The framework extensively uses pytest fixtures to define dbt project states. These typically include the models, seeds, macros, and snapshots directories. These fixtures return dictionaries where keys are filenames and values are the content of the dbt files (SQL or YAML).

@pytest.fixture(scope="class")
def models(self):
    return {
        "schema.yml": models__schema_yml,
        "second_model.sql": models__second_model_sql,
        "readme.md": models__readme_md,
        "model.sql": models__model_sql,
    }

Sources: dbt-tests-adapter/src/dbt/tests/adapter/basic/test_docs_generate.py:270-277, CLAUDE.md:84-90

Functional Test Execution Flow

When a test is executed, the framework follows a standard sequence: schema creation, artifact seeding, running dbt commands, and verifying results (often against a generated catalog.json or manifest.json).

Documentation Generation Testing

The BaseDocsGenerate class serves as a primary example of complex functional testing within the suite. It validates that an adapter can successfully generate documentation artifacts (catalog.json) and correctly handles metadata such as column descriptions, types, and asset paths.

• Key Verification Functions:
  • verify_catalog: Compares the generated catalog.json against an expected_catalog dictionary.
  • verify_metadata: Ensures the generated_at timestamp and schema versions are correct.
  • run_and_generate: Orchestrates the dbt commands needed to produce the artifacts.

Sources: dbt-tests-adapter/src/dbt/tests/adapter/basic/test_docs_generate.py:192-230, dbt-tests-adapter/CHANGELOG.md:31-33

Advanced Test Capabilities

Recent updates to the framework have introduced tests for specialized dbt features:

• Python UDFs: Includes PythonUDFWithPackagesSupported to test package templating in Python-based models.
• Snapshot Evolution: Tests for hard_deletes="new_record" through BaseSnapshotNewColumnTimestampStrategy.
• Microbatching: Validation for microbatch concurrency and execution strategies.

Sources: dbt-tests-adapter/CHANGELOG.md:12-18, CLAUDE.md:78-82

Summary

The dbt-tests-adapter framework is a critical component for maintaining cross-platform consistency in the dbt ecosystem. By providing a standardized set of base classes for functional and unit testing, it reduces the burden on adapter maintainers while ensuring that all adapters meet the quality standards required for production data transformation.

Sources: dbt-tests-adapter/README.md:12-16, CLAUDE.md:65-68