:feat(test-definitions): faceted add-test picker dialog

Add a faceted picker to the Add-Test dialog so users browse and search
test types by taxonomy (algorithm, statistical technique) and column type
before advancing to the existing parameter form. Persists the taxonomy
fields on test types and surfaces them, with column-type metadata, to the dialog.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: luis-dk

testgen/common/models/test_definition.py

@@ -9,6 +9,7 @@
 from sqlalchemy import (
     Boolean,
     Column,
+    Enum,
     ForeignKey,
     String,
     Text,
@@ -40,6 +41,87 @@ class Severity(StrEnum):
     WARNING = "Warning"
 
 
+class TestAlgorithm(StrEnum):
+    """SQL-derived algorithm family for a test type (faceted picker axis)."""
+
+    BOUNDARY_CHECK = "Boundary check"
+    COUNTING = "Counting"
+    PATTERN_REGEX = "Pattern / regex"
+    SET_LOOKUP = "Set / lookup"
+    STATISTICAL_DRIFT = "Statistical drift"
+    AGGREGATE_RECONCILIATION = "Aggregate reconciliation"
+    FRESHNESS_TIME = "Freshness / time"
+    SCHEMA_METADATA = "Schema / metadata"
+    CUSTOM_SQL = "Custom SQL"
+
+
+class StatisticalTechnique(StrEnum):
+    """Named statistical technique a test type uses to evaluate its measure."""
+
+    COHENS_D = "Cohen's D"
+    COHENS_H = "Cohen's H"
+    OUTLIER_DETECTION = "Outlier Detection"
+    SD_SHIFT = "SD Shift"
+    JENSEN_SHANNON_DIVERGENCE = "Jensen-Shannon Divergence"
+    PREDICTIVE_MODEL = "Predictive Model"
+
+
+class TestCriteria(StrEnum):
+    """What a test type needs to be set up (faceted picker axis).
+
+    Derived, not stored: ``derive_test_criteria`` is the single source of truth, shared by the
+    UI lookup and MCP so the value never drifts between surfaces.
+    """
+
+    DEFINED_RULE = "Defined Rule"
+    DEFINED_THRESHOLD = "Defined Threshold"
+    DEFINED_VALUE = "Defined Value"
+    LIST_OF_VALUES = "List of Values"
+    REFERENCE_DATASET = "Reference Dataset"
+    CUSTOM_CRITERIA = "Custom Criteria"
+
+
+# Predefined validity/integrity rules — the user just enables them; the rule itself is fixed
+# (dedup/uniqueness and standard format validators). Not separable from structural attributes
+# alone: e.g. Valid_Month is structurally identical to the Defined-Value test Pattern_Match
+# (both column-scoped, Pattern / regex, with baseline_value + threshold_value params).
+_DEFINED_RULE_TESTS = frozenset({
+    "Dupe_Rows", "Unique", "Email_Format", "Street_Addr_Pattern",
+    "Valid_Characters", "Valid_Month", "Valid_US_Zip", "Valid_US_Zip3",
+})
+# The user asserts the expected value/pattern the column should hold (a constant, a regex
+# baseline, or simply that a value is present). Enumerated for the same reason as above.
+_DEFINED_VALUE_TESTS = frozenset({
+    "Constant", "Pattern_Match", "Required",
+})
+
+
+def derive_test_criteria(
+    test_type: str,
+    test_scope: str | None,
+    algorithm: str | None,
+) -> TestCriteria:
+    """Classify a test type by the kind of setup it requires.
+
+    Single source of truth for the Criteria facet — call from both the UI lookup and MCP rather
+    than reproducing the rules. Scope and algorithm resolve the cleanly-typed buckets (referential
+    is checked before Set / lookup so Combo_Match stays Reference Dataset). Defined Rule, Defined
+    Value, and Defined Threshold can't be told apart from structural attributes, so the first two
+    are enumerated and Defined Threshold is the fallthrough.
+    """
+    if test_scope == "custom":
+        return TestCriteria.CUSTOM_CRITERIA
+    if test_scope == "referential":
+        return TestCriteria.REFERENCE_DATASET
+    if algorithm == TestAlgorithm.SET_LOOKUP:
+        return TestCriteria.LIST_OF_VALUES
+    if test_type in _DEFINED_RULE_TESTS:
+        return TestCriteria.DEFINED_RULE
+    if test_type in _DEFINED_VALUE_TESTS:
+        return TestCriteria.DEFINED_VALUE
+    return TestCriteria.DEFINED_THRESHOLD
+
+
 class InvalidTestDefinitionFields(ValueError):
     """Aggregated field-level validation errors. ``errors``: ``dict[field_name, reason]``."""
 
@@ -175,6 +257,15 @@ def process_bind_param(self, value: str | None, _dialect) -> str | None:
         return value or None
 
 
+def _enum_by_value(enum_cls: type[StrEnum]) -> Enum:
+    """Map a StrEnum to its VARCHAR column by member value (not name) so reads return enum members.
+
+    These columns store the display value (e.g. ``"Boundary check"``), which differs from the enum
+    member name, so the default name-based mapping would not round-trip.
+    """
+    return Enum(enum_cls, native_enum=False, values_callable=lambda cls: [member.value for member in cls])
+
+
 class TestType(ParamFieldsMixin, Entity):
     __tablename__ = "test_types"
 
@@ -204,12 +295,19 @@ class TestType(ParamFieldsMixin, Entity):
     dq_dimension: str = Column(String)
     impact_dimension: str = Column(String)
     health_dimension: str = Column(String)
+    algorithm: TestAlgorithm | None = Column(_enum_by_value(TestAlgorithm))
+    statistical_technique: StatisticalTechnique | None = Column(_enum_by_value(StatisticalTechnique))
     threshold_description: str = Column(String)
     usage_notes: str = Column(String)
     active: str = Column(String)
 
     # Unmapped columns: generation_template, result_visualization, result_visualization_params
 
+    @property
+    def criteria(self) -> TestCriteria:
+        """Setup-kind facet, derived via the shared classifier (see ``derive_test_criteria``)."""
+        return derive_test_criteria(self.test_type, self.test_scope, self.algorithm)
+
     _summary_columns = (
         *[key for key in TestTypeSummary.__annotations__.keys() if key not in ("default_test_description", "default_impact_dimension")],
         test_description.label("default_test_description"),

testgen/template/dbsetup/030_initialize_new_schema_structure.sql

@@ -576,6 +576,8 @@ CREATE TABLE test_types (
    dq_dimension                  VARCHAR(50),
    impact_dimension              VARCHAR(20),
    health_dimension              VARCHAR(50),
+   algorithm                     VARCHAR(64),
+   statistical_technique         VARCHAR(64),
    threshold_description         VARCHAR(200),
    result_visualization          VARCHAR(50) DEFAULT 'line_chart',
    result_visualization_params   TEXT DEFAULT NULL,

testgen/template/dbsetup_test_types/test_types_Aggregate_Balance.yaml

@@ -37,6 +37,7 @@ test_types:
   usage_notes: |-
     This test compares sums or counts of a column rolled up to one or more category combinations across two different tables. Both tables must be accessible at the same time. It's ideal for confirming that two datasets exactly match -- that the sum of a measure or count of a value hasn't changed or shifted between categories. Use this test to compare a raw and processed version of the same dataset, or to confirm that an aggregated table exactly matches the detail table that it's built from. An error here means that one or more value combinations fail to match. New categories or combinations will cause failure.
   active: Y
+  algorithm: Aggregate reconciliation
   cat_test_conditions: []
   target_data_lookups:
   - id: '1400'

testgen/template/dbsetup_test_types/test_types_Aggregate_Balance_Percent.yaml

@@ -37,6 +37,7 @@ test_types:
   usage_notes: |-
     This test compares sums or counts of a column rolled up to one or more category combinations across two different tables. Both tables must be accessible at the same time. Use it to confirm that two datasets closely match within the tolerance you set -- that the sum of a measure or count of a value remains sufficiently consistent between categories. You could use this test compare sales per product within one month to another, when you want to be alerted if the difference for any product falls outside of the range defined as 5% below to 10% above the prior month. An error here means that one or more value combinations fail to match within the set tolerances. New categories or combinations will cause failure.
   active: Y
+  algorithm: Aggregate reconciliation
   cat_test_conditions: []
   target_data_lookups:
   - id: '1404'

testgen/template/dbsetup_test_types/test_types_Aggregate_Balance_Range.yaml

@@ -37,6 +37,7 @@ test_types:
   usage_notes: |-
     This test compares sums or counts of a column rolled up to one or more category combinations across two different tables. Both tables must be accessible at the same time. Use it to confirm that two datasets closely match within the tolerances you define as specific values above or below the aggregate measure for the same categories in the reference dataset -- that the sum of a measure or count of a value remains sufficiently consistent between categories. For instance, you can use this test to compare sales per product within one month to another, when you want to be alerted if the difference for any product falls outside of the range defined as 10000 dollars above or below the prior week. An error here means that one or more value combinations fail to match within the set tolerances. New categories or combinations will cause failure.
   active: Y
+  algorithm: Aggregate reconciliation
   cat_test_conditions: []
   target_data_lookups:
   - id: '1405'

testgen/template/dbsetup_test_types/test_types_Aggregate_Minimum.yaml

@@ -37,6 +37,7 @@ test_types:
   usage_notes: |-
     This test compares sums or counts of a column rolled up to one or more category combinations, but requires a match or increase in the aggregate value, rather than an exact match, across two different tables. Both tables must be accessible at the same time. Use this to confirm that aggregate values have not dropped for any set of categories, even if some values may rise. This test is useful to compare an older and newer version of a cumulative dataset. An error here means that one or more values per category set fail to match or exceed the prior dataset. New categories or combinations are allowed (but can be restricted independently with a Combo_Match test). Both tables must be present to run this test.
   active: Y
+  algorithm: Aggregate reconciliation
   cat_test_conditions: []
   target_data_lookups:
   - id: '1401'

testgen/template/dbsetup_test_types/test_types_Alpha_Trunc.yaml

@@ -36,6 +36,7 @@ test_types:
   usage_notes: |-
     Alpha Truncation tests that the longest text value in a column hasn't become shorter than the defined threshold, initially 95% of the longest value at baseline. This could indicate a problem in a cumulative dataset, where prior values should still exist unchanged. A failure here would suggest that some process changed data that you would still expect to be present and matching its value when the column was profiled. This test would not be appropriate for an incremental or windowed dataset.
   active: Y
+  algorithm: Boundary check
   cat_test_conditions:
   - id: '7001'
     test_type: Alpha_Trunc

testgen/template/dbsetup_test_types/test_types_Avg_Shift.yaml

@@ -37,6 +37,8 @@ test_types:
   usage_notes: |-
     Average Shift tests that the average of a numeric column has not significantly changed since baseline, when profiling was done. A significant shift may indicate errors in processing, differences in source data, or valid changes that may nevertheless impact assumptions in downstream data products. The test uses Cohen's D, a statistical technique to identify significant shifts in a value. Cohen's D measures the difference between the two averages, reporting results on a standardized scale, which can be interpreted via a rule-of-thumb from small to huge. Depending on your data, some difference may be expected, so it's reasonable to adjust the threshold value that triggers test failure. This test works well for measures, or even for identifiers if you expect them to increment consistently. You may want to periodically adjust the expected threshold, or even the expected average value if you expect shifting over time. Consider this test along with Variability Increase. If variability rises too, process or measurement flaws could be at work. If variability remains consistent, the issue is more likely to be with the source data itself.
   active: Y
+  algorithm: Statistical drift
+  statistical_technique: Cohen's D
   cat_test_conditions:
   - id: '7002'
     test_type: Avg_Shift

testgen/template/dbsetup_test_types/test_types_CUSTOM.yaml

@@ -38,6 +38,7 @@ test_types:
   usage_notes: |-
     This business-rule test is highly flexible, covering any error state that can be expressed by a SQL query against one or more tables in the database. In operation, the user-defined query is embedded within a parent query returning the count of error rows identified. Any row returned by the query is interpreted as a single error condition in the test. Note that this query is run independently of other tests, and that performance will be slower, depending in large part on the efficiency of the query you write. Interpretation is based on the user-defined meaning of the test. Your query might be written to return errors in individual rows identified by joining tables. Or it might return an error based on a multi-column aggregate condition returning a single row if an error is found. This query is run separately when you click `Review Source Data` from Test Results, so be sure to include enough data in your results to follow-up. Interpretation is based on the user-defined meaning of the test.
   active: Y
+  algorithm: Custom SQL
   cat_test_conditions: []
   target_data_lookups: []
   test_templates:

testgen/template/dbsetup_test_types/test_types_Combo_Match.yaml

@@ -37,6 +37,7 @@ test_types:
   usage_notes: |-
     This test verifies that values, or combinations of values, that are present in the main table are also found in a reference table. This is a useful test for referential integrity between fact and dimension tables. You can also use it to confirm the validity of a code or category, or of combinations of values that should only be found together within each record, such as product/size/color.  An error here means that one  or more category combinations in the main table are not found in the reference table. Both tables must be present to run this test.
   active: Y
+  algorithm: Set / lookup
   cat_test_conditions: []
   target_data_lookups:
   - id: '1402'