Update SearchFlakyTests endpoint documentation (#3868)

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

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

.generator/schemas/v2/openapi.yaml

@@ -26664,9 +26664,18 @@ components:
             Includes state transitions like new -> quarantined -> fixed, along with the associated commit SHA when available.
           example:
             - commit_sha: abc123def456
+              policy_id: ftm_policy.quarantine.failure_rate
+              policy_meta:
+                config:
+                  failure_rate: 0.1
+                  required_runs: 100
+                failure_rate: 0.25
+                total_runs: 200
               status: quarantined
               timestamp: 1704067200000
             - commit_sha: ""
+              policy_id: unknown
+              policy_meta:
               status: new
               timestamp: 1703980800000
           items:
@@ -26736,6 +26745,11 @@ components:
           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
+        policy_id:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyId"
+        policy_meta:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyMeta"
+          nullable: true
         status:
           description: The test status at this point in history.
           example: quarantined
@@ -26750,6 +26764,131 @@ components:
         - commit_sha
         - timestamp
       type: object
+    FlakyTestHistoryPolicyId:
+      description: The policy that triggered this status change.
+      enum:
+        - ftm_policy.manual
+        - ftm_policy.fixed
+        - ftm_policy.disable.failure_rate
+        - ftm_policy.disable.branch_flake
+        - ftm_policy.disable.days_active
+        - ftm_policy.quarantine.failure_rate
+        - ftm_policy.quarantine.branch_flake
+        - ftm_policy.quarantine.days_active
+        - unknown
+      example: ftm_policy.quarantine.failure_rate
+      nullable: false
+      type: string
+      x-enum-varnames:
+        - MANUAL
+        - FIXED
+        - DISABLE_FAILURE_RATE
+        - DISABLE_BRANCH_FLAKE
+        - DISABLE_DAYS_ACTIVE
+        - QUARANTINE_FAILURE_RATE
+        - QUARANTINE_BRANCH_FLAKE
+        - QUARANTINE_DAYS_ACTIVE
+        - UNKNOWN
+    FlakyTestHistoryPolicyMeta:
+      description: Metadata about the policy that triggered this status change.
+      properties:
+        branches:
+          description: Branches where the test was flaky at the time of the status change.
+          example: ["main", "develop"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        config:
+          $ref: "#/components/schemas/FlakyTestHistoryPolicyMetaConfig"
+          nullable: true
+        days_active:
+          description: The number of days the test has been active at the time of the status change.
+          example: 15
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        days_without_flake:
+          description: The number of days since the test last exhibited flakiness.
+          example: 30
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        failure_rate:
+          description: The failure rate of the test at the time of the status change.
+          example: 0.25
+          format: double
+          maximum: 1
+          minimum: 0
+          nullable: true
+          type: number
+        state:
+          description: The previous state of the test.
+          example: quarantined
+          nullable: true
+          type: string
+        total_runs:
+          description: The total number of test runs at the time of the status change.
+          example: 200
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+      type: object
+    FlakyTestHistoryPolicyMetaConfig:
+      description: Configuration parameters of the policy that triggered this status change.
+      properties:
+        branches:
+          description: The branches considered by the policy.
+          example: ["main"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        days_active:
+          description: The number of days a test must have been active for the policy to trigger.
+          example: 30
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        failure_rate:
+          description: The failure rate threshold for the policy to trigger.
+          example: 0.7
+          format: double
+          maximum: 1
+          minimum: 0
+          nullable: true
+          type: number
+        forget_branches:
+          description: Branches excluded from the policy evaluation.
+          example: ["release"]
+          items:
+            type: string
+          nullable: true
+          type: array
+        required_runs:
+          description: The minimum number of test runs required for the policy to trigger.
+          example: 100
+          format: int32
+          maximum: 2147483647
+          nullable: true
+          type: integer
+        state:
+          description: The target state the policy transitions the test from.
+          example: quarantined
+          nullable: true
+          type: string
+        test_services:
+          description: Test services excluded from the policy evaluation.
+          example: ["my-service"]
+          items:
+            type: string
+          nullable: true
+          type: array
+      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 CI Visibility.
       properties:
@@ -26829,6 +26968,14 @@ components:
     FlakyTestsSearchFilter:
       description: Search filter settings.
       properties:
+        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
         query:
           default: "*"
           description: |-
@@ -26874,14 +27021,6 @@ 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:

examples/v2/test-optimization/SearchFlakyTests.ts

@@ -13,9 +13,9 @@ const params: v2.TestOptimizationApiSearchFlakyTestsRequest = {
     data: {
       attributes: {
         filter: {
+          includeHistory: true,
           query: `flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"`,
         },
-        includeHistory: true,
         page: {
           cursor:
             "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==",

examples/v2/test-optimization/SearchFlakyTests_1224086727.ts

@@ -13,9 +13,9 @@ const params: v2.TestOptimizationApiSearchFlakyTestsRequest = {
     data: {
       attributes: {
         filter: {
+          includeHistory: true,
           query: `flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"`,
         },
-        includeHistory: true,
         page: {
           cursor:
             "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==",

examples/v2/test-optimization/SearchFlakyTests_209064879.ts

@@ -14,12 +14,12 @@ const params: v2.TestOptimizationApiSearchFlakyTestsRequest = {
       attributes: {
         filter: {
           query: `flaky_test_state:active @git.repository.id_v2:"github.com/datadog/shopist"`,
+          includeHistory: true,
         },
         page: {
           limit: 10,
         },
         sort: "fqn",
-        includeHistory: true,
       },
       type: "search_flaky_tests_request",
     },

features/v2/test_optimization.feature

@@ -117,7 +117,7 @@ Feature: Test Optimization
   Scenario: Search flaky tests returns "Bad Request" response
     Given operation "SearchFlakyTests" enabled
     And new "SearchFlakyTests" request
-    And body with value {"data": {"attributes": {"filter": {"query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "include_history": true, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
+    And body with value {"data": {"attributes": {"filter": {"include_history": true, "query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
     When the request is sent
     Then the response status is 400 Bad Request
 
@@ -133,7 +133,7 @@ Feature: Test Optimization
   Scenario: Search flaky tests returns "OK" response
     Given operation "SearchFlakyTests" enabled
     And new "SearchFlakyTests" request
-    And body with value {"data": {"attributes": {"filter": {"query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "include_history": true, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
+    And body with value {"data": {"attributes": {"filter": {"include_history": true, "query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
     When the request is sent
     Then the response status is 200 OK
 
@@ -149,19 +149,21 @@ Feature: Test Optimization
   Scenario: Search flaky tests returns "OK" response with history
     Given operation "SearchFlakyTests" enabled
     And new "SearchFlakyTests" request
-    And body with value {"data": {"attributes": {"filter": {"query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "page": {"limit": 10}, "sort": "fqn", "include_history": true}, "type": "search_flaky_tests_request"}}
+    And body with value {"data": {"attributes": {"filter": {"query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\"", "include_history": true}, "page": {"limit": 10}, "sort": "fqn"}, "type": "search_flaky_tests_request"}}
     When the request is sent
     Then the response status is 200 OK
     And the response "data[0].attributes" has field "history"
     And the response "data[0].attributes.history[0]" has field "status"
     And the response "data[0].attributes.history[0]" has field "commit_sha"
     And the response "data[0].attributes.history[0]" has field "timestamp"
+    And the response "data[0].attributes.history[0]" has field "policy_id"
+    And the response "data[0].attributes.history[0]" has field "policy_meta"
 
   @generated @skip @team:DataDog/ci-app-backend @with-pagination
   Scenario: Search flaky tests returns "OK" response with pagination
     Given operation "SearchFlakyTests" enabled
     And new "SearchFlakyTests" request
-    And body with value {"data": {"attributes": {"filter": {"query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "include_history": true, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
+    And body with value {"data": {"attributes": {"filter": {"include_history": true, "query": "flaky_test_state:active @git.repository.id_v2:\"github.com/datadog/shopist\""}, "page": {"cursor": "eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==", "limit": 25}, "sort": "failure_rate"}, "type": "search_flaky_tests_request"}}
     When the request with pagination is sent
     Then the response status is 200 OK
 

packages/datadog-api-client-v2/index.ts

@@ -2932,6 +2932,9 @@ export { FlakyTest } from "./models/FlakyTest";
 export { FlakyTestAttributes } from "./models/FlakyTestAttributes";
 export { FlakyTestAttributesFlakyState } from "./models/FlakyTestAttributesFlakyState";
 export { FlakyTestHistory } from "./models/FlakyTestHistory";
+export { FlakyTestHistoryPolicyId } from "./models/FlakyTestHistoryPolicyId";
+export { FlakyTestHistoryPolicyMeta } from "./models/FlakyTestHistoryPolicyMeta";
+export { FlakyTestHistoryPolicyMetaConfig } from "./models/FlakyTestHistoryPolicyMetaConfig";
 export { FlakyTestPipelineStats } from "./models/FlakyTestPipelineStats";
 export { FlakyTestRunMetadata } from "./models/FlakyTestRunMetadata";
 export { FlakyTestsPagination } from "./models/FlakyTestsPagination";

packages/datadog-api-client-v2/models/FlakyTestHistory.ts

@@ -3,6 +3,8 @@
  * This product includes software developed at Datadog (https://www.datadoghq.com/).
  * Copyright 2020-Present Datadog, Inc.
  */
+import { FlakyTestHistoryPolicyId } from "./FlakyTestHistoryPolicyId";
+import { FlakyTestHistoryPolicyMeta } from "./FlakyTestHistoryPolicyMeta";
 
 import { AttributeTypeMap } from "../../datadog-api-client-common/util";
 
@@ -14,6 +16,14 @@ export class FlakyTestHistory {
    * The commit SHA associated with this status change. Will be an empty string if the commit SHA is not available.
    */
   "commitSha": string;
+  /**
+   * The policy that triggered this status change.
+   */
+  "policyId"?: FlakyTestHistoryPolicyId;
+  /**
+   * Metadata about the policy that triggered this status change.
+   */
+  "policyMeta"?: FlakyTestHistoryPolicyMeta;
   /**
    * The test status at this point in history.
    */
@@ -44,6 +54,14 @@ export class FlakyTestHistory {
       type: "string",
       required: true,
     },
+    policyId: {
+      baseName: "policy_id",
+      type: "FlakyTestHistoryPolicyId",
+    },
+    policyMeta: {
+      baseName: "policy_meta",
+      type: "FlakyTestHistoryPolicyMeta",
+    },
     status: {
       baseName: "status",
       type: "string",

packages/datadog-api-client-v2/models/FlakyTestHistoryPolicyId.ts

@@ -0,0 +1,32 @@
+/**
+ * Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+ * This product includes software developed at Datadog (https://www.datadoghq.com/).
+ * Copyright 2020-Present Datadog, Inc.
+ */
+
+import { UnparsedObject } from "../../datadog-api-client-common/util";
+
+/**
+ * The policy that triggered this status change.
+ */
+
+export type FlakyTestHistoryPolicyId =
+  | typeof MANUAL
+  | typeof FIXED
+  | typeof DISABLE_FAILURE_RATE
+  | typeof DISABLE_BRANCH_FLAKE
+  | typeof DISABLE_DAYS_ACTIVE
+  | typeof QUARANTINE_FAILURE_RATE
+  | typeof QUARANTINE_BRANCH_FLAKE
+  | typeof QUARANTINE_DAYS_ACTIVE
+  | typeof UNKNOWN
+  | UnparsedObject;
+export const MANUAL = "ftm_policy.manual";
+export const FIXED = "ftm_policy.fixed";
+export const DISABLE_FAILURE_RATE = "ftm_policy.disable.failure_rate";
+export const DISABLE_BRANCH_FLAKE = "ftm_policy.disable.branch_flake";
+export const DISABLE_DAYS_ACTIVE = "ftm_policy.disable.days_active";
+export const QUARANTINE_FAILURE_RATE = "ftm_policy.quarantine.failure_rate";
+export const QUARANTINE_BRANCH_FLAKE = "ftm_policy.quarantine.branch_flake";
+export const QUARANTINE_DAYS_ACTIVE = "ftm_policy.quarantine.days_active";
+export const UNKNOWN = "unknown";