test contracts

backend/src/api/routes/reports.py

@@ -62,6 +62,20 @@ def _parse_csv_enum_list(raw: Optional[str], enum_cls, field_name: str) -> List:
 # @PRE: authenticated/authorized request and validated query params.
 # @POST: returns {items,total,page,page_size,has_next,applied_filters}.
 # @POST: deterministic error payload for invalid filters.
+#
+# @TEST_CONTRACT: ListReportsApi ->
+# {
+#   required_fields: {page: int, page_size: int, sort_by: str, sort_order: str},
+#   optional_fields: {task_types: str, statuses: str, search: str},
+#   invariants: [
+#       "Returns ReportCollection on success",
+#       "Raises HTTPException 400 for invalid query parameters"
+#   ]
+# }
+# @TEST_FIXTURE: valid_list_request -> {"page": 1, "page_size": 20}
+# @TEST_EDGE: invalid_task_type_filter -> raises HTTPException(400)
+# @TEST_EDGE: malformed_query -> raises HTTPException(400)
+# @TEST_INVARIANT: consistent_list_payload -> verifies: [valid_list_request]
 @router.get("", response_model=ReportCollection)
 async def list_reports(
     page: int = Query(1, ge=1),