appom 1.4.0 → 2.0.0

data/lib/appom/element_state.rb

@@ -0,0 +1,458 @@
+# frozen_string_literal: true
+
+# Element state tracking for Appom automation framework
+# Tracks element state changes and provides monitoring capabilities
+module Appom::ElementState
+  # Tracks element states and changes over time
+  class Tracker
+    include Appom::Logging
+
+    attr_reader :tracked_elements, :state_history
+
+    def initialize
+      @tracked_elements = {}
+      @state_history = []
+      @observers = []
+      @tracking_enabled = true
+    end
+
+    # Start tracking an element
+    def track_element(element, name: nil, context: {})
+      element_id = generate_element_id(element, name)
+
+      state = capture_element_state(element)
+
+      @tracked_elements[element_id] = {
+        element: element,
+        name: name || element_id,
+        context: context,
+        first_seen: Time.now,
+        last_updated: Time.now,
+        current_state: state,
+        previous_states: [],
+        change_count: 0,
+      }
+
+      log_debug("Started tracking element: #{name || element_id}")
+      notify_observers(:element_tracked, element_id, state)
+
+      element_id
+    end
+
+    # Update element state and detect changes
+    def update_element_state(element_id)
+      return unless @tracking_enabled
+
+      tracked = @tracked_elements[element_id]
+      return unless tracked
+
+      begin
+        new_state = capture_element_state(tracked[:element])
+        old_state = tracked[:current_state]
+
+        if state_changed?(old_state, new_state)
+          # Store previous state
+          tracked[:previous_states] << {
+            state: old_state,
+            timestamp: tracked[:last_updated],
+            duration: Time.now - tracked[:last_updated],
+          }
+
+          # Keep only last 10 states
+          tracked[:previous_states] = tracked[:previous_states].last(10)
+
+          # Update current state
+          tracked[:current_state] = new_state
+          tracked[:last_updated] = Time.now
+          tracked[:change_count] += 1
+
+          # Record in history
+          change_event = {
+            timestamp: Time.now,
+            element_id: element_id,
+            element_name: tracked[:name],
+            old_state: old_state,
+            new_state: new_state,
+            changes: calculate_changes(old_state, new_state),
+          }
+
+          @state_history << change_event
+          @state_history = @state_history.last(1000) # Keep last 1000 changes
+
+          log_debug("Element state changed: #{tracked[:name]}", change_event[:changes])
+          notify_observers(:state_changed, element_id, change_event)
+
+          change_event
+        end
+      rescue StandardError => e
+        log_warn("Failed to update element state: #{e.message}")
+        nil
+      end
+    end
+
+    # Get current state of tracked element
+    def element_state(element_id)
+      tracked = @tracked_elements[element_id]
+      return nil unless tracked
+
+      # Update state before returning
+      update_element_state(element_id)
+      tracked[:current_state]
+    end
+
+    # Get element state history
+    def element_history(element_id, limit: 50)
+      @state_history
+        .select { |event| event[:element_id] == element_id }
+        .last(limit)
+    end
+
+    # Wait for element state change
+    def wait_for_state_change(element_id, expected_changes: {}, timeout: 10, interval: 0.5)
+      start_time = Time.now
+
+      loop do
+        current_state = element_state(element_id)
+
+        return current_state if expected_changes.all? { |key, value| current_state&.dig(key) == value }
+
+        if Time.now - start_time > timeout
+          raise Appom::TimeoutError,
+                "Element state did not change as expected within #{timeout}s. " \
+                "Expected: #{expected_changes}, Current: #{current_state}"
+        end
+
+        sleep interval
+      end
+    end
+
+    # Wait for element to be in specific state
+    def wait_for_state(element_id, condition, timeout: 10, interval: 0.5)
+      start_time = Time.now
+
+      loop do
+        current_state = element_state(element_id)
+
+        result = case condition
+                 when Proc
+                   condition.call(current_state)
+                 when Hash
+                   condition.all? { |key, value| current_state&.dig(key) == value }
+                 else
+                   false
+                 end
+
+        return current_state if result
+
+        if Time.now - start_time > timeout
+          raise Appom::TimeoutError,
+                "Element did not reach expected state within #{timeout}s. Current: #{current_state}"
+        end
+
+        sleep interval
+      end
+    end
+
+    # Stop tracking an element
+    def stop_tracking(element_id)
+      tracked = @tracked_elements.delete(element_id)
+      return unless tracked
+
+      log_debug("Stopped tracking element: #{tracked[:name]}")
+      notify_observers(:element_untracked, element_id)
+
+      # Return final summary
+      {
+        name: tracked[:name],
+        tracking_duration: Time.now - tracked[:first_seen],
+        change_count: tracked[:change_count],
+        final_state: tracked[:current_state],
+      }
+    end
+
+    # Get tracking summary
+    def tracking_summary
+      {
+        total_tracked: @tracked_elements.count,
+        total_changes: @state_history.count,
+        most_active: most_active_elements(5),
+        recent_changes: @state_history.last(10),
+        tracking_enabled: @tracking_enabled,
+      }
+    end
+
+    # Find elements by state criteria
+    def find_elements_by_state(criteria)
+      if criteria.is_a?(Hash)
+        # Always return array of tracked hashes for consistency with test expectations
+        @tracked_elements.values.select { |tracked| criteria.all? { |key, value| tracked[:current_state]&.dig(key) == value } }
+      else
+        @tracked_elements.values.select do |tracked|
+          current_state = tracked[:current_state]
+          case criteria
+          when Proc
+            criteria.call(current_state)
+          else
+            false
+          end
+        end
+      end
+    end
+
+    # Add state change observer
+    def add_observer(&block)
+      @observers << block
+      block
+    end
+
+    # Remove observer
+    def remove_observer(observer)
+      @observers.delete(observer)
+    end
+
+    # Enable/disable tracking
+    def tracking_enabled=(enabled)
+      @tracking_enabled = enabled
+      log_info("Element state tracking #{enabled ? 'enabled' : 'disabled'}")
+    end
+
+    # Clear all tracking data
+    def clear!
+      @tracked_elements.clear
+      @state_history.clear
+      log_info('Element state tracking data cleared')
+    end
+
+    # Export tracking data
+    def export_tracking_data(file_path: nil, format: :json)
+      file_path ||= "element_state_tracking_#{Time.now.strftime('%Y%m%d_%H%M%S')}.#{format}"
+
+      data = {
+        exported_at: Time.now,
+        summary: tracking_summary,
+        tracked_elements: serialize_tracked_elements,
+        state_history: @state_history,
+      }
+
+      case format
+      when :json
+        File.write(file_path, JSON.pretty_generate(data))
+      when :yaml
+        File.write(file_path, YAML.dump(data))
+      else
+        raise ArgumentError, "Unsupported format: #{format}"
+      end
+
+      log_info("Element state tracking data exported to #{file_path}")
+      file_path
+    end
+
+    private
+
+    def generate_element_id(element, name)
+      if name
+        name.to_s
+      else
+        # Try to generate meaningful ID from element
+        begin
+          attrs = []
+          attrs << element.attribute(:id) if element.attribute(:id)
+          attrs << element.attribute(:class) if element.attribute(:class)
+          attrs << element.tag_name if element.respond_to?(:tag_name)
+
+          id = attrs.any? ? attrs.join('_') : "element_#{element.object_id}"
+          id.gsub(/[^\w\-_]/, '_')
+        rescue StandardError
+          "element_#{element.object_id}"
+        end
+      end
+    end
+
+    def capture_element_state(element)
+      state = {
+        captured_at: Time.now,
+        exists: false,
+        displayed: false,
+        enabled: false,
+        selected: false,
+        text: nil,
+        attributes: {},
+        location: nil,
+        size: nil,
+      }
+
+      begin
+        state[:exists] = element.respond_to?(:displayed?) || element.respond_to?(:enabled?)
+
+        if state[:exists]
+          state[:displayed] = element.displayed? if element.respond_to?(:displayed?)
+          state[:enabled] = element.enabled? if element.respond_to?(:enabled?)
+          state[:selected] = element.selected? if element.respond_to?(:selected?)
+          state[:text] = element.text if element.respond_to?(:text)
+
+          # Capture common attributes
+          if element.respond_to?(:attribute)
+            %w[id class name type value placeholder].each do |attr|
+              value = element.attribute(attr.to_sym) || element.attribute(attr)
+              state[:attributes][attr.to_sym] = value if value
+            end
+          end
+
+          # Capture location and size
+          state[:location] = element.location if element.respond_to?(:location)
+
+          state[:size] = element.size if element.respond_to?(:size)
+        end
+      rescue StandardError => e
+        state[:error] = e.message
+        state[:exists] = false
+      end
+
+      state
+    end
+
+    def state_changed?(old_state, new_state)
+      # Compare relevant state properties, excluding timestamp fields
+      comparison_keys = %i[exists displayed enabled selected text attributes location size]
+
+      comparison_keys.any? { |key| old_state[key] != new_state[key] }
+    end
+
+    def calculate_changes(old_state, new_state)
+      changes = {}
+
+      old_state.each do |key, old_value|
+        new_value = new_state[key]
+
+        next unless old_value != new_value
+
+        changes[key] = {
+          from: old_value,
+          to: new_value,
+        }
+      end
+
+      changes
+    end
+
+    def most_active_elements(limit)
+      @tracked_elements
+        .map { |_id, tracked| [tracked[:name], tracked[:change_count]] }
+        .sort_by { |_, count| -count }
+        .first(limit)
+        .to_h
+    end
+
+    def notify_observers(event_type, *args)
+      @observers.each do |observer|
+        observer.call(event_type, *args)
+      rescue StandardError => e
+        log_error("Observer error: #{e.message}")
+      end
+    end
+
+    def serialize_tracked_elements
+      @tracked_elements.transform_values do |tracked|
+        {
+          name: tracked[:name],
+          context: tracked[:context],
+          first_seen: tracked[:first_seen],
+          last_updated: tracked[:last_updated],
+          current_state: tracked[:current_state],
+          change_count: tracked[:change_count],
+          previous_states_count: tracked[:previous_states].size,
+        }
+      end
+    end
+  end
+
+  # Element state monitoring mixin
+  module Monitoring
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    # Class methods for element state tracking
+    module ClassMethods
+      def track_state_changes
+        @state_tracking_enabled = true
+      end
+
+      def state_tracking_enabled?
+        @state_tracking_enabled ||= false
+      end
+    end
+
+    # Track this element's state
+    def track_state(name: nil, context: {})
+      return unless self.class.state_tracking_enabled?
+
+      ::Appom::ElementState.tracker.track_element(self, name: name, context: context)
+    end
+
+    # Update state and return changes
+    def update_state
+      return unless self.class.state_tracking_enabled?
+
+      ::Appom::ElementState.tracker.update_element_state(element_id) if defined?(@element_id)
+    end
+
+    # Get current state
+    def current_state
+      return unless self.class.state_tracking_enabled?
+
+      ::Appom::ElementState.tracker.element_state(element_id) if defined?(@element_id)
+    end
+
+    # Wait for state change
+    def wait_for_state_change(**args)
+      return unless self.class.state_tracking_enabled?
+
+      ::Appom::ElementState.tracker.wait_for_state_change(element_id, args.empty? ? {} : args) if defined?(@element_id)
+    end
+
+    private
+
+    def element_id
+      @element_id ||= ::Appom::ElementState.tracker.generate_element_id(self, nil)
+    end
+
+    def initialize(*)
+      super if defined?(super)
+    end
+  end
+
+  # Global state tracker
+  class << self
+    attr_writer :tracker
+
+    def tracker
+      @tracker ||= Tracker.new
+    end
+
+    # Convenience methods
+    def track_element(element, **)
+      tracker.track_element(element, **)
+    end
+
+    def element_state(element_id)
+      tracker.element_state(element_id)
+    end
+
+    def wait_for_state_change(element_id, **)
+      tracker.wait_for_state_change(element_id, **)
+    end
+
+    def tracking_summary
+      tracker.tracking_summary
+    end
+
+    def clear!
+      tracker.clear!
+    end
+
+    def export_data(**)
+      tracker.export_tracking_data(**)
+    end
+  end
+end

data/lib/appom/element_validation.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Element validation module for Appom automation framework
+# Provides validation for element definitions and arguments
+module Appom::ElementValidation
+  # Boolean values for validation
+  BOOLEAN_VALUES = [true, false].freeze
+
+  # Valid Appium locator strategies
+  VALID_LOCATOR_STRATEGIES = [
+    :accessibility_id,
+    :android_uiautomator,
+    :android_viewtag,
+    :android_data_matcher,
+    :android_view_matcher,
+    :ios_predicate,
+    :ios_uiautomation,
+    :ios_class_chain,
+    :class_name,
+    :class, # Alias for class_name
+    :css,
+    :id,
+    :name,
+    :link_text,
+    :partial_link_text,
+    :tag_name,
+    :xpath,
+  ].freeze
+
+  class << self
+    # Validate element definition arguments
+    def validate_element_args(name, *find_args)
+      validate_element_name(name)
+      validate_find_arguments(find_args)
+    end
+
+    # Validate section definition arguments
+    def validate_section_args(name, *args)
+      validate_element_name(name)
+
+      # Extract section class and find args
+      find_args = args.dup
+
+      if find_args.first.is_a?(Class)
+        section_class = find_args.shift
+        validate_section_class(section_class)
+      end
+
+      validate_find_arguments(find_args) unless find_args.empty?
+    end
+
+    private
+
+    def validate_element_name(name)
+      raise Appom::ConfigurationError.new('element_name', name, 'Element name must be a symbol') unless name.is_a?(Symbol)
+
+      raise Appom::ConfigurationError.new('element_name', name, 'Element name cannot be empty') if name.to_s.empty?
+
+      # Check for reserved method names
+      reserved_methods = %i[page parent root_element initialize]
+      return unless reserved_methods.include?(name)
+
+      raise Appom::ConfigurationError.new('element_name', name, 'Element name conflicts with reserved method')
+    end
+
+    def validate_find_arguments(find_args)
+      return if find_args.empty? # Allow empty args for some cases
+
+      flattened_args = find_args.flatten
+      return if flattened_args.empty?
+
+      # First argument should be a locator strategy (symbol)
+      locator_strategy = flattened_args.first
+      unless locator_strategy.is_a?(Symbol)
+        raise Appom::ConfigurationError.new('locator_strategy', locator_strategy,
+                                            'First argument must be a symbol representing locator strategy',)
+      end
+
+      unless VALID_LOCATOR_STRATEGIES.include?(locator_strategy)
+        valid_strategies = VALID_LOCATOR_STRATEGIES.map(&:to_s).join(', ')
+        raise Appom::ConfigurationError.new('locator_strategy', locator_strategy,
+                                            "Invalid locator strategy. Valid strategies: #{valid_strategies}",)
+      end
+
+      # Second argument should be the locator value (string)
+      if flattened_args.size > 1
+        locator_value = flattened_args[1]
+        unless locator_value.is_a?(String) || locator_value.is_a?(Hash)
+          raise Appom::ConfigurationError.new('locator_value', locator_value,
+                                              'Locator value must be a string or hash',)
+        end
+
+        if locator_value.is_a?(String) && locator_value.empty?
+          raise Appom::ConfigurationError.new('locator_value', locator_value,
+                                              'Locator value cannot be empty',)
+        end
+      else
+        raise Appom::ConfigurationError.new('find_arguments', find_args,
+                                            'Missing locator value. Expected format: :strategy, "value"',)
+      end
+
+      # Validate optional hash arguments
+      flattened_args[2..]&.each do |arg|
+        validate_element_options(arg) if arg.is_a?(Hash)
+      end
+    end
+
+    def validate_element_options(options)
+      valid_options = %i[text visible enabled timeout]
+
+      options.each do |key, value|
+        unless valid_options.include?(key)
+          valid_keys = valid_options.map(&:to_s).join(', ')
+          raise Appom::ConfigurationError.new('element_option', key,
+                                              "Invalid option. Valid options: #{valid_keys}",)
+        end
+
+        case key
+        when :text
+          raise Appom::ConfigurationError.new('text_option', value, 'Text option must be a string') unless value.is_a?(String)
+        when :visible, :enabled
+          raise Appom::ConfigurationError.new("#{key}_option", value, "#{key.capitalize} option must be true or false") unless BOOLEAN_VALUES.include?(value)
+        when :timeout
+          raise Appom::ConfigurationError.new('timeout_option', value, 'Timeout must be a positive number') unless value.is_a?(Numeric) && value.positive?
+        end
+      end
+    end
+
+    def validate_section_class(klass)
+      raise Appom::ConfigurationError.new('section_class', klass, 'Section class must be a Class') unless klass.is_a?(Class)
+
+      return if klass.ancestors.include?(Appom::Section)
+
+      raise Appom::ConfigurationError.new('section_class', klass,
+                                          'Section class must inherit from Appom::Section',)
+    end
+  end
+end