Add new test options (#11)

Author: testableapple

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.3.0](https://github.com/alteral/xcmonkey/releases/tag/1.3.0)
+
+_January 29, 2023_
+
+### 🔄 Changed
+
+- `duration` option is renamed to `event-count`
+
+### ✅ Added
+
+- New test options that allow to
+  - specify gestures to exclude from the test
+  - set up throttle between events
+  - ignore app crashes
+
 ## [1.2.0](https://github.com/alteral/xcmonkey/releases/tag/1.2.0)
 
 _January 23, 2023_

Gemfile

@@ -17,3 +17,4 @@ gem 'rubocop-rake', '0.6.0'
 gem 'rubocop-require_tools'
 gem 'rubocop-rspec', '2.15.0'
 gem 'simplecov'
+gem 'solargraph'

README.md

@@ -39,7 +39,7 @@ gem 'xcmonkey'
 ### To run a stress test
 
 ```bash
-$ xcmonkey test --duration 100 --bundle-id "com.apple.Maps" --udid "413EA256-CFFB-4312-94A6-12592BEE4CBA"
+$ xcmonkey test --event-count 100 --bundle-id "com.apple.Maps" --udid "413EA256-CFFB-4312-94A6-12592BEE4CBA"
 
 12:44:19.343: Device info: {
   "name": "iPhone 14 Pro",
@@ -97,6 +97,26 @@ xcmonkey repeat --session-path "./xcmonkey-session.json"
 xcmonkey describe -x 20 -y 625 --udid "413EA256-CFFB-4312-94A6-12592BEE4CBA"
 ```
 
+### Test options reference
+
+The table below lists all options you can include on the `xcmonkey test` command line.
+
+| Category | Option | Description | Default |
+| --- | --- | --- | --- |
+| **General** | `-h, --help` | Display help documentation | |
+| | `-v, --version` | Display version information | |
+| | `-t, --trace` | Display backtrace when an error occurs | |
+| **Events** | `-u, --udid <string>` | Set device UDID | |
+| | `-b, --bundle-id <string>` | Set target bundle identifier | |
+| | `-s, --session-path <string>` | Path where test session should be saved | |
+| | `-e, --event-count <integer>` | Set events count | `60` |
+| | `--exclude-taps` | Exclude taps from gestures list | `false` |
+| | `--exclude-swipes` | Exclude swipes from gestures list | `false` |
+| | `--exclude-presses` | Exclude presses from gestures list | `false` |
+| | `--disable-simulator-keyboard` | Should simulator keyboard be disable? | `false` |
+| **Debugging** | `--ignore-crashes` | Should app crashes be ignored? | `false` |
+| | `--throttle <milliseconds>` | Fixed delay between events | `0` |
+
 ## [fastlane](https://github.com/fastlane/fastlane) integration
 
 To run *xcmonkey* from *fastlane*, add the following code to your `Fastfile`:
@@ -106,7 +126,7 @@ require 'xcmonkey'
 
 lane :test do
   Xcmonkey.new(
-    duration: 100,
+    event_count: 100,
     bundle_id: 'com.apple.Maps',
     udid: '413EA256-CFFB-4312-94A6-12592BEE4CBA'
   ).run

bin/xcmonkey

@@ -17,16 +17,26 @@ class Xcmonkey
     c.description = 'Runs monkey test'
     c.option('-u', '--udid STRING', String, 'Set device UDID')
     c.option('-b', '--bundle-id STRING', String, 'Set target bundle identifier')
-    c.option('-d', '--duration SECONDS', Integer, 'Test duration in seconds. Defaults to `60`')
-    c.option('-k', '--enable-simulator-keyboard', 'Should simulator keyboard be enabled? Defaults to `true`')
-    c.option('-s', '--session-path STRING', String, 'Path where monkey testing session should be saved. Defaults to current directory')
+    c.option('-e', '--event-count NUMBER', Integer, 'Set events count. Defaults to `60`')
+    c.option('-s', '--session-path STRING', String, 'Path where test session should be saved')
+    c.option('--throttle MILLISECONDS', Integer, 'Fixed delay between events in milliseconds. Defaults to `0`')
+    c.option('--exclude-taps', 'Exclude taps from gestures list. Defaults to `false`')
+    c.option('--exclude-swipes', 'Exclude swipes from gestures list. Defaults to `false`')
+    c.option('--exclude-presses', 'Exclude presses from gestures list. Defaults to `false`')
+    c.option('--ignore-crashes', 'Should app crashes be ignored? Defaults to `false`')
+    c.option('--disable-simulator-keyboard', 'Should simulator keyboard be disable? Defaults to `false`')
     c.action do |_, options|
       params = {
         udid: options.udid,
         bundle_id: options.bundle_id,
-        duration: options.duration,
+        event_count: options.event_count,
+        throttle: options.throttle,
         session_path: options.session_path,
-        enable_simulator_keyboard: options.enable_simulator_keyboard
+        exclude_taps: options.exclude_taps,
+        exclude_swipes: options.exclude_swipes,
+        exclude_presses: options.exclude_presses,
+        ignore_crashes: options.ignore_crashes,
+        disable_simulator_keyboard: options.disable_simulator_keyboard
       }
       Xcmonkey.new(params).run
     end

fastlane/Fastfile

@@ -8,9 +8,9 @@ lane :release do
   set_github_release(
     repository_name: 'alteral/xcmonkey',
     api_token: ENV.fetch("GITHUB_TOKEN", nil),
-    name: "xcmonkey v#{version}",
-    tag_name: "v#{version}",
-    description: "v#{version}",
+    name: version,
+    tag_name: version,
+    description: "See [CHANGELOG.md](https://github.com/alteral/xcmonkey/blob/main/CHANGELOG.md##{version.delete('.')}})",
     commitish: git_branch,
     upload_assets: [gem_path]
   )

lib/xcmonkey.rb

@@ -7,36 +7,37 @@
 require_relative 'xcmonkey/driver'
 
 class Xcmonkey
-  attr_accessor :driver
+  attr_accessor :params, :driver
 
   def initialize(params)
-    params[:session_path] = Dir.pwd if params[:session_path].nil?
-    params[:duration] = 60 if params[:duration].nil?
-    params[:enable_simulator_keyboard] = true if params[:enable_simulator_keyboard].nil?
-    ensure_required_params(params)
+    params[:event_count] = 60 if params[:event_count].nil?
+    params[:ignore_crashes] = false if params[:ignore_crashes].nil?
+    params[:disable_simulator_keyboard] = false if params[:disable_simulator_keyboard].nil?
+    self.params = params
     self.driver = Driver.new(params)
+    ensure_required_params
   end
 
   def run
     driver.monkey_test(gestures)
   end
 
   def gestures
-    taps = [:precise_tap, :blind_tap] * 10
-    swipes = [:precise_swipe, :blind_swipe] * 5
-    presses = [:precise_press, :blind_press]
+    taps = params[:exclude_taps] ? [] : [:precise_tap, :blind_tap] * 10
+    swipes = params[:exclude_swipes] ? [] : [:precise_swipe, :blind_swipe] * 5
+    presses = params[:exclude_presses] ? [] : [:precise_press, :blind_press]
     taps + swipes + presses
   end
 
-  def ensure_required_params(params)
+  def ensure_required_params
     Logger.error('UDID should be provided') if params[:udid].nil?
 
     Logger.error('Bundle identifier should be provided') if params[:bundle_id].nil?
 
-    Logger.error('Session path should be a directory') if params[:session_path].nil? || !File.directory?(params[:session_path])
+    Logger.error('Session path should be a directory') if params[:session_path] && !File.directory?(params[:session_path])
 
-    if params[:duration].nil? || !params[:duration].kind_of?(Integer) || !params[:duration].positive?
-      Logger.error('Duration must be Integer and not less than 1 second')
+    if params[:event_count].nil? || !params[:event_count].kind_of?(Integer) || !params[:event_count].positive?
+      Logger.error('Event count must be Integer and not less than 1')
     end
   end
 end

lib/xcmonkey/driver.rb

@@ -1,12 +1,14 @@
 class Driver
-  attr_accessor :udid, :bundle_id, :enable_simulator_keyboard, :session_duration, :session_path, :session_actions
+  attr_accessor :udid, :bundle_id, :disable_simulator_keyboard, :event_count, :session_path, :session_actions, :ignore_crashes, :throttle
 
   def initialize(params)
     self.udid = params[:udid]
+    self.throttle = params[:throttle]
     self.bundle_id = params[:bundle_id]
-    self.session_duration = params[:duration]
+    self.event_count = params[:event_count]
     self.session_path = params[:session_path]
-    self.enable_simulator_keyboard = params[:enable_simulator_keyboard]
+    self.ignore_crashes = params[:ignore_crashes]
+    self.disable_simulator_keyboard = params[:disable_simulator_keyboard]
     self.session_actions = params[:session_actions]
     @session = { params: params, actions: [] }
     ensure_driver_installed
@@ -23,10 +25,8 @@ def monkey_test_precondition
 
   def monkey_test(gestures)
     monkey_test_precondition
-    app_elements = describe_ui.shuffle
-    current_time = Time.now
-    counter = 0
-    while Time.now < current_time + session_duration
+    event_count.times do |counter|
+      app_elements = describe_ui.shuffle
       el1_coordinates = central_coordinates(app_elements.first)
       el2_coordinates = central_coordinates(app_elements.last)
       case gestures.sample
@@ -53,18 +53,14 @@ def monkey_test(gestures)
       else
         next
       end
-      detect_app_state_change
-      track_running_apps if counter % 5 == 0 # Track running apps after every 5th action to speed up the test
-      counter += 1
-      app_elements = describe_ui.shuffle
+      checkup(counter)
     end
     save_session
   end
 
   def repeat_monkey_test
     monkey_test_precondition
-    counter = 0
-    session_actions.each do |action|
+    session_actions.each_with_index do |action, counter|
       case action['type']
       when 'tap'
         tap(coordinates: { x: action['x'], y: action['y'] })
@@ -79,10 +75,16 @@ def repeat_monkey_test
       else
         next
       end
-      detect_app_state_change
-      track_running_apps if counter % 5 == 0
-      counter += 1
+      checkup(counter)
+    end
+  end
+
+  def checkup(counter)
+    detect_app_state_change
+    if counter % 5 == 0 || throttle.to_i > 0 # Track running apps after every 5th action
+      track_running_apps                     # (unless `throttle` was provided) to speed up the test
     end
+    check_speed_limit
   end
 
   def describe_ui
@@ -115,7 +117,7 @@ def shutdown_simulator
 
   def configure_simulator_keyboard
     shutdown_simulator
-    keyboard_status = enable_simulator_keyboard ? 0 : 1
+    keyboard_status = disable_simulator_keyboard ? 1 : 0
     `defaults write com.apple.iphonesimulator ConnectHardwareKeyboard #{keyboard_status}`
   end
 
@@ -165,10 +167,8 @@ def press(coordinates:, duration:)
   end
 
   def swipe(start_coordinates:, end_coordinates:, duration:)
-    Logger.info(
-      "Swipe (#{duration}s):",
-      payload: "#{JSON.pretty_generate(start_coordinates)} => #{JSON.pretty_generate(end_coordinates)}"
-    )
+    payload = "#{JSON.pretty_generate(start_coordinates)} => #{JSON.pretty_generate(end_coordinates)}"
+    Logger.info("Swipe (#{duration}s):", payload: payload)
     unless session_actions
       @session[:actions] << {
         type: :swipe,
@@ -188,8 +188,8 @@ def central_coordinates(element)
     x = (frame['x'] + (frame['width'] / 2)).abs.to_i
     y = (frame['y'] + (frame['height'] / 2)).abs.to_i
     {
-      x: x > screen_size[:width].to_i ? rand(0..screen_size[:width].to_i) : x,
-      y: y > screen_size[:height].to_i ? rand(0..screen_size[:height].to_i) : y
+      x: x > screen_size[:width].to_i ? random_coordinates[:x] : x,
+      y: y > screen_size[:height].to_i ? random_coordinates[:y] : y
     }
   end
 
@@ -222,6 +222,8 @@ def press_duration
   end
 
   def save_session
+    return if session_path.nil?
+
     File.write("#{session_path}/xcmonkey-session.json", JSON.pretty_generate(@session))
   end
 
@@ -236,6 +238,7 @@ def track_running_apps
       return if new_apps.empty?
 
       launch_app(target_bundle_id: bundle_id)
+
       new_apps.each do |id|
         Logger.warn("Shutting down: #{id}")
         terminate_app(id)
@@ -249,7 +252,7 @@ def detect_app_state_change
 
     target_app_is_running = list_running_apps.any? { |app| app['bundle_id'] == bundle_id }
 
-    if target_app_is_running
+    if target_app_is_running || ignore_crashes
       launch_app(target_bundle_id: bundle_id)
     else
       save_session
@@ -262,6 +265,10 @@ def detect_app_in_background
     current_app_label.nil? || current_app_label.strip.empty?
   end
 
+  def check_speed_limit
+    sleep(throttle / 1000.0) if throttle.to_i > 0
+  end
+
   private
 
   def ensure_driver_installed

lib/xcmonkey/repeater.rb

@@ -1,5 +1,5 @@
 class Repeater
-  attr_accessor :udid, :bundle_id, :enable_simulator_keyboard, :actions
+  attr_accessor :udid, :bundle_id, :disable_simulator_keyboard, :ignore_crashes, :actions, :throttle
 
   def initialize(params)
     validate_session(params[:session_path])
@@ -8,8 +8,10 @@ def initialize(params)
   def run
     params = {
       udid: udid,
+      throttle: throttle,
       bundle_id: bundle_id,
-      enable_simulator_keyboard: enable_simulator_keyboard,
+      ignore_crashes: ignore_crashes,
+      disable_simulator_keyboard: disable_simulator_keyboard,
       session_actions: actions
     }
     Driver.new(params).repeat_monkey_test
@@ -34,6 +36,10 @@ def validate_session(session_path)
     self.bundle_id = session['params']['bundle_id']
     Logger.error('Provided session is not valid: `bundle_id` should not be `nil`') if bundle_id.nil?
 
-    self.enable_simulator_keyboard = session['params']['enable_simulator_keyboard']
+    self.throttle = session['params']['throttle']
+
+    self.ignore_crashes = session['params']['ignore_crashes']
+
+    self.disable_simulator_keyboard = session['params']['disable_simulator_keyboard']
   end
 end

lib/xcmonkey/version.rb

@@ -1,3 +1,3 @@
 class Xcmonkey
-  VERSION = '1.2.0'
+  VERSION = '1.3.0'
 end