Change details type to dict

Align type with Test Engine, simplify implementation.

Author: scadu

src/buildkite_test_collector/collector/payload.py

@@ -40,12 +40,20 @@ class TestSpan:
 
     Buildkite Test Analtics supports some basic tracing to allow insight into
     the runtime performance your tests.
+
+    The detail field should be a dict matching the expected format for each section type:
+    - sql: {"query": str}
+    - annotation: {"content": str}
+    - http: {"method": str, "url": str, "lib": str}
+    - sleep: no detail required
+
+    See: https://buildkite.com/docs/test-engine/test-collection/importing-json#json-test-results-data-reference-detail-objects
     """
     section: Literal['http', 'sql', 'sleep', 'annotation']
     duration: timedelta
     start_at: Optional[Instant] = None
     end_at: Optional[Instant] = None
-    detail: Optional[str] = None
+    detail: Optional[Dict[str, str]] = None
 
     def as_json(self, started_at: Instant) -> JsonDict:
         """Convert this span into a Dict for eventual serialisation into JSON"""
@@ -55,31 +63,7 @@ def as_json(self, started_at: Instant) -> JsonDict:
         }
 
         if self.detail is not None:
-            # Format detail based on section type to match the expected Avro schema
-            # pylint: disable=C0301
-            # See: https://buildkite.com/docs/test-analytics/importing-json#json-test-results-data-reference-span-objects
-            if self.section == "sql":
-                attrs["detail"] = {"query": self.detail}
-            elif self.section == "annotation":
-                attrs["detail"] = {"content": self.detail}
-            elif self.section == "http":
-                # For HTTP spans, the detail should be a dict with method, url, lib
-                # If it's a string, handle it gracefully
-                if isinstance(self.detail, dict):
-                    attrs["detail"] = self.detail
-                else:
-                    # Fallback: if provided a string, treat it as a URL
-                    attrs["detail"] = {
-                        "method": "GET",
-                        "url": self.detail,
-                        "lib": "unknown"
-                    }
-            elif self.section == "sleep":
-                # Sleep spans don't need detail
-                pass
-            else:
-                # For unknown/custom sections, keep detail as-is
-                attrs["detail"] = self.detail
+            attrs["detail"] = self.detail
 
         if self.start_at is not None:
             attrs["start_at"] = (self.start_at - started_at).total_seconds()

src/buildkite_test_collector/pytest_plugin/span_collector.py

@@ -32,17 +32,27 @@ def record(self, span: TestSpan) -> None:
 
     @contextmanager
     def measure(self, section: Literal['http', 'sql', 'sleep', 'annotation'],
-                detail: Optional[str] = None) -> Any:
+                detail: Optional[dict] = None) -> Any:
         """
         Measure the execution time of some code and record it as a span.
 
+        The detail parameter should be a dict matching the expected format for each section type:
+        - sql: {"query": str}
+        - annotation: {"content": str}
+        - http: {"method": str, "url": str, "lib": str}
+        - sleep: no detail required
+
         Example:
 
         .. code-block:: python
 
             def test_measure_http_request(spans):
-                with spans.measure('http', 'The koan of Github'):
+                with spans.measure('http', {'method': 'GET', 'url': 'https://api.github.com/zen', 'lib': 'requests'}):
                     requests.get("https://api.github.com/zen")
+
+            def test_measure_sql_query(spans):
+                with spans.measure('sql', {'query': 'SELECT * FROM users'}):
+                    db.execute('SELECT * FROM users')
         """
         start_at = Instant.now()
         try:

tests/buildkite_test_collector/pytest_plugin/test_span_collector.py

@@ -7,7 +7,8 @@
 def test_record_adds_span_to_plugin(span_collector):
     span_collector.record(TestSpan(
         section='http',
-        duration=timedelta(seconds=3)))
+        duration=timedelta(seconds=3),
+        detail={'method': 'GET', 'url': 'https://example.com', 'lib': 'requests'}))
 
     assert len(span_collector.current_test().history.children) == 1