go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/analysis/proto/v1/test_history.proto

// Copyright 2022 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package luci.analysis.v1;

import "google/api/field_behavior.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";
import "go.chromium.org/luci/analysis/proto/v1/common.proto";
import "go.chromium.org/luci/analysis/proto/v1/predicate.proto";
import "go.chromium.org/luci/analysis/proto/v1/test_verdict.proto";

option go_package = "go.chromium.org/luci/analysis/proto/v1;analysispb";

// Provide methods to read test histories.
service TestHistory {
  // Retrieves test verdicts for a given test ID in a given project and in a
  // given range of time.
  // Accepts a test variant predicate to filter the verdicts.
  rpc Query(QueryTestHistoryRequest) returns (
    QueryTestHistoryResponse) {};

  // Retrieves a summary of test verdicts for a given test ID in a given project
  // and in a given range of times.
  // Accepts a test variant predicate to filter the verdicts.
  rpc QueryStats(QueryTestHistoryStatsRequest) returns (
    QueryTestHistoryStatsResponse) {};

  // Retrieves variants for a given test ID in a given project that were
  // recorded in the past 90 days.
  rpc QueryVariants(QueryVariantsRequest) returns (QueryVariantsResponse) {};

  // Finds test IDs that contain the given substring in a given project that
  // were recorded in the past 90 days.
  rpc QueryTests(QueryTestsRequest) returns (QueryTestsResponse) {};
}

// A request message for `TestHistory.Query` RPC.
message QueryTestHistoryRequest {
  // Required. The LUCI Project of the test results.
  // I.e. For a result to be part of the history, it needs to be contained
  // transitively by an invocation in this project.
  string project = 1
    [(google.api.field_behavior) = REQUIRED];

  // Required. The test ID to query the history from.
  string test_id = 2
    [(google.api.field_behavior) = REQUIRED];

  // Required. A test verdict in the response must satisfy this predicate.
  luci.analysis.v1.TestVerdictPredicate predicate = 3
    [(google.api.field_behavior) = REQUIRED];

  // The maximum number of entries to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 variants will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to the next call MUST
  // match the call that provided the page token.
  string page_token = 5;
}

// A response message for `TestHistory.Query` RPC.
message QueryTestHistoryResponse {
  // The list of test verdicts.
  // Test verdicts will be ordered by `partition_time` DESC, `variant_hash` ASC,
  // `invocation_id` ASC.
  repeated luci.analysis.v1.TestVerdict verdicts = 1;

  // This field will be set if there are more results to return.
  // To get the next page of data, send the same request again, but include this
  // token.
  string next_page_token = 2;
}

// A request message for `TestHistory.QueryStats` RPC.
message QueryTestHistoryStatsRequest {
  // Required. The LUCI Project of the test results.
  // I.e. For a result to be part of the history, it needs to be contained
  // transitively by an invocation in this project.
  string project = 1
    [(google.api.field_behavior) = REQUIRED];

  // Required. The test ID to query the history from.
  string test_id = 2
    [(google.api.field_behavior) = REQUIRED];

  // Required. A test verdict in the response must satisfy this predicate.
  luci.analysis.v1.TestVerdictPredicate predicate = 3
    [(google.api.field_behavior) = REQUIRED];

  // The maximum number of entries to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 variants will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to the next call
  // MUST match the call that provided the page token.
  string page_token = 5;
}

// A response message for `TestHistory.QueryStats` RPC.
message QueryTestHistoryStatsResponse {
  message Group {
    // The start time of this group.
    // Test verdicts that are paritioned in the 24 hours following this
    // timestamp are captured in this group.
    google.protobuf.Timestamp partition_time = 1;

    // The hash of the variant.
    string variant_hash = 2;

    // The number of unexpected test verdicts in the group.
    int32 unexpected_count = 3;

    // The number of unexpectedly skipped test verdicts in the group.
    int32 unexpectedly_skipped_count = 4;

    // The number of flaky test verdicts in the group.
    int32 flaky_count = 5;

    // The number of exonerated test verdicts in the group.
    int32 exonerated_count = 6;

    // The number of expected test verdicts in the group.
    int32 expected_count = 7;

    // The average duration of passing test results in the group.
    google.protobuf.Duration passed_avg_duration = 8;
  }

  // The list of test verdict groups. Test verdicts will be grouped and ordered
  // by `partition_date` DESC, `variant_hash` ASC.
  repeated Group groups = 1;

  // This field will be set if there are more results to return.
  // To get the next page of data, send the same request again, but include this
  // token.
  string next_page_token = 2;
}

// A request message for the `QueryVariants` RPC.
message QueryVariantsRequest {
  // Required. The LUCI project to query the variants from.
  string project = 1
    [(google.api.field_behavior) = REQUIRED];

  // Required. The test ID to query the variants from.
  string test_id = 2
    [(google.api.field_behavior) = REQUIRED];

  // Optional. The project-scoped realm to query the variants from.
  // This is the realm without the "<project>:" prefix.
  //
  // When specified, only the test variants found in the matching realm will be
  // returned.
  string sub_realm = 3;

  // Optional. When specified, only variant matches this predicate will be
  // returned.
  VariantPredicate variant_predicate = 6;

  // The maximum number of variants to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 variants will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryVariants` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryVariants` MUST
  // match the call that provided the page token.
  string page_token = 5;
}

// A response message for the `QueryVariants` RPC.
message QueryVariantsResponse {
  // Contains the variant definition and its hash.
  message VariantInfo {
    // The hash of the variant.
    string variant_hash = 1;

    // The definition of the variant.
    luci.analysis.v1.Variant variant = 2;
  }

  // A list of variants. Ordered by variant hash.
  repeated VariantInfo variants = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}

// A request message for the `QueryTests` RPC.
message QueryTestsRequest {
  // Required. The LUCI project to query the tests from.
  string project = 1
    [(google.api.field_behavior) = REQUIRED];

  // Required. Only tests that contain the substring will be returned.
  string test_id_substring = 2
    [(google.api.field_behavior) = REQUIRED];

  // Optional. The project-scoped realm to query the variants from.
  // This is the realm without the "<project>:" prefix.
  //
  // When specified, only the tests found in the matching realm will be
  // returned.
  string sub_realm = 3;

  // The maximum number of test IDs to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test IDs will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryTests` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryTests` MUST
  // match the call that provided the page token.
  string page_token = 5;
}

// A response message for the `QueryTests` RPC.
message QueryTestsResponse {
  // A list of test Ids. Ordered alphabetically.
  repeated string test_ids = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}