Add history field to flaky test management API (#3462)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -24023,6 +24023,22 @@ components:
           type: string
         flaky_state:
           $ref: '#/components/schemas/FlakyTestAttributesFlakyState'
+        history:
+          description: 'Chronological history of status changes for this flaky test,
+            ordered from most recent to oldest.
+
+            Includes state transitions like new -> quarantined -> fixed, along with
+            the associated commit SHA when available.'
+          example:
+          - commit_sha: abc123def456
+            status: quarantined
+            timestamp: 1704067200000
+          - commit_sha: ''
+            status: new
+            timestamp: 1703980800000
+          items:
+            $ref: '#/components/schemas/FlakyTestHistory'
+          type: array
         last_flaked_branch:
           description: The branch name where the test exhibited flakiness for the
             last time.
@@ -24107,6 +24123,29 @@ components:
       - FIXED
       - QUARANTINED
       - DISABLED
+    FlakyTestHistory:
+      description: A single history entry representing a status change for a flaky
+        test.
+      properties:
+        commit_sha:
+          description: The commit SHA associated with this status change. Will be
+            an empty string if the commit SHA is not available.
+          example: abc123def456
+          type: string
+        status:
+          description: The test status at this point in history.
+          example: quarantined
+          type: string
+        timestamp:
+          description: Unix timestamp in milliseconds when this status change occurred.
+          example: 1704067200000
+          format: int64
+          type: integer
+      required:
+      - status
+      - commit_sha
+      - timestamp
+      type: object
     FlakyTestPipelineStats:
       description: CI pipeline related statistics for the flaky test. This information
         is only available if test runs are associated with CI pipeline events from
@@ -24253,6 +24292,17 @@ components:
       properties:
         filter:
           $ref: '#/components/schemas/FlakyTestsSearchFilter'
+        include_history:
+          default: false
+          description: 'Whether to include the status change history for each flaky
+            test in the response.
+
+            When set to true, each test will include a `history` array with chronological
+            status changes.
+
+            Defaults to false.'
+          example: true
+          type: boolean
         page:
           $ref: '#/components/schemas/FlakyTestsSearchPageOptions'
         sort:
@@ -101085,8 +101135,33 @@ paths:
 
         If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).'
     post:
-      description: List endpoint returning flaky tests from Flaky Test Management.
+      description: 'List endpoint returning flaky tests from Flaky Test Management.
         Results are paginated.
+
+
+        The response includes comprehensive test information including:
+
+        - Test identification and metadata (module, suite, name)
+
+        - Flaky state and categorization
+
+        - First and last flake occurrences (timestamp, branch, commit SHA)
+
+        - Test execution statistics from the last 7 days (failure rate)
+
+        - Pipeline impact metrics (failed pipelines count, total lost time)
+
+        - Complete status change history (optional, ordered from most recent to oldest)
+
+
+        Set `include_history` to `true` in the request to receive the status change
+        history for each test.
+
+        History is disabled by default for better performance.
+
+
+        Results support filtering by various facets including service, environment,
+        repository, branch, and test state.'
       operationId: SearchFlakyTests
       requestBody:
         content:

examples/v2/test-optimization/SearchFlakyTests.java

@@ -31,6 +31,7 @@ public static void main(String[] args) {
                                         """
 flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
 """))
+                            .includeHistory(true)
                             .page(
                                 new FlakyTestsSearchPageOptions()
                                     .cursor(

examples/v2/test-optimization/SearchFlakyTests_1224086727.java

@@ -31,6 +31,7 @@ public static void main(String[] args) {
                                         """
 flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
 """))
+                            .includeHistory(true)
                             .page(
                                 new FlakyTestsSearchPageOptions()
                                     .cursor(

examples/v2/test-optimization/SearchFlakyTests_209064879.java

@@ -0,0 +1,51 @@
+// Search flaky tests returns "OK" response with history
+
+import com.datadog.api.client.ApiClient;
+import com.datadog.api.client.ApiException;
+import com.datadog.api.client.v2.api.TestOptimizationApi;
+import com.datadog.api.client.v2.api.TestOptimizationApi.SearchFlakyTestsOptionalParameters;
+import com.datadog.api.client.v2.model.FlakyTestsSearchFilter;
+import com.datadog.api.client.v2.model.FlakyTestsSearchPageOptions;
+import com.datadog.api.client.v2.model.FlakyTestsSearchRequest;
+import com.datadog.api.client.v2.model.FlakyTestsSearchRequestAttributes;
+import com.datadog.api.client.v2.model.FlakyTestsSearchRequestData;
+import com.datadog.api.client.v2.model.FlakyTestsSearchRequestDataType;
+import com.datadog.api.client.v2.model.FlakyTestsSearchResponse;
+import com.datadog.api.client.v2.model.FlakyTestsSearchSort;
+
+public class Example {
+  public static void main(String[] args) {
+    ApiClient defaultClient = ApiClient.getDefaultApiClient();
+    defaultClient.setUnstableOperationEnabled("v2.searchFlakyTests", true);
+    TestOptimizationApi apiInstance = new TestOptimizationApi(defaultClient);
+
+    FlakyTestsSearchRequest body =
+        new FlakyTestsSearchRequest()
+            .data(
+                new FlakyTestsSearchRequestData()
+                    .attributes(
+                        new FlakyTestsSearchRequestAttributes()
+                            .filter(
+                                new FlakyTestsSearchFilter()
+                                    .query(
+                                        """
+flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"
+"""))
+                            .page(new FlakyTestsSearchPageOptions().limit(10L))
+                            .sort(FlakyTestsSearchSort.FQN_ASCENDING)
+                            .includeHistory(true))
+                    .type(FlakyTestsSearchRequestDataType.SEARCH_FLAKY_TESTS_REQUEST));
+
+    try {
+      FlakyTestsSearchResponse result =
+          apiInstance.searchFlakyTests(new SearchFlakyTestsOptionalParameters().body(body));
+      System.out.println(result);
+    } catch (ApiException e) {
+      System.err.println("Exception when calling TestOptimizationApi#searchFlakyTests");
+      System.err.println("Status code: " + e.getCode());
+      System.err.println("Reason: " + e.getResponseBody());
+      System.err.println("Response headers: " + e.getResponseHeaders());
+      e.printStackTrace();
+    }
+  }
+}

src/main/java/com/datadog/api/client/v2/api/TestOptimizationApi.java

@@ -197,6 +197,18 @@ public PaginationIterable<FlakyTest> searchFlakyTestsWithPagination(
   /**
    * List endpoint returning flaky tests from Flaky Test Management. Results are paginated.
    *
+   * <p>The response includes comprehensive test information including: - Test identification and
+   * metadata (module, suite, name) - Flaky state and categorization - First and last flake
+   * occurrences (timestamp, branch, commit SHA) - Test execution statistics from the last 7 days
+   * (failure rate) - Pipeline impact metrics (failed pipelines count, total lost time) - Complete
+   * status change history (optional, ordered from most recent to oldest)
+   *
+   * <p>Set <code>include_history</code> to <code>true</code> in the request to receive the status
+   * change history for each test. History is disabled by default for better performance.
+   *
+   * <p>Results support filtering by various facets including service, environment, repository,
+   * branch, and test state.
+   *
    * @param parameters Optional parameters for the request.
    * @return ApiResponse&lt;FlakyTestsSearchResponse&gt;
    * @throws ApiException if fails to make API call

src/main/java/com/datadog/api/client/v2/model/FlakyTestAttributes.java

@@ -29,6 +29,7 @@
   FlakyTestAttributes.JSON_PROPERTY_FIRST_FLAKED_TS,
   FlakyTestAttributes.JSON_PROPERTY_FLAKY_CATEGORY,
   FlakyTestAttributes.JSON_PROPERTY_FLAKY_STATE,
+  FlakyTestAttributes.JSON_PROPERTY_HISTORY,
   FlakyTestAttributes.JSON_PROPERTY_LAST_FLAKED_BRANCH,
   FlakyTestAttributes.JSON_PROPERTY_LAST_FLAKED_SHA,
   FlakyTestAttributes.JSON_PROPERTY_LAST_FLAKED_TS,
@@ -68,6 +69,9 @@ public class FlakyTestAttributes {
   public static final String JSON_PROPERTY_FLAKY_STATE = "flaky_state";
   private FlakyTestAttributesFlakyState flakyState;
 
+  public static final String JSON_PROPERTY_HISTORY = "history";
+  private List<FlakyTestHistory> history = null;
+
   public static final String JSON_PROPERTY_LAST_FLAKED_BRANCH = "last_flaked_branch";
   private String lastFlakedBranch;
 
@@ -302,6 +306,41 @@ public void setFlakyState(FlakyTestAttributesFlakyState flakyState) {
     this.flakyState = flakyState;
   }
 
+  public FlakyTestAttributes history(List<FlakyTestHistory> history) {
+    this.history = history;
+    for (FlakyTestHistory item : history) {
+      this.unparsed |= item.unparsed;
+    }
+    return this;
+  }
+
+  public FlakyTestAttributes addHistoryItem(FlakyTestHistory historyItem) {
+    if (this.history == null) {
+      this.history = new ArrayList<>();
+    }
+    this.history.add(historyItem);
+    this.unparsed |= historyItem.unparsed;
+    return this;
+  }
+
+  /**
+   * Chronological history of status changes for this flaky test, ordered from most recent to
+   * oldest. Includes state transitions like new -&gt; quarantined -&gt; fixed, along with the
+   * associated commit SHA when available.
+   *
+   * @return history
+   */
+  @jakarta.annotation.Nullable
+  @JsonProperty(JSON_PROPERTY_HISTORY)
+  @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS)
+  public List<FlakyTestHistory> getHistory() {
+    return history;
+  }
+
+  public void setHistory(List<FlakyTestHistory> history) {
+    this.history = history;
+  }
+
   public FlakyTestAttributes lastFlakedBranch(String lastFlakedBranch) {
     this.lastFlakedBranch = lastFlakedBranch;
     return this;
@@ -611,6 +650,7 @@ public boolean equals(Object o) {
         && Objects.equals(this.firstFlakedTs, flakyTestAttributes.firstFlakedTs)
         && Objects.equals(this.flakyCategory, flakyTestAttributes.flakyCategory)
         && Objects.equals(this.flakyState, flakyTestAttributes.flakyState)
+        && Objects.equals(this.history, flakyTestAttributes.history)
         && Objects.equals(this.lastFlakedBranch, flakyTestAttributes.lastFlakedBranch)
         && Objects.equals(this.lastFlakedSha, flakyTestAttributes.lastFlakedSha)
         && Objects.equals(this.lastFlakedTs, flakyTestAttributes.lastFlakedTs)
@@ -635,6 +675,7 @@ public int hashCode() {
         firstFlakedTs,
         flakyCategory,
         flakyState,
+        history,
         lastFlakedBranch,
         lastFlakedSha,
         lastFlakedTs,
@@ -660,6 +701,7 @@ public String toString() {
     sb.append("    firstFlakedTs: ").append(toIndentedString(firstFlakedTs)).append("\n");
     sb.append("    flakyCategory: ").append(toIndentedString(flakyCategory)).append("\n");
     sb.append("    flakyState: ").append(toIndentedString(flakyState)).append("\n");
+    sb.append("    history: ").append(toIndentedString(history)).append("\n");
     sb.append("    lastFlakedBranch: ").append(toIndentedString(lastFlakedBranch)).append("\n");
     sb.append("    lastFlakedSha: ").append(toIndentedString(lastFlakedSha)).append("\n");
     sb.append("    lastFlakedTs: ").append(toIndentedString(lastFlakedTs)).append("\n");