Bamboo: Result ordering

 atlassian-api#1313

Author: gonchik

atlassian/bamboo.py

@@ -453,6 +453,7 @@ def results(
         start_index=0,
         max_results=25,
         include_all_states=False,
+        build_state=None,
     ):
         """
         Get results as generic method
@@ -468,6 +469,8 @@ def results(
         :param start_index:
         :param max_results:
         :param include_all_states:
+        :param build_state: Optional Bamboo result state, such as
+            ``Successful`` or ``Failed``.
         :return:
         """
         resource = "result"
@@ -485,6 +488,8 @@ def results(
             params["issueKey"] = issue_key
         if include_all_states:
             params["includeAllStates"] = include_all_states
+        if build_state is not None:
+            params["buildstate"] = build_state
         return self.base_list_call(
             resource,
             expand=expand,
@@ -581,6 +586,7 @@ def plan_results(
         start_index=0,
         max_results=25,
         include_all_states=False,
+        build_state=None,
     ):
         """
         Get Plan results
@@ -594,6 +600,8 @@ def plan_results(
         :param start_index:
         :param max_results:
         :param include_all_states:
+        :param build_state: Optional Bamboo result state, such as
+            ``Successful`` or ``Failed``.
         :return:
         """
         return self.results(
@@ -607,8 +615,71 @@ def plan_results(
             start_index=start_index,
             max_results=max_results,
             include_all_states=include_all_states,
+            build_state=build_state,
         )
 
+    def ordered_plan_results(
+        self,
+        project_key,
+        plan_key,
+        order="descending",
+        build_state=None,
+        max_results=25,
+        **kwargs,
+    ):
+        """Return retrieved plan results ordered by completion time.
+
+        Bamboo's result API does not expose a server-side sort parameter. This
+        helper orders the result page client-side by ``buildCompletedTime``.
+        Set ``max_results`` high enough to include the history being compared;
+        this method returns a list rather than the lazy generator returned by
+        :meth:`plan_results`.
+
+        :param order: ``"ascending"`` for oldest first or ``"descending"``
+            for newest first.
+        :param build_state: Optional ``Successful`` or ``Failed`` filter.
+        :param max_results: Number of results Bamboo should return to sort.
+        :return: A list of build results ordered by completion time.
+        """
+        if order not in {"ascending", "descending"}:
+            raise ValueError("order must be 'ascending' or 'descending'")
+
+        results = self.plan_results(
+            project_key,
+            plan_key,
+            build_state=build_state,
+            max_results=max_results,
+            **kwargs,
+        )
+        return sorted(
+            results,
+            key=lambda result: result.get("buildCompletedTime") or "",
+            reverse=order == "descending",
+        )
+
+    def latest_successful_plan_result(self, project_key, plan_key, max_results=25, **kwargs):
+        """Return the newest successful plan result, or ``None`` when absent."""
+        results = self.ordered_plan_results(
+            project_key,
+            plan_key,
+            build_state="Successful",
+            max_results=max_results,
+            **kwargs,
+        )
+        return results[0] if results else None
+
+    def oldest_failed_plan_result(self, project_key, plan_key, max_results=25, **kwargs):
+        """Return the oldest failed plan result, or ``None`` when absent."""
+        results = self.ordered_plan_results(
+            project_key,
+            plan_key,
+            order="ascending",
+            build_state="Failed",
+            max_results=max_results,
+            **kwargs,
+        )
+        return results[0] if results else None
+
     def build_result(
         self,
         build_key,

docs/bamboo.rst

@@ -124,6 +124,10 @@ Build results
     plan_results(project_key, plan_key, expand=None, favourite=False, clover_enabled=False, label=None,
                  issue_key=None, start_index=0, max_results=25, include_all_states=False)
 
+    # Bamboo has no server-side result sort; order the retrieved history locally.
+    newest_success = bamboo.latest_successful_plan_result("PROJECT", "PLAN", max_results=1000)
+    oldest_failed = bamboo.oldest_failed_plan_result("PROJECT", "PLAN", max_results=1000)
+
     # Get a single build result
     build_result(build_key, expand=None, include_all_states=False)
 

tests/bamboo/test_bamboo.py

@@ -126,3 +126,39 @@ def test_project_linked_repository_methods(mock_get, mock_post, mock_delete):
     assert mock_get.call_args_list[1].args[0] == "rest/api/latest/project/PROJ/repository"
     mock_post.assert_called_once_with("rest/api/latest/project/PROJ/repository", data={"id": 42})
     mock_delete.assert_called_once_with("rest/api/latest/project/PROJ/repository/42")
+
+
+def test_ordered_plan_results_and_convenience_filters(monkeypatch):
+    bamboo = Bamboo("https://bamboo.example.test", token="token")
+    calls = []
+    results = [
+        {"buildCompletedTime": "2024-01-02T00:00:00.000Z", "state": "Failed"},
+        {"buildCompletedTime": "2024-01-03T00:00:00.000Z", "state": "Successful"},
+        {"buildCompletedTime": "2024-01-01T00:00:00.000Z", "state": "Failed"},
+    ]
+
+    def plan_results(project_key, plan_key, **kwargs):
+        calls.append((project_key, plan_key, kwargs))
+        return (result for result in results)
+
+    monkeypatch.setattr(bamboo, "plan_results", plan_results)
+
+    assert [result["buildCompletedTime"] for result in bamboo.ordered_plan_results("PROJ", "PLAN")] == [
+        "2024-01-03T00:00:00.000Z",
+        "2024-01-02T00:00:00.000Z",
+        "2024-01-01T00:00:00.000Z",
+    ]
+    assert bamboo.latest_successful_plan_result("PROJ", "PLAN")["state"] == "Successful"
+    assert bamboo.oldest_failed_plan_result("PROJ", "PLAN")["buildCompletedTime"] == "2024-01-01T00:00:00.000Z"
+    assert calls[1][2]["build_state"] == "Successful"
+    assert calls[2][2]["build_state"] == "Failed"
+
+
+@patch.object(Bamboo, "get")
+def test_plan_results_forwards_supported_build_state_filter(mock_get):
+    bamboo = Bamboo("https://bamboo.example.test", token="token")
+    mock_get.return_value = {"results": {"size": 0, "result": []}}
+
+    assert list(bamboo.plan_results("PROJ", "PLAN", build_state="Successful")) == []
+
+    assert mock_get.call_args.args[3]["buildstate"] == "Successful"