Merge branch 'feat/TG-1134-external-url-custom-metadata' into 'enterprise'

TG-1134: External URL and custom metadata on test definitions

See merge request dkinternal/testgen/dataops-testgen!576

Author: ci bot

testgen/common/models/test_definition.py

@@ -1,3 +1,4 @@
+import json
 from collections.abc import Iterable
 from dataclasses import dataclass
 from datetime import UTC, datetime
@@ -135,6 +136,28 @@ def _is_blank(value: object) -> bool:
     return value is None or value == ""
 
 
+CUSTOM_METADATA_MAX_KEYS = 50
+CUSTOM_METADATA_MAX_BYTES = 10_240
+
+
+def validate_custom_metadata(value: object) -> str | None:
+    """Return an error message if ``value`` is not a valid ``custom_metadata`` payload, else ``None``.
+
+    ``custom_metadata`` must be a JSON object (key-value pairs), bounded in key count and serialized
+    size. Shared by every write path — ``TestDefinition.validate`` (UI/CLI/MCP) and the
+    ``TestDefinitionExport`` import schema — so the rule has a single definition.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        return "must be a JSON object of key-value pairs"
+    if len(value) > CUSTOM_METADATA_MAX_KEYS:
+        return f"must have at most {CUSTOM_METADATA_MAX_KEYS} keys"
+    if len(json.dumps(value)) > CUSTOM_METADATA_MAX_BYTES:
+        return f"must be at most {CUSTOM_METADATA_MAX_BYTES} bytes when serialized as JSON"
+    return None
+
+
 class ParamFieldsMixin:
     """Parsed access to default_parm_columns/prompts/help metadata.
 
@@ -224,6 +247,8 @@ class TestDefinitionSummary(TestTypeSummary):
     prediction: dict[str, dict[str, float]] | None
     flagged: bool
     impact_dimension: str | None
+    external_url: str | None
+    custom_metadata: dict | None
 
     @property
     def display_name(self) -> str:
@@ -397,6 +422,8 @@ class TestDefinition(Entity):
     flagged: bool = Column(Boolean, default=False, nullable=False)
     external_id: UUID | None = Column(postgresql.UUID(as_uuid=True))
     impact_dimension: str | None = Column(String, nullable=True)
+    external_url: str | None = Column(NullIfEmptyString)
+    custom_metadata: dict | None = Column(postgresql.JSONB)
 
     _default_order_by = (
         asc(func.lower(schema_name)),
@@ -555,14 +582,16 @@ def select_page(
     # Fields editable on every test type regardless of param_columns.
     EDITABLE_BASE_FIELDS: ClassVar[frozenset[str]] = frozenset({
         "test_active", "severity", "lock_refresh", "flagged", "test_description",
+        "external_url", "custom_metadata",
     })
 
     def editable_fields(self, test_type: TestType) -> set[str]:
         """Fields a caller may set or change on this test definition under the given test type."""
         fields = self.EDITABLE_BASE_FIELDS | test_type.param_columns
-        # column_name is meaningful for column-scoped tests (the column under test) and
-        # custom-scoped tests (a "Test Focus" label). Other scopes don't use it.
-        if test_type.test_scope in ("column", "custom"):
+        # column_name is meaningful for column-scoped tests (the column under test),
+        # custom-scoped tests (a "Test Focus" label), and referential tests (the aggregate
+        # expression or categorical column list under test). Table-scoped tests don't use it.
+        if test_type.test_scope in ("column", "custom", "referential"):
             fields = fields | {"column_name"}
         # impact_dimension is overridable only for user-defined-semantic scopes
         # (custom-scope = user-authored SQL; referential-scope = comparison-based tests).
@@ -588,9 +617,10 @@ def validate(self, test_type: TestType) -> None:
                     f"(got `{self.severity}`)"
                 )
 
-        # column_name applies to column-scoped tests (the column under test) and
-        # custom-scoped tests (a "Test Focus" label). Other scopes don't use it.
-        if test_type.test_scope not in ("column", "custom") and not _is_blank(self.column_name):
+        # column_name applies to column-scoped tests (the column under test),
+        # custom-scoped tests (a "Test Focus" label), and referential tests (the aggregate
+        # expression or categorical column list under test). Table-scoped tests don't use it.
+        if test_type.test_scope not in ("column", "custom", "referential") and not _is_blank(self.column_name):
             errors["column_name"] = (
                 f"test type `{test_type.test_type}` has scope `{test_type.test_scope}`; "
                 f"column_name does not apply to this scope"
@@ -601,6 +631,10 @@ def validate(self, test_type: TestType) -> None:
                 f"test type `{test_type.test_type}` does not accept a custom query"
             )
 
+        metadata_error = validate_custom_metadata(self.custom_metadata)
+        if metadata_error:
+            errors["custom_metadata"] = metadata_error
+
         for required in _required_fields_for(test_type):
             if _is_blank(getattr(self, required, None)):
                 errors[required] = f"required for test type `{test_type.test_type}`"

testgen/common/test_definition_export_import_service.py

@@ -14,7 +14,7 @@
 from testgen.common.models import get_current_session
 from testgen.common.models.data_table import DataTable
 from testgen.common.models.table_group import TableGroup
-from testgen.common.models.test_definition import TestDefinition, TestType
+from testgen.common.models.test_definition import TestDefinition, TestType, validate_custom_metadata
 from testgen.common.models.test_suite import TestSuite
 
 EXPORT_FORMAT_VERSION = 1
@@ -129,11 +129,26 @@ class TestDefinitionExport(BaseModel):
     history_calculation_upper: str | None = None
     history_lookback: int = 0
 
+    # URL / metadata
+    external_url: str | None = None
+    custom_metadata: dict[str, Any] | None = None
+
     @field_validator("skip_errors", "window_days", "history_lookback", mode="before")
     @classmethod
     def _coerce_none_to_zero(cls, v: int | None) -> int:
         return v if v is not None else 0
 
+    @field_validator("custom_metadata")
+    @classmethod
+    def _check_custom_metadata(cls, v: dict[str, Any] | None) -> dict[str, Any] | None:
+        # The import path does not run TestDefinition.validate(), so this is the only enforcement
+        # of the custom_metadata shape/size bound on import. Shares validate_custom_metadata with
+        # the model so the rule has a single definition.
+        error = validate_custom_metadata(v)
+        if error:
+            raise ValueError(f"custom_metadata {error}")
+        return v
+
 
 class ExportSource(BaseModel):
     project_code: str

testgen/mcp/tools/test_definitions.py

@@ -1,3 +1,4 @@
+import json
 from datetime import UTC, datetime
 from enum import StrEnum
 from typing import NoReturn
@@ -242,6 +243,14 @@ def _append_td_summary(doc: MdDoc, td: TestDefinitionSummary) -> None:
     elif td.last_auto_gen_date:
         doc.field("Last Updated", f"{td.last_auto_gen_date} (auto-generated)")
 
+    # URL and metadata
+    if td.external_url:
+        doc.field("External URL", td.external_url)
+    if td.custom_metadata:
+        doc.heading(2, "Custom Metadata")
+        for key, value in td.custom_metadata.items():
+            doc.field(MdDoc.escape(key), value)
+
     # Parameters (editable fields from test type metadata)
     _append_parameters_section(doc, td)
 
@@ -506,6 +515,25 @@ def _raise_validation_errors(err: InvalidTestDefinitionFields, header: str) -> N
     raise MCPUserError(f"{header}\n\n{bullets}") from err
 
 
+def _coerce_custom_metadata(fields: dict) -> None:
+    """Accept ``custom_metadata`` as a JSON string for convenience, parsing it to an object in place.
+
+    A blank string becomes ``None`` (clears the field). Non-object JSON is left for model
+    validation to reject with a consistent message.
+    """
+    value = fields.get("custom_metadata")
+    if not isinstance(value, str):
+        return
+    stripped = value.strip()
+    if not stripped:
+        fields["custom_metadata"] = None
+        return
+    try:
+        fields["custom_metadata"] = json.loads(stripped)
+    except json.JSONDecodeError as e:
+        raise MCPUserError("`custom_metadata` must be a JSON object of key-value pairs.") from e
+
+
 @with_database_session
 @mcp_permission("edit")
 def create_test(
@@ -547,6 +575,7 @@ def create_test(
     )
 
     fields = fields or {}
+    _coerce_custom_metadata(fields)
     accepted = td.editable_fields(tt)
     rejected = sorted(set(fields) - accepted)
     if rejected:
@@ -591,6 +620,7 @@ def update_test(test_definition_id: str, fields: dict) -> str:
     if not fields:
         raise MCPUserError("No fields supplied to update.")
 
+    _coerce_custom_metadata(fields)
     accepted = td.editable_fields(tt)
     rejected = sorted(set(fields) - accepted)
     if rejected:

testgen/mcp/tools/test_results.py

@@ -6,7 +6,7 @@
 from testgen.common.enums import JobStatus
 from testgen.common.models import get_current_session, with_database_session
 from testgen.common.models.job_execution import JobExecution
-from testgen.common.models.test_definition import TestType
+from testgen.common.models.test_definition import TestDefinition, TestType
 from testgen.common.models.test_result import BucketInterval, TestResult, TestResultStatus
 from testgen.common.models.test_run import TestRun, TestRunSummary
 from testgen.common.models.test_suite import TestSuite
@@ -130,6 +130,12 @@ def list_test_results(
 
     type_names = {tt.test_type: tt.test_name_short for tt in TestType.select_where(TestType.active == "Y")}
 
+    td_ids = {r.test_definition_id for r in results if r.test_definition_id}
+    source_by_td = {
+        td.id: (td.external_url, td.custom_metadata)
+        for td in (TestDefinition.select_where(TestDefinition.id.in_(td_ids)) if td_ids else [])
+    }
+
     doc = MdDoc()
     doc.heading(1, f"Test Results for run `{run_id_label}`")
     if resolved_via_suite:
@@ -153,6 +159,13 @@ def list_test_results(
             doc.field("Threshold", r.threshold_value)
         if r.message:
             doc.field("Message", r.message)
+        external_url, custom_metadata = source_by_td.get(r.test_definition_id, (None, None))
+        if external_url:
+            doc.field("External URL", external_url)
+        if custom_metadata:
+            doc.heading(3, "Custom Metadata")
+            for key, value in custom_metadata.items():
+                doc.field(MdDoc.escape(key), value)
 
     return doc.render()
 

testgen/template/dbsetup/030_initialize_new_schema_structure.sql

@@ -241,6 +241,8 @@ CREATE TABLE test_definitions (
    flagged                BOOLEAN DEFAULT FALSE NOT NULL,
    external_id            UUID,
    impact_dimension       VARCHAR(20),
+   external_url           VARCHAR,
+   custom_metadata        JSONB,
    CONSTRAINT test_definitions_test_suites_test_suite_id_fk
       FOREIGN KEY (test_suite_id) REFERENCES test_suites
 );

testgen/template/dbupgrade/0197_incremental_upgrade.sql

@@ -0,0 +1,5 @@
+SET SEARCH_PATH TO {SCHEMA_NAME};
+
+ALTER TABLE test_definitions
+    ADD COLUMN IF NOT EXISTS external_url    VARCHAR,
+    ADD COLUMN IF NOT EXISTS custom_metadata JSONB;

testgen/ui/components/frontend/js/pages/test_definition_summary.js

@@ -17,19 +17,25 @@
  * @property {string} export_to_observability
  * @property {string?} last_manual_update
  * @property {string?} usage_notes
+ * @property {string?} external_url
+ * @property {object?} custom_metadata
  * @property {Array<TestDefinitionAttribute>} attributes
- * 
+ *
  * @typedef Properties
  * @type {object}
  * @property {TestDefinition} test_definition
  */
 import van from '/app/static/js/van.min.js';
-import { createEmitter, getValue, isEqual, loadStylesheet } from '/app/static/js/utils.js';
+import { createEmitter, getValue, isEqual, isHttpUrl, loadStylesheet } from '/app/static/js/utils.js';
 import { Alert } from '/app/static/js/components/alert.js';
 import { Attribute } from '/app/static/js/components/attribute.js';
+import { Link } from '/app/static/js/components/link.js';
 
 const { div, strong } = van.tags;
 
+const metadataDisplayValue = (value) =>
+    (value !== null && typeof value === 'object') ? JSON.stringify(value) : value;
+
 /**
  * @param {Properties} props 
  * @returns 
@@ -112,6 +118,37 @@ const TestDefinitionSummary = (props) => {
                         ),
                     ),
                 ),
+                testDefinition.external_url
+                    ? Attribute({
+                        label: 'External URL',
+                        value: isHttpUrl(testDefinition.external_url)
+                            ? Link({
+                                href: testDefinition.external_url.trim(),
+                                label: testDefinition.external_url.trim(),
+                                open_new: true,
+                                right_icon: 'open_in_new',
+                                right_icon_size: 16,
+                            })
+                            : testDefinition.external_url,
+                        class: 'mt-4 external-url-attribute',
+                      })
+                    : '',
+                testDefinition.custom_metadata && Object.keys(testDefinition.custom_metadata).length
+                    ? div(
+                        { class: 'flex-column fx-gap-3 mt-4' },
+                        strong({}, 'Custom Metadata'),
+                        div(
+                            { class: 'flex-row fx-flex-wrap fx-gap-4 test-definition-attributes' },
+                            Object.entries(testDefinition.custom_metadata).map(([key, value]) =>
+                                Attribute({
+                                    label: key,
+                                    value: metadataDisplayValue(value),
+                                    class: 'fx-flex',
+                                })
+                            ),
+                        ),
+                      )
+                    : '',
                 testDefinition.usage_notes
                     ? Alert(
                         { type: 'info', class: 'mt-4' },
@@ -132,6 +169,20 @@ stylesheet.replace(`
 .test-definition-attributes > div .attribute-value {
     font-size: 16px;
 }
+.external-url-attribute .attribute-value {
+    overflow-wrap: anywhere;
+}
+.external-url-attribute .tg-link {
+    max-width: 100%;
+}
+.external-url-attribute .tg-link--wrapper {
+    flex-wrap: wrap;
+}
+.external-url-attribute .tg-link--text {
+    overflow-wrap: anywhere;
+    word-break: break-all;
+    min-width: 0;
+}
 `);
 
 export { TestDefinitionSummary };