config.proto

syntax = "proto3";

// Protocol buffer for configuring testgrid.k8s.io

// Specifies the test name.
message TestNameConfig {
  // Specifies name elements to be selected from configuration values
  message NameElement {
    reserved 1, 3, 4;

    // Configuration value to use.
    // Valid choice are:
    // 'Tests name': The name of a test case
    // 'Commit': The commit number of the build
    // 'Context', 'Thread': The info extracted from each junit files:
    //    - junit_core-os_01.xml -> Context: core-os, Thread: 01
    //    - junit_runner.xml -> Context: runner
    //    - junit_01.xml -> Thread: 01
    // or any metadata key from finished.json, which is copied from your test suite.
    //
    // A valid sample TestNameConfig looks like:
    // test_name_config:
    //   name_elements:
    //   - target_config: Tests name
    //   - target_config: Context
    //   name_format: '%s [%s]'
    string target_config = 2;
  }

  // The name elements specifying the target test name for this tab.
  repeated NameElement name_elements = 1;

  // Specifies a printf-style format string for name elements. The format
  // string should have as many conversions as there are name_elements.
  // For example, two name_elements could be used with name_format="%s: %s".
  string name_format = 2;
}

// A single notification.
message Notification {
  // Required: Text summary of the issue or notice.
  string summary = 1;
  // Optional: Link to further information, such as a bug, email, document, etc.
  string context_link = 2;
}

// Specifies a group of tests to gather.
message TestGroup {
  reserved 5, 7, 8, 10, 13, 16 to 23, 28 to 37;

  // Name of this TestGroup, for mapping dashboard tabs to tests.
  string name = 1;

  // Path to the test result stored in gcs
  string gcs_prefix = 2;

  // Number of days of test results to gather and serve.
  int32 days_of_results = 3;

  // Whether to ignore pending (currently running) test results.
  bool ignore_pending = 4;

  enum TestsName {
    TESTS_NAME_MIN = 0;
    TESTS_NAME_IGNORE = 1;
    TESTS_NAME_REPLACE = 2;
    TESTS_NAME_APPEND = 3;
  }

  // What to do with the 'Tests name' configuration value. It can replace the
  // name of the test, be appended to the name of the test, or ignored. If it is
  // ignored, then the name of the tests will be the build target.
  TestsName tests_name_policy = 6;

  // Custom column headers for defining extra column-heading rows from values in
  // the test result.
  message ColumnHeader {
    reserved 1, 2;
    string configuration_value = 3;
  }
  repeated ColumnHeader column_header = 9;

  // Time in hours before an alert will be added to a test results table if the
  // run date of the latest results are older than this time.  If zero, no
  // alerts are raised.
  int32 alert_stale_results_hours = 11;

  // The number of consecutive test result failures to see before alerting of
  // a consistent failure. If zero, no alerts are raised.
  int32 num_failures_to_alert = 12;

  // Default code search path for searching regressions. Overridden by
  // code_search_path in DashboardTab.
  string code_search_path = 14;

  // The number of columns to consider "recent" for a variety of purposes.
  int32 num_columns_recent = 15;

  // deprecated - always set to true
  bool use_kubernetes_client = 24;

  // deprecated - always set to true
  bool is_external = 25;

  // Specifies the test name for a test.
  TestNameConfig test_name_config = 26;

  // A list of notifications attached to this test group.
  // This is displayed on any dashboard tab backed by this test group.
  repeated Notification notifications = 27;

  // The number of consecutive test passes to close the alert.
  int32 num_passes_to_disable_alert = 38;

  // Numeric property metric value to be used for short text. If this property
  // is present, it will override all the other short text values.
  string short_text_metric = 43;
}


// Specifies a dashboard.
message Dashboard {
  // A list of the tabs on the dashboard.
  repeated DashboardTab dashboard_tab = 1;

  // A name for the Dashboard.
  string name = 2;

  // A list of notifications attached to this dashboard.
  // This is displayed on any dashboard tab in this dashboard.
  repeated Notification notifications = 3;

  reserved 4;  // Deprecated show_summary_first bool, unused

  // Control which tab is displayed when first opening a dashboard.
  // Defaults to Summary
  string default_tab = 5;
}

message LinkTemplate {
  // The URL template.
  string url = 1;
  // The options templates.
  repeated LinkOptionsTemplate options = 2;
}

// A simple key/value pair for link options.
message LinkOptionsTemplate {
  // The key for the option. This is not expanded.
  string key = 1;

  // The value for the option. This is expanded the same as the LinkTemplate.
  string value = 2;
}

// A single tab on a dashboard.
message DashboardTab {
  reserved 14;

  // The name of the dashboard tab to display in the client.
  string name = 1;

  // The name of the TestGroup specifying the test results for this tab.
  string test_group_name = 2;

  // Default bug component for manually filing bugs from the dashboard
  int32 bug_component = 3;

  // Default code search path for searching regressions. This value overrides
  // the default in the TestGroup config so that dashboards may be customized
  // separately.
  string code_search_path = 4;

  // See TestGroup.num_columns_recent. This value overrides the default in the
  // TestGroup config so that dashboards may be customized separately.
  int32 num_columns_recent = 5;

  // Base options to always include, for example:
  // width=20&include-filter-by-regex=level_tests
  // This is taken from the #fragment part of the testgrid url.
  // Best way to create these is to setup the options on testgrid and then
  // copy the #fragment part.
  string base_options = 6;

  // The URL template to visit after clicking on a cell.
  LinkTemplate open_test_template = 7;

  // The URL template to visit when filing a bug.
  LinkTemplate file_bug_template = 8;

  // The URL template to visit when attaching a bug
  LinkTemplate attach_bug_template = 9;

  // Text to show in the about menu as a link to another view of the results.
  string results_text = 10;

  // The URL template to visit after clicking.
  LinkTemplate results_url_template = 11;

  // The URL template to visit when searching for changelists.
  LinkTemplate code_search_url_template = 12;

  // A description paragraph to be displayed.
  string description = 13;

  // Configuration options for dashboard tab alerts.
  DashboardTabAlertOptions alert_options = 15;
}

// Configuration options for dashboard tab alerts.
message DashboardTabAlertOptions {
  // Time in hours before an alert will be added to a test results table if the
  // run date of the latest results are older than this time.  If zero, no
  // alerts are raised.
  int32 alert_stale_results_hours = 1;

  // The number of consecutive test result failures to see before alerting of
  // a consistent failure. If zero, no alerts are raised.
  int32 num_failures_to_alert = 2;

  // The comma-separated addresses to send mail.
  string alert_mail_to_addresses = 3;
}

// Specifies a dashboard group.
message DashboardGroup {
  // The name for the dashboard group.
  string name = 1;

  // A list of names specifying dashboards to show links to in a separate tabbed
  // bar at the top of the page for each of the given dashboards.
  repeated string dashboard_names = 2;
}

// A service configuration consisting of multiple test groups and dashboards.
message Configuration {
  // A list of groups of tests to gather.
  repeated TestGroup test_groups = 1;

  // A list of all of the dashboards for a server.
  repeated Dashboard dashboards = 2;

  // A list of all the dashboard groups for a server.
  repeated DashboardGroup dashboard_groups = 3;
}

message DefaultConfiguration {
  // A default testgroup with default initialization data
  TestGroup default_test_group = 1;

  // A default dashboard tab with default initialization data
  DashboardTab default_dashboard_tab = 2;
}