appom 1.4.0 → 2.0.0

data/lib/appom/wait.rb

@@ -1,42 +1,103 @@
-module Appom
-  class Wait
-    DEFAULT_TIMEOUT  = 5
-    DEFAULT_INTERVAL = 0.25
-
-    ##
-    # Create a new Wait instance
-    #
-    # @param [Hash] opts Options for this instance
-    # @option opts [Numeric] :timeout (5) Seconds to wait before timing out.
-    # @option opts [Numeric] :interval (0.25) Seconds to sleep between polls.
-    #
-    def initialize(opts = {})
-      @timeout  = opts.fetch(:timeout, DEFAULT_TIMEOUT)
-      @interval = opts.fetch(:interval, DEFAULT_INTERVAL)
-    end
+# frozen_string_literal: true
 
-    ##
-    # Wait until the given block returns a true value.
-    #
-    # @raise [Error::TimeOutError]
-    # @return [Object] the result of the block
-    #
-    def until
-      end_time = Time.now + @timeout
-      error_message = ""
-
-      until Time.now > end_time
-        begin
-          result = yield
-          return result if result
-        rescue => error
-          error_message = error.message
-        end
+# Provides wait functionality with configurable timeout and retry interval.
+#
+# The Wait class is used throughout Appom to wait for conditions to become true,
+# such as waiting for elements to appear or disappear, or for elements to reach
+# a certain state.
+#
+# @example Basic wait usage
+#   wait = Appom::Wait.new(timeout: 10, interval: 0.5)
+#   result = wait.until { some_condition }
+#
+# @example Wait for element to be displayed
+#   wait = Appom::Wait.new(timeout: 5)
+#   wait.until { element.displayed? }
+#
+# @since 0.1.0
+# @author Harry.Tran
+class Appom::Wait
+  include Appom::Logging
+
+  # Default timeout in seconds
+  DEFAULT_TIMEOUT  = 5
+  # Default retry interval in seconds
+  DEFAULT_INTERVAL = 0.25
+
+  # @!attribute [r] timeout
+  #   @return [Numeric] The timeout value in seconds
+  # @!attribute [r] interval
+  #   @return [Numeric] The interval between retries in seconds
+  attr_reader :timeout, :interval
+
+  # Create a new Wait instance
+  #
+  # @param opts [Hash] Options for this instance
+  # @option opts [Numeric] :timeout (5) Seconds to wait before timing out
+  # @option opts [Numeric] :interval (0.25) Seconds to sleep between polls
+  # @return [Wait] A new Wait instance
+  #
+  # @example Create wait with custom timeout
+  #   wait = Appom::Wait.new(timeout: 10, interval: 1.0)
+  def initialize(opts = {})
+    @timeout  = opts.fetch(:timeout, DEFAULT_TIMEOUT)
+    @interval = opts.fetch(:interval, DEFAULT_INTERVAL)
+  end
 
-        sleep @interval
+  # Wait until the given block returns a truthy value
+  #
+  # @yield [] Block to execute repeatedly until it returns true
+  # @return [Object] The result of the block when it returns truthy
+  # @raise [WaitError] If the timeout is reached before condition is met
+  # @raise [AppomError] Re-raises any Appom-specific errors from the block
+  #
+  # @example Wait for element to appear
+  #   wait.until { page.find_element(:id, 'button') }
+  #
+  # @example Wait with exception handling
+  #   wait.until do
+  #     element = page.find_element(:id, 'button')
+  #     element.displayed? && element.enabled?
+  #   end
+  def until(&)
+    end_time = Time.now + @timeout
+    error_message = ''
+    last_error = nil
+    start_time = Time.now
+
+    log_wait_start('custom condition', @timeout)
+
+    until Time.now > end_time
+      begin
+        result = yield
+        if result
+          duration = Time.now - start_time
+          log_wait_end('custom condition', duration.round(3), success: true)
+          return result
+        end
+      rescue StandardError => e
+        last_error = e
+        error_message = e.message
       end
 
-      raise StandardError, error_message
+      sleep @interval
+    end
+
+    duration = Time.now - start_time
+    log_wait_end('custom condition', duration.round(3), success: false)
+
+    # Handle exceptions differently based on type
+    if last_error.is_a?(StandardError) && last_error.instance_of?(StandardError)
+      # Wrap StandardError in WaitError with message included
+      condition = "condition (last error: #{error_message})"
+      raise Appom::WaitError.new(condition, @timeout)
+    elsif last_error
+      # Raise specific exceptions directly (ArgumentError, RuntimeError, etc.)
+      raise last_error
+    else
+      # No exceptions, just condition never became true
+      condition = error_message.empty? ? 'condition' : error_message
+      raise Appom::WaitError.new(condition, @timeout)
     end
   end
 end

data/lib/appom.rb

@@ -2,57 +2,228 @@
 
 require 'appom/version'
 require 'appium_lib'
-require 'appom/cucumber'
+require 'appom/exceptions'
+require 'appom/logging'
+require 'appom/element_validation'
+require 'appom/retry'
+require 'appom/wait'
+require 'appom/smart_wait'
+require 'appom/element_cache'
+require 'appom/screenshot'
+require 'appom/configuration'
 
+# The main Appom module provides a comprehensive Page Object Model framework for Appium.
+#
+# Appom gives you a simple, clean and semantic DSL for describing mobile applications.
+# It implements the Page Object Model pattern on top of Appium with enhanced error
+# handling, logging, performance monitoring, visual testing, and element state tracking.
+#
+# @example Basic usage
+#   # Register Appium driver
+#   Appom.register_driver do
+#     Appium::Driver.new(options, false)
+#   end
+#
+#   # Configure global settings
+#   Appom.configure do |config|
+#     config.max_wait_time = 30
+#   end
+#
+#   # Define page objects with enhanced features
+#   class LoginPage < Appom::Page
+#     element :email, :id, 'email_field'
+#     element :password, :id, 'password_field'
+#     element :submit, :accessibility_id, 'submit_button'
+#
+#     def login_with_monitoring(email, password)
+#       Appom::Performance.time_operation('login_process') do
+#         self.email.set email
+#         self.password.set password
+#         self.submit.click
+#       end
+#     end
+#   end
+#
+# @example Visual testing
+#   # Perform visual regression test
+#   Appom::Visual.regression_test('login_screen')
+#
+# @example Performance monitoring
+#   # Get performance statistics
+#   stats = Appom::Performance.summary
+#   puts "Average operation time: #{stats[:average_operation_time]}s"
+#
+# @see https://github.com/hoangtaiki/appom
+# @author Harry.Tran
 module Appom
-  # A item was defined without a selector.
-  class InvalidElementError < StandardError; end
-  # A block was passed to the method, which it cannot interpreter.
-  class UnsupportedBlockError < StandardError; end
+  include Appom::Logging
+  extend Appom::Logging
 
   autoload :ElementContainer, 'appom/element_container'
   autoload :Page, 'appom/page'
   autoload :Wait, 'appom/wait'
   autoload :Section, 'appom/section'
   autoload :ElementFinder, 'appom/element_finder'
+  autoload :Helpers, 'appom/helpers'
+  autoload :Retry, 'appom/retry'
+  autoload :SmartWait, 'appom/smart_wait'
+  autoload :ElementCache, 'appom/element_cache'
+  autoload :Screenshot, 'appom/screenshot'
+  autoload :Configuration, 'appom/configuration'
+  autoload :Performance, 'appom/performance'
+  autoload :ElementState, 'appom/element_state'
+  autoload :Visual, 'appom/visual'
 
   class << self
-    attr_accessor :driver
-    attr_accessor :max_wait_time
+    attr_accessor :driver, :max_wait_time
 
-    # Configure appom
+    # Configure appom global settings
+    #
+    # @yieldparam [self] config The Appom module for configuration
+    # @example Configure wait time
+    #   Appom.configure do |config|
+    #     config.max_wait_time = 30
+    #   end
     def configure
       yield self
     end
 
-    # Register a new appium driver for Appom.
-    # @return [Appium::Driver] A appium driver instance
-    def register_driver
-      @driver = yield
+    # Register a new Appium driver for Appom
+    #
+    # @yield [] Block that returns an Appium::Driver instance
+    # @return [Appium::Driver] The registered driver instance
+    # @raise [DriverError] If driver registration fails
+    #
+    # @example Register iOS driver
+    #   Appom.register_driver do
+    #     options = {
+    #       appium_lib: { server_url: 'http://localhost:4723' },
+    #       caps: { platformName: 'iOS', deviceName: 'iPhone 13' }
+    #     }
+    #     Appium::Driver.new(options, false)
+    #   end
+    def register_driver(&)
+      log_info('Registering Appium driver')
+
+      # Register driver with performance monitoring
+      @driver = Performance.time_operation('driver_registration', &)
+
       setup_exit_handler
+
+      # Initialize element state tracking if enabled
+      if Configuration.get('element_state.tracking_enabled', false)
+        ElementState.tracker
+        log_info('Element state tracking initialized')
+      end
+
+      log_info('Appium driver registered successfully')
+      @driver
+    rescue StandardError => e
+      log_error('Failed to register driver', { error: e.message })
+      raise DriverError, "Failed to register driver: #{e.message}"
     end
 
-    # Creates a new global driver and quits the old one if it exists.
+    # Start the registered Appium driver
+    #
+    # @raise [DriverNotInitializedError] If no driver has been registered
+    # @raise [DriverOperationError] If driver start fails
     def start_driver
-      @driver.start_driver
+      raise DriverNotInitializedError unless @driver
+
+      log_info('Starting Appium driver')
+
+      # Start driver with performance monitoring
+      Performance.time_operation('driver_start') do
+        @driver.start_driver
+      end
+
+      log_info('Appium driver started successfully')
+    rescue DriverNotInitializedError
+      raise
+    rescue StandardError => e
+      log_error('Failed to start driver', { error: e.message })
+      raise DriverOperationError.new('start_driver', e.message)
     end
 
-    # Reset the device, relaunching the application.
+    # Reset the device, relaunching the application
+    #
+    # @raise [DriverNotInitializedError] If no driver has been registered
+    # @raise [DriverOperationError] If driver reset fails
     def reset_driver
-      @driver.reset
+      raise DriverNotInitializedError unless @driver
+
+      log_info('Resetting Appium driver')
+
+      # Reset driver with performance monitoring
+      Performance.time_operation('driver_reset') do
+        @driver.reset
+      end
+
+      log_info('Appium driver reset successfully')
+    rescue DriverNotInitializedError
+      raise
+    rescue StandardError => e
+      log_error('Failed to reset driver', { error: e.message })
+      raise DriverOperationError.new('reset', e.message)
     end
 
     # After run all scenario and exit we will quit driver to close application under test
     def setup_exit_handler
       main = Process.pid
       at_exit do
-        @driver.driver_quit if Process.pid == main
+        cleanup_on_exit(main)
+      end
+    end
+
+    private
+
+    # Extracted method to enable testing
+    def cleanup_on_exit(main_pid)
+      return unless Process.pid == main_pid
+
+      begin
+        # Export performance metrics before quitting
+        if defined?(Performance) && Performance.monitor.metrics.any?
+          Performance.export_metrics(format: :json)
+          log_info('Performance metrics exported on exit')
+        end
+
+        @driver&.driver_quit
+      rescue StandardError => e
+        # Log error but don't raise during exit
+        warn "Warning: Failed to quit driver during exit: #{e.message}"
       end
     end
+
+    public
+
+    # Performance monitoring convenience methods
+    def performance_stats
+      Performance.summary
+    end
+
+    def export_performance_metrics(**)
+      Performance.export_metrics(**)
+    end
+
+    # Visual testing convenience methods
+    def visual_regression_test(name, **)
+      Visual.regression_test(name, **)
+    end
+
+    def generate_visual_report(**)
+      Visual.generate_report(**)
+    end
+
+    # Element state tracking convenience methods
+    def element_tracking_summary
+      ElementState.tracking_summary
+    end
+
+    def export_element_tracking(**)
+      ElementState.export_data(**)
+    end
   end
 
   @max_wait_time = 20
 end
-
-World(Appom)
-

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appom
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Harry.Tran
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-08-14 00:00:00.000000000 Z
+date: 2026-02-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: appium_lib
@@ -16,46 +16,48 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '9.4'
+        version: '16.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '9.4'
+        version: '16.0'
 - !ruby/object:Gem::Dependency
   name: cucumber
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '9.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.3'
+        version: '9.0'
 - !ruby/object:Gem::Dependency
-  name: rubocop
+  name: selenium-webdriver
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.58'
-  type: :development
+        version: '4.0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.58'
-description: Appom gives you a simple, clean and semantic for describing your application.
-  Appom implements the Page Object Model pattern on top of Appium.
+        version: '4.0'
+description: Appom provides a clean, semantic DSL for mobile application testing.
+  Built on Appium, it includes performance monitoring, visual regression testing,
+  element state tracking, smart waiting, and intelligent caching for enterprise-grade
+  test automation.
 email:
-- hoang@platphormcorp.com
+- duchoang.vp@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -63,17 +65,30 @@ files:
 - LICENSE.txt
 - README.md
 - lib/appom.rb
+- lib/appom/configuration.rb
 - lib/appom/cucumber.rb
+- lib/appom/element_cache.rb
 - lib/appom/element_container.rb
 - lib/appom/element_finder.rb
+- lib/appom/element_state.rb
+- lib/appom/element_validation.rb
+- lib/appom/exceptions.rb
+- lib/appom/helpers.rb
+- lib/appom/logging.rb
 - lib/appom/page.rb
+- lib/appom/performance.rb
+- lib/appom/retry.rb
+- lib/appom/screenshot.rb
 - lib/appom/section.rb
+- lib/appom/smart_wait.rb
 - lib/appom/version.rb
+- lib/appom/visual.rb
 - lib/appom/wait.rb
 homepage: https://github.com/hoangtaiki/appom
 licenses:
 - MIT
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -82,15 +97,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.2.3
+      version: 3.2.2
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.19
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
-summary: A Page Object Model for Appium
+summary: A comprehensive Page Object Model framework for Appium with advanced testing
+  capabilities
 test_files: []