messages.proto

// Copyright 2015 ThoughtWorks, Inc.

// This file is part of gauge-proto.

// gauge-proto is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.

// gauge-proto is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.

// You should have received a copy of the GNU General Public License
// along with gauge-proto.  If not, see <http://www.gnu.org/licenses/>.


// The comments are exported to Markdown, hence they may contain markdown syntax and cross-refs.
syntax = "proto3";
package gauge.messages;
option csharp_namespace = "Gauge.Messages";
option java_package = "com.thoughtworks.gauge";

import "spec.proto";

/// Default request. Tells the runner to shutdown.
message KillProcessRequest {
}

/// Sends to any request which needs a execution status as response
/// usually step execution, hooks etc will return this
message ExecutionStatusResponse {
  gauge.messages.ProtoExecutionResult executionResult = 1;
}

/// Sent at start of Suite Execution. Tells the runner to execute `before_suite` hook.
message ExecutionStartingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at end of Suite Execution. Tells the runner to execute `after_suite` hook.
message ExecutionEndingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at start of Spec Execution. Tells the runner to execute `before_spec` hook.
message SpecExecutionStartingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at end of Spec Execution. Tells the runner to execute `after_spec` hook.
message SpecExecutionEndingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at start of Scenario Execution. Tells the runner to execute `before_scenario` hook.
message ScenarioExecutionStartingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at end of Scenario Execution. Tells the runner to execute `after_scenario` hook.
message ScenarioExecutionEndingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at start of Step Execution. Tells the runner to execute `before_step` hook.
message StepExecutionStartingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Sent at end of Step Execution. Tells the runner to execute `after_step` hook.
message StepExecutionEndingRequest {
    ExecutionInfo currentExecutionInfo = 1;
}

/// Contains details of the execution. 
/// Depending on the context (Step, Scenario, Spec or Suite), the respective fields are set.
message ExecutionInfo {
    /// Holds the information of the current Spec. Valid in context of Spec execution.
    SpecInfo currentSpec = 1;
    /// Holds the information of the current Scenario. Valid in context of Scenario execution.
    ScenarioInfo currentScenario = 2;
    /// Holds the information of the current Step. Valid in context of Step execution.
    StepInfo currentStep = 3;
    /// Stacktrace of the execution. Valid only if there is an error in execution.
    string stacktrace = 4;
}

/// Contains details of the Spec execution.
message SpecInfo {
    /// Name of the current Spec being executed.
    string name = 1;
    /// Full File path containing the current Spec being executed.
    string fileName = 2;
    /// Flag to indicate if the current Spec execution failed.
    bool isFailed = 3;
    /// Tags relevant to the current Spec execution.
    repeated string  tags = 4;
}

/// Contains details of the Scenario execution.
message ScenarioInfo {
    /// Name of the current Scenario being executed.
    string name = 1;
    /// Flag to indicate if the current Scenario execution failed.
    bool isFailed = 2;
    /// Tags relevant to the current Scenario execution.
    repeated string  tags = 3;
}

/// Contains details of the Step execution.
message StepInfo {
    /// The current request to execute Step
    ExecuteStepRequest step = 1;
    /// Flag to indicate if the current Step execution failed.
    bool isFailed = 2;
    /// The current stack trace in case of failure
    string stackTrace = 3;
    /// The error message in case of failure
    string errorMessage = 4;
}

/// Request sent ot the runner to Execute a Step
message ExecuteStepRequest {
  /// Contains the actual text of the Step being executed. 
  /// This contains the parameters as defined in the Spec.
  string actualStepText = 1;
  /// Contains the parsed text of the Step being executed. 
  /// The paramters are replaced with placeholders.
  string parsedStepText = 2;
  /// Flag to indicate if the execution of the Scenario, containing the current Step, failed.
  bool scenarioFailing = 3;
  /// Collection of parameters applicable to the current Step.
  repeated gauge.messages.Parameter parameters = 4;
}

/// Request sent ot the runner to check if given Step is valid. 
/// The runner should check if there is an implementation defined for the given Step Text.
message StepValidateRequest {
  /// The text is used to lookup Step implementation
  string stepText = 1;
  /// The number of paramters in the Step
  int32 numberOfParameters = 2;
  ///This is use to generate step implementation template
  gauge.messages.ProtoStepValue stepValue = 3;
}

/// Response of StepValidateRequest.
/// The runner tells the caller if the Request was valid, 
/// i.e. an implementation exists for given Step text.
/// Returns an error message if it is an error response.
message StepValidateResponse {
    enum ErrorType {
        STEP_IMPLEMENTATION_NOT_FOUND = 0;
        DUPLICATE_STEP_IMPLEMENTATION = 1;
    }
    bool isValid = 1;
    string errorMessage = 2;
    ErrorType errorType = 3;
    string suggestion = 4;
}

/// Result of the Suite Execution.
message SuiteExecutionResult {
    gauge.messages.ProtoSuiteResult suiteResult = 1;
}

/// Requests Gauge to give all Step Names.
message StepNamesRequest {
}


/// Response to StepNamesRequest
message StepNamesResponse {
    /// Collection of strings corresponding to Step texts.
    repeated string steps = 1;
}

/// Request runner to initialize Scenario DataStore
/// Scenario Datastore is reset after every Scenario execution.
message ScenarioDataStoreInitRequest {
}

/// Request runner to initialize Spec DataStore
/// Spec Datastore is reset after every Spec execution.
message SpecDataStoreInitRequest {
}

/// Request runner to initialize Suite DataStore
/// Suite Datastore is reset after every Suite execution.
message SuiteDataStoreInitRequest {
}

/// Holds the new and old positions of a parameter.
/// Used when refactoring a Step.
message ParameterPosition {
  int32 oldPosition = 1;
  int32 newPosition = 2;
}

/// Tells the runner to refactor the specified Step.
message RefactorRequest {
  /// Old value, used to lookup Step to refactor
  gauge.messages.ProtoStepValue oldStepValue = 1;
  /// New value, the to-be value of Step being refactored.
  gauge.messages.ProtoStepValue newStepValue = 2;
  /// Holds parameter positions of all parameters. Contains old and new parameter positions.
  repeated ParameterPosition paramPositions = 3;
  /// If set to true, the refactored files should be saved to the file system before returning the response.
  bool saveChanges = 4;
}

/// Give all file changes to be made to file system
message FileChanges {
  string fileName = 1;
  string fileContent = 2 [deprecated=true];
  repeated TextDiff diffs = 3;
}

/// Response of a RefactorRequest
message RefactorResponse {
  /// Flag indicating the success of Refactor operation.
  bool success = 1;
  /// Error message, valid only if Refactor wasn't successful
  string error = 2;
  /// List of files that were affected because of the refactoring.
  repeated string filesChanged = 3;
  /// List of file changes to be made to successfully achieve refactoring.
  repeated FileChanges fileChanges = 4;
}

/// Request for details on a Single Step.
message StepNameRequest {
  /// Step text to lookup the Step. 
  /// This is the parsed step value, i.e. with placeholders for parameters.
  string stepValue = 1;
}

/// Response to StepNameRequest.
message StepNameResponse {
  /// Flag indicating if there is a match for the given Step Text.
  bool isStepPresent = 1;
  /// The Step name of the given step. 
  repeated string stepName = 2;
  /// Flag indicating if the given Step is an alias.
  bool hasAlias = 3;
  /// File name in which the step implementation exists
  string fileName = 4;
  /// Range of step
  gauge.messages.Span span = 5;
}

/// Response when a unsupported message request is sent.
message UnsupportedMessageResponse {
    string message = 1;
}

/// Request for caching a file.
/// Gauge sends this request when running in LSP mode,
/// so runner can cache file contents present on the client(an editor).
message CacheFileRequest {
    enum FileStatus {
        /// The file content was changed in the client
        CHANGED = 0;
        /// The file was closed in the client
        CLOSED = 1;
        /// The file was created on the client
        CREATED = 2;
        /// The file was deleted on the client
        DELETED = 3;
        /// The file is opened in the client
        OPENED = 4;
    }
    /// File content of the file to be cached
    string content = 1;
    /// File path of the file to be cached
    string filePath = 2;
    /// Specifies if the file is closed
    bool isClosed = 3;
    /// Specifies the status of the file
    FileStatus status = 4;
}

/// Request for find step positions
message StepPositionsRequest {
    /// Get step positions for file path
    string filePath = 1;
}

/// Response for find step positions
message StepPositionsResponse {
    /// Step position for each step implementation
    message StepPosition {
        /// Step Value
        string stepValue = 1;
        /// Range of step
        gauge.messages.Span span = 2;
    }
    /// Step Position
    repeated StepPosition stepPositions = 1;
    /// Error message
    string error = 2;
}

/// Request for getting Implementation file glob pattern
message ImplementationFileGlobPatternRequest {
}

/// Response for getting Implementation file glob pattern
message ImplementationFileGlobPatternResponse {
    /// List of implementation file glob patterns
    repeated string globPatterns = 1;
}

/// Request for getting Implementation file list
message ImplementationFileListRequest {
}

/// Response for getting Implementation file list
message ImplementationFileListResponse {
    /// List of implementation files
    repeated string implementationFilePaths = 1;
}

/// Request for injecting code snippet into implementation file
message StubImplementationCodeRequest {
    /// Path of the file where the new stub implementation will be added
    string implementationFilePath = 1;

    /// List of implementation codes to be appended to implementation file.
    repeated string codes = 2;
}

/// A Single Replace Diff Element to be applied
message TextDiff {
    /// Range of file to be replaced
    gauge.messages.Span span = 1;

    /// New content to replace the content in the span
    string content = 2;
}

/// Diffs to be applied to a file
message FileDiff {
    /// File Path where the new content needs to be put in
    string filePath = 1;

    /// The diffs which need to be applied to this file
    repeated TextDiff textDiffs = 2;
}

/// This is the message which gets transferred all the time
/// with proper message type set
/// One of the Request/Response fields will have value, depending on the MessageType set.
message Message {
  enum MessageType {
      ExecutionStarting = 0;
      SpecExecutionStarting = 1;
      SpecExecutionEnding = 2;
      ScenarioExecutionStarting = 3;
      ScenarioExecutionEnding = 4;
      StepExecutionStarting = 5;
      StepExecutionEnding = 6;
      ExecuteStep = 7;
      ExecutionEnding = 8;
      StepValidateRequest = 9;
      StepValidateResponse = 10;
      ExecutionStatusResponse = 11;
      StepNamesRequest = 12;
      StepNamesResponse = 13;
      KillProcessRequest = 14;
      SuiteExecutionResult = 15;
      ScenarioDataStoreInit = 16;
      SpecDataStoreInit = 17;
      SuiteDataStoreInit = 18;
      StepNameRequest = 19;
      StepNameResponse = 20;
      RefactorRequest = 21;
      RefactorResponse = 22;
      UnsupportedMessageResponse = 23;
      CacheFileRequest = 24;
      StepPositionsRequest = 25;
      StepPositionsResponse = 26;
      ImplementationFileListRequest = 27;
      ImplementationFileListResponse = 28;
      StubImplementationCodeRequest = 29;
      FileDiff = 30;
      ImplementationFileGlobPatternRequest = 31;
      ImplementationFileGlobPatternResponse = 32;
  }

  MessageType messageType = 1;

  /// A unique id to represent this message. A response to the message should copy over this value.
  /// This is used to synchronize messages & responses
  int64 messageId = 2;

  /// [ExecutionStartingRequest](#gauge.messages.ExecutionStartingRequest)
  ExecutionStartingRequest executionStartingRequest = 3;
  /// [SpecExecutionStartingRequest](#gauge.messages.SpecExecutionStartingRequest)
  SpecExecutionStartingRequest specExecutionStartingRequest = 4;
  /// [SpecExecutionEndingRequest](#gauge.messages.SpecExecutionEndingRequest)
  SpecExecutionEndingRequest specExecutionEndingRequest = 5;
  /// [ScenarioExecutionStartingRequest](#gauge.messages.ScenarioExecutionStartingRequest)
  ScenarioExecutionStartingRequest scenarioExecutionStartingRequest = 6;
  /// [ScenarioExecutionEndingRequest](#gauge.messages.ScenarioExecutionEndingRequest)
  ScenarioExecutionEndingRequest scenarioExecutionEndingRequest = 7;
  /// [StepExecutionStartingRequest](#gauge.messages.StepExecutionStartingRequest)
  StepExecutionStartingRequest stepExecutionStartingRequest = 8;
  /// [StepExecutionEndingRequest](#gauge.messages.StepExecutionEndingRequest)
  StepExecutionEndingRequest stepExecutionEndingRequest = 9;
  /// [ExecuteStepRequest](#gauge.messages.ExecuteStepRequest)
  ExecuteStepRequest executeStepRequest = 10;
  /// [ExecutionEndingRequest](#gauge.messages.ExecutionEndingRequest)
  ExecutionEndingRequest executionEndingRequest = 11;
  /// [StepValidateRequest](#gauge.messages.StepValidateRequest)
  StepValidateRequest stepValidateRequest = 12;
  /// [StepValidateResponse](#gauge.messages.StepValidateResponse)
  StepValidateResponse stepValidateResponse = 13;
  /// [ExecutionStatusResponse](#gauge.messages.ExecutionStatusResponse)
  ExecutionStatusResponse executionStatusResponse = 14;
  /// [StepNamesRequest](#gauge.messages.StepNamesRequest)
  StepNamesRequest stepNamesRequest = 15;
  /// [StepNamesResponse](#gauge.messages.StepNamesResponse)
  StepNamesResponse stepNamesResponse = 16;
  /// [SuiteExecutionResult ](#gauge.messages.SuiteExecutionResult )
  SuiteExecutionResult suiteExecutionResult = 17;
  /// [KillProcessRequest](#gauge.messages.KillProcessRequest)
  KillProcessRequest killProcessRequest = 18;
  /// [ScenarioDataStoreInitRequest](#gauge.messages.ScenarioDataStoreInitRequest)
  ScenarioDataStoreInitRequest scenarioDataStoreInitRequest = 19;
  /// [SpecDataStoreInitRequest](#gauge.messages.SpecDataStoreInitRequest)
  SpecDataStoreInitRequest specDataStoreInitRequest = 20;
  /// [SuiteDataStoreInitRequest](#gauge.messages.SuiteDataStoreInitRequest)
  SuiteDataStoreInitRequest suiteDataStoreInitRequest = 21;
  /// [StepNameRequest](#gauge.messages.StepNameRequest)
  StepNameRequest stepNameRequest= 22;
  /// [StepNameResponse](#gauge.messages.StepNameResponse)
  StepNameResponse stepNameResponse= 23;
  /// [RefactorRequest](#gauge.messages.RefactorRequest)
  RefactorRequest refactorRequest = 24;
  /// [RefactorResponse](#gauge.messages.RefactorResponse)
  RefactorResponse refactorResponse = 25;
  /// [UnsupportedMessageResponse](#gauge.messages.UnsupportedMessageResponse)
  UnsupportedMessageResponse unsupportedMessageResponse = 26;
  /// [CacheFileRequest](#gauge.messages.CacheFileRequest)
  CacheFileRequest cacheFileRequest = 27;
  /// [StepPositionsRequest](#gauge.messages.StepPositionsRequest)
  StepPositionsRequest stepPositionsRequest = 28;
  /// [StepPositionsResponse](#gauge.messages.StepPositionsResponse)
  StepPositionsResponse stepPositionsResponse = 29;
  /// [ImplementationFileListRequest](#gauge.messages.ImplementationFileListRequest)
  ImplementationFileListRequest implementationFileListRequest = 30;
  /// [ImplementationFileListResponse](#gauge.messages.ImplementationFileListResponse)
  ImplementationFileListResponse implementationFileListResponse = 31;
  /// [StubImplementationCodeRequest](#gauge.messages.StubImplementationCodeRequest)
  StubImplementationCodeRequest stubImplementationCodeRequest = 32;
  /// [FileDiff](#gauge.messages.FileDiff)
  FileDiff fileDiff = 33;
  /// [ImplementationFileGlobPatternRequest](#gauge.messages.ImplementationFileGlobPatternRequest)
  ImplementationFileGlobPatternRequest implementationFileGlobPatternRequest = 34;
  /// [ImplementationFileGlobPatternResponse](#gauge.messages.ImplementationFileGlobPatternResponse)
  ImplementationFileGlobPatternResponse implementationFileGlobPatternResponse = 35;
}