Project

xcmonkey

0.03
No release in over a year
xcmonkeyalteral/xcmonkeyHomepageDocumentationSource CodeBug TrackerWiki
xcmonkey is a tool for doing randomised UI testing of iOS apps
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
5,140
Stars
107
Forks
4
Watchers
4
 Releases
Current version
1.3.1
Total releases
10
First release
2022-12-27
Latest release
2023-02-08
 Issues
Open Issues
0
Closed Issues
6
Total Issues
6
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
2
Closed Pull Requests
26
Merged Pull Requests
32
Pull Request Acceptance Rate
53%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2023-06-11
Reverse Dependencies
1

 Dependencies

Runtime

colorize
~> 0.8.1
commander
>= 0
 Project Readme

Description

xcmonkey is a tool for doing stress testing of iOS apps. It's inspired by and has similar goals to monkey on Android.

Under the hood, xcmonkey uses iOS Development Bridge as a driver, that's why it's pretty smart and can do a lot of things, such as taps, swipes and presses. All that comes «pseudo-random» because it has access to the screen hierarchy, and so can either do actions blindly (like tapping on random points) or precisely (like tapping on the existing elements).

Prerequisites

brew install facebook/fb/idb-companion
pip3.6 install fb-idb

Installation

gem install xcmonkey

If you prefer to use bundler, add the following line to your Gemfile:

gem 'xcmonkey'

Usage

To run a stress test

$ 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",
  "udid": "413EA256-CFFB-4312-94A6-12592BEE4CBA",
  "state": "Booted",
  "type": "simulator",
  "os_version": "iOS 16.2",
  "architecture": "x86_64",
  "path": "/tmp/idb/413EA256-CFFB-4312-94A6-12592BEE4CBA_companion.sock",
  "is_local": true,
  "companion": "/tmp/idb/413EA256-CFFB-4312-94A6-12592BEE4CBA_companion.sock"
}

12:44:22.550: App info: {
  "bundle_id": "com.apple.Maps",
  "name": "Maps",
  "install_type": "system",
  "architectures": [
    "x86_64",
    "arm64"
  ],
  "process_state": "Running",
  "debuggable": false,
  "pid": "49186"
}

12:44:23.203: Tap: {
  "x": 53,
  "y": 749
}

12:44:23.511: Swipe (0.5s): {
  "x": 196,
  "y": 426
} => {
  "x": 143,
  "y": 447
}

12:44:24.355: Press (1.2s): {
  "x": 143,
  "y": 323
}

To repeat the stress test from generated session

xcmonkey repeat --session-path "./xcmonkey-session.json"

To describe the required point

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 Disable simulator keyboard false
Debugging --ignore-crashes Ignore app crashes false
--throttle <milliseconds> Fixed delay between events 0

fastlane integration

To get started with xcmonkey fastlane plugin, add it to your project by running:

fastlane add_plugin xcmonkey

Usage

lane :monkey_test do
  bundle_id = 'com.apple.Maps'
  device = 'iPhone 14'
  sim = FastlaneCore::Simulator.all.filter { |d| d.name == device }.max_by(&:os_version)
  udid = sim.udid

  xcmonkey(udid: udid, bundle_id: bundle_id)
end

Code of Conduct

Help us keep xcmonkey open and inclusive. Please read and follow our Code of Conduct.

License

This project is licensed under the terms of the MIT license. See the LICENSE file.