gui_automation_client.h

Go to the documentation of this file.

// gui_automation_client.h
// gRPC client for automating YAZE GUI through ImGuiTestHarness service
 
#ifndef YAZE_CLI_SERVICE_GUI_AUTOMATION_CLIENT_H
#define YAZE_CLI_SERVICE_GUI_AUTOMATION_CLIENT_H
 
#include <chrono>
#include <cstdint>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
#include "absl/status/status.h"
#include "absl/status/statusor.h"
#include "absl/time/time.h"
 
#ifdef YAZE_WITH_GRPC
#include "util/grpc_win_compat.h"
 
#include <grpcpp/grpcpp.h>
 
#include "protos/imgui_test_harness.grpc.pb.h"
#endif
 
namespace yaze {
namespace cli {
 
enum class ClickType { kLeft, kRight, kMiddle, kDouble };
 
struct AutomationResult {
  bool success;
  std::string message;
  std::chrono::milliseconds execution_time;
  std::string actual_value;    // For assertions
  std::string expected_value;  // For assertions
  std::string test_id;         // Test execution identifier (for introspection)
  std::string resolved_widget_key;  // Selector-v2: resolved widget key
  std::string resolved_path;        // Selector-v2: resolved legacy path
};
 
enum class TestRunStatus {
  kUnknown,
  kQueued,
  kRunning,
  kPassed,
  kFailed,
  kTimeout
};
 
struct TestStatusDetails {
  std::string test_id;
  TestRunStatus status = TestRunStatus::kUnknown;
  std::optional<absl::Time> queued_at;
  std::optional<absl::Time> started_at;
  std::optional<absl::Time> completed_at;
  int execution_time_ms = 0;
  std::string error_message;
  std::vector<std::string> assertion_failures;
};
 
struct HarnessTestSummary {
  std::string test_id;
  std::string name;
  std::string category;
  std::optional<absl::Time> last_run_at;
  int total_runs = 0;
  int pass_count = 0;
  int fail_count = 0;
  int average_duration_ms = 0;
};
 
struct ListTestsResult {
  std::vector<HarnessTestSummary> tests;
  std::string next_page_token;
  int total_count = 0;
};
 
struct AssertionOutcome {
  std::string description;
  bool passed = false;
  std::string expected_value;
  std::string actual_value;
  std::string error_message;
};
 
struct TestResultDetails {
  std::string test_id;
  bool success = false;
  std::string test_name;
  std::string category;
  std::optional<absl::Time> executed_at;
  int duration_ms = 0;
  std::vector<AssertionOutcome> assertions;
  std::vector<std::string> logs;
  std::map<std::string, int> metrics;
  std::string screenshot_path;
  int64_t screenshot_size_bytes = 0;
  std::string failure_context;
  std::string widget_state;
};
 
struct ReplayTestResult {
  bool success = false;
  std::string message;
  std::string replay_session_id;
  int steps_executed = 0;
  std::vector<AssertionOutcome> assertions;
  std::vector<std::string> logs;
};
 
struct StartRecordingResult {
  bool success = false;
  std::string message;
  std::string recording_id;
  std::optional<absl::Time> started_at;
};
 
struct StopRecordingResult {
  bool success = false;
  std::string message;
  std::string output_path;
  int step_count = 0;
  std::chrono::milliseconds duration{0};
};
 
enum class WidgetTypeFilter {
  kUnspecified,
  kAll,
  kButton,
  kInput,
  kMenu,
  kTab,
  kCheckbox,
  kSlider,
  kCanvas,
  kSelectable,
  kOther,
};
 
struct WidgetBoundingBox {
  float min_x = 0.0f;
  float min_y = 0.0f;
  float max_x = 0.0f;
  float max_y = 0.0f;
};
 
struct WidgetDescriptor {
  std::string path;
  std::string widget_key;
  std::string legacy_path;
  std::string alias_of;
  std::string label;
  std::string type;
  std::string description;
  std::string suggested_action;
  bool visible = true;
  bool enabled = true;
  WidgetBoundingBox bounds;
  uint32_t widget_id = 0;
  bool has_bounds = false;
  int64_t last_seen_frame = -1;
  std::optional<absl::Time> last_seen_at;
  bool stale = false;
};
 
struct DiscoveredWindowInfo {
  std::string name;
  bool visible = true;
  std::vector<WidgetDescriptor> widgets;
};
 
struct DiscoverWidgetsQuery {
  std::string window_filter;
  WidgetTypeFilter type_filter = WidgetTypeFilter::kUnspecified;
  std::string path_prefix;
  bool include_invisible = false;
  bool include_disabled = false;
};
 
struct DiscoverWidgetsResult {
  std::vector<DiscoveredWindowInfo> windows;
  int total_widgets = 0;
  std::optional<absl::Time> generated_at;
};
 
struct UiSyncStateSnapshot {
  int64_t frame_id = 0;
  int pending_editor_actions = 0;
  int pending_layout_actions = 0;
  bool layout_rebuild_pending = false;
  int pending_harness_tests = 0;
  int queued_harness_tests = 0;
  int running_harness_tests = 0;
  std::optional<absl::Time> sampled_at;
  bool idle = false;
};
 
struct WaitForIdleResult {
  bool success = false;
  std::string message;
  std::chrono::milliseconds elapsed{0};
  int64_t last_frame_id = 0;
  int stable_frames_observed = 0;
  UiSyncStateSnapshot state;
  std::string timeout_reason;
};
 
class GuiAutomationClient {
 public:
  explicit GuiAutomationClient(const std::string& server_address);
 
  absl::Status Connect();
 
  absl::StatusOr<AutomationResult> Ping(const std::string& message = "ping");
 
  absl::StatusOr<AutomationResult> Click(const std::string& target,
                                         ClickType type = ClickType::kLeft,
                                         const std::string& widget_key = "");
 
  absl::StatusOr<AutomationResult> Type(const std::string& target,
                                        const std::string& text,
                                        bool clear_first = false,
                                        const std::string& widget_key = "");
 
  absl::StatusOr<AutomationResult> Wait(const std::string& condition,
                                        int timeout_ms = 5000,
                                        int poll_interval_ms = 100,
                                        const std::string& widget_key = "");
 
  absl::StatusOr<AutomationResult> Assert(const std::string& condition,
                                          const std::string& widget_key = "");
 
  absl::StatusOr<UiSyncStateSnapshot> FlushUiActions(int timeout_ms = 2000);
 
  absl::StatusOr<WaitForIdleResult> WaitForIdle(int timeout_ms = 5000,
                                                int stable_frames = 2,
                                                bool flush_first = true,
                                                int poll_interval_ms = 25);
 
  absl::StatusOr<UiSyncStateSnapshot> GetUiSyncState();
 
  absl::StatusOr<AutomationResult> Screenshot(
      const std::string& region = "full", const std::string& format = "PNG");
 
  absl::StatusOr<TestStatusDetails> GetTestStatus(const std::string& test_id);
 
  absl::StatusOr<ListTestsResult> ListTests(
      const std::string& category_filter = "", int page_size = 100,
      const std::string& page_token = "");
 
  absl::StatusOr<TestResultDetails> GetTestResults(const std::string& test_id,
                                                   bool include_logs = false);
 
  absl::StatusOr<DiscoverWidgetsResult> DiscoverWidgets(
      const DiscoverWidgetsQuery& query);
 
  absl::StatusOr<ReplayTestResult> ReplayTest(
      const std::string& script_path, bool ci_mode,
      const std::map<std::string, std::string>& parameter_overrides = {});
 
  absl::StatusOr<StartRecordingResult> StartRecording(
      const std::string& output_path, const std::string& session_name,
      const std::string& description);
 
  absl::StatusOr<StopRecordingResult> StopRecording(
      const std::string& recording_id, bool discard = false);
 
  bool IsConnected() const { return connected_; }
 
  const std::string& ServerAddress() const { return server_address_; }
 
 private:
#ifdef YAZE_WITH_GRPC
  std::unique_ptr<yaze::test::ImGuiTestHarness::Stub> stub_;
#endif
  std::string server_address_;
  bool connected_ = false;
};
 
}  // namespace cli
}  // namespace yaze
 
#endif  // YAZE_CLI_SERVICE_GUI_AUTOMATION_CLIENT_H