accept generic test args under 'args' (#11840)

Author: MichelleArk

.changes/unreleased/Features-20250721-173100.yaml

@@ -0,0 +1,6 @@
+kind: Features
+body: Deprecate top-level argument properties in generic tests
+time: 2025-07-21T17:31:00.960402-04:00
+custom:
+    Author: michelleark
+    Issue: "11847"

core/dbt/contracts/project.py

@@ -361,6 +361,7 @@ class ProjectFlags(ExtensibleDbtClassMixin):
     require_nested_cumulative_type_params: bool = False
     validate_macro_args: bool = False
     require_all_warnings_handled_by_warn_error: bool = False
+    require_generic_test_arguments_property: bool = False
 
     @property
     def project_only_flags(self) -> Dict[str, Any]:
@@ -376,6 +377,7 @@ def project_only_flags(self) -> Dict[str, Any]:
             "require_nested_cumulative_type_params": self.require_nested_cumulative_type_params,
             "validate_macro_args": self.validate_macro_args,
             "require_all_warnings_handled_by_warn_error": self.require_all_warnings_handled_by_warn_error,
+            "require_generic_test_arguments_property": self.require_generic_test_arguments_property,
         }
 
 

core/dbt/deprecations.py

@@ -215,6 +215,16 @@ class MissingPlusPrefixDeprecation(DBTDeprecation):
     _event = "MissingPlusPrefixDeprecation"
 
 
+class ArgumentsPropertyInGenericTestDeprecation(DBTDeprecation):
+    _name = "arguments-property-in-generic-test-deprecation"
+    _event = "ArgumentsPropertyInGenericTestDeprecation"
+
+
+class MissingArgumentsPropertyInGenericTestDeprecation(DBTDeprecation):
+    _name = "missing-arguments-property-in-generic-test-deprecation"
+    _event = "MissingArgumentsPropertyInGenericTestDeprecation"
+
+
 def renamed_env_var(old_name: str, new_name: str):
     class EnvironmentVariableRenamed(DBTDeprecation):
         _name = f"environment-variable-renamed:{old_name}"
@@ -298,6 +308,8 @@ def show_deprecations_summary() -> None:
     SourceOverrideDeprecation(),
     EnvironmentVariableNamespaceDeprecation(),
     MissingPlusPrefixDeprecation(),
+    ArgumentsPropertyInGenericTestDeprecation(),
+    MissingArgumentsPropertyInGenericTestDeprecation(),
 ]
 
 deprecations: Dict[str, DBTDeprecation] = {d.name: d for d in deprecations_list}

core/dbt/events/types.py

@@ -742,6 +742,24 @@ def message(self) -> str:
         return line_wrap_message(deprecation_tag(description, self.__class__.__name__))
 
 
+class ArgumentsPropertyInGenericTestDeprecation(WarnLevel):
+    def code(self) -> str:
+        return "D038"
+
+    def message(self) -> str:
+        description = f"Found `arguments` property in test definition of `{self.test_name}` without usage of `require_generic_test_arguments_property` behavior change flag. The `arguments` property is deprecated for custom usage and will be used to nest keyword arguments in future versions of dbt."
+        return line_wrap_message(deprecation_tag(description, self.__class__.__name__))
+
+
+class MissingArgumentsPropertyInGenericTestDeprecation(WarnLevel):
+    def code(self) -> str:
+        return "D039"
+
+    def message(self) -> str:
+        description = f"Found top-level arguments to test `{self.test_name}`. Arguments to generic tests should be nested under the `arguments` property.`"
+        return line_wrap_message(deprecation_tag(description, self.__class__.__name__))
+
+
 # =======================================================
 # I - Project parsing
 # =======================================================

core/dbt/include/jsonschemas/resources/latest.json

@@ -691,6 +691,101 @@
       },
       "additionalProperties": false
     },
+    "CustomTest": {
+      "anyOf": [
+        {
+          "$ref": "#/definitions/CustomTestMultiKey"
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/CustomTestInner"
+          }
+        }
+      ]
+    },
+    "CustomTestInner": {
+      "type": "object",
+      "properties": {
+        "args": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnyValue"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "config": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/DataTestConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "CustomTestMultiKey": {
+      "type": "object",
+      "required": [
+        "test_name"
+      ],
+      "properties": {
+        "args": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/AnyValue"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "config": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/DataTestConfig"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "description": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "test_name": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
     "DataTestConfig": {
       "type": "object",
       "properties": {
@@ -1030,7 +1125,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -1225,7 +1319,9 @@
         {
           "$ref": "#/definitions/AcceptedValuesTest"
         },
-        true
+        {
+          "$ref": "#/definitions/CustomTest"
+        }
       ]
     },
     "DbtBatchSize": {
@@ -2234,13 +2330,9 @@
           ]
         },
         "offset_window": {
-          "anyOf": [
-            {
-              "$ref": "#/definitions/MetricTimeWindow"
-            },
-            {
-              "type": "null"
-            }
+          "type": [
+            "string",
+            "null"
           ]
         }
       },
@@ -2287,23 +2379,6 @@
       },
       "additionalProperties": false
     },
-    "MetricTimeWindow": {
-      "type": "object",
-      "required": [
-        "count",
-        "granularity"
-      ],
-      "properties": {
-        "count": {
-          "type": "integer",
-          "format": "int32"
-        },
-        "granularity": {
-          "type": "string"
-        }
-      },
-      "additionalProperties": false
-    },
     "MetricType": {
       "type": "string",
       "enum": [
@@ -3004,7 +3079,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -3212,6 +3286,16 @@
               "type": "null"
             }
           ]
+        },
+        "updates_on": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/UpdatesOn"
+            },
+            {
+              "type": "null"
+            }
+          ]
         }
       },
       "additionalProperties": false
@@ -4139,7 +4223,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -4854,7 +4937,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -5430,7 +5512,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -6149,7 +6230,6 @@
           ]
         },
         "require_partition_filter": {
-          "default": false,
           "type": [
             "boolean",
             "null"
@@ -6338,6 +6418,13 @@
       },
       "additionalProperties": false
     },
+    "UpdatesOn": {
+      "type": "string",
+      "enum": [
+        "any",
+        "all"
+      ]
+    },
     "Versions": {
       "type": "object",
       "required": [

core/dbt/parser/generic_test_builders.py

@@ -2,6 +2,7 @@
 from copy import deepcopy
 from typing import Any, Dict, Generic, List, Optional, Tuple
 
+from dbt import deprecations
 from dbt.artifacts.resources import NodeVersion
 from dbt.clients.jinja import GENERIC_TEST_KWARGS_NAME, get_rendered
 from dbt.contracts.graph.nodes import UnpatchedSourceDefinition
@@ -18,6 +19,7 @@
     TestTypeError,
     UnexpectedTestNamePatternError,
 )
+from dbt.flags import get_flags
 from dbt.parser.common import Testable
 from dbt.utils import md5
 from dbt_common.exceptions.macros import UndefinedMacroError
@@ -227,6 +229,20 @@ def extract_test_args(data_test, name=None) -> Tuple[str, Dict[str, Any]]:
         test_args = deepcopy(test_args)
         if name is not None:
             test_args["column_name"] = name
+
+        # Extract kwargs when they are nested under new 'arguments' property separately from 'config' if require_generic_test_arguments_property is enabled
+        if get_flags().require_generic_test_arguments_property:
+            arguments = test_args.pop("arguments", {})
+            if not arguments and any(k not in ("config", "column_name") for k in test_args.keys()):
+                deprecations.warn(
+                    "missing-arguments-property-in-generic-test-deprecation", test_name=test_name
+                )
+            test_args = {**test_args, **arguments}
+        elif "arguments" in test_args:
+            deprecations.warn(
+                "arguments-property-in-generic-test-deprecation", test_name=test_name
+            )
+
         return test_name, test_args
 
     def tags(self) -> List[str]:

core/setup.py

@@ -74,7 +74,7 @@
         # Minor versions for these are expected to be backwards-compatible
         "dbt-common>=1.27.0,<2.0",
         "dbt-adapters>=1.15.2,<2.0",
-        "dbt-protos>=1.0.339,<2.0",
+        "dbt-protos>=1.0.346,<2.0",
         "pydantic<3",
         # ----
         # Expect compatibility with all new versions of these packages, so lower bounds only.