https://github.com/testableapple/xcmonkey
Challenge your apps on iOS with monkey testing 📱🐒
https://github.com/testableapple/xcmonkey
Last synced: 8 months ago
JSON representation
Challenge your apps on iOS with monkey testing 📱🐒
- Host: GitHub
- URL: https://github.com/testableapple/xcmonkey
- Owner: testableapple
- License: mit
- Created: 2022-12-15T21:00:45.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-28T19:37:03.000Z (over 1 year ago)
- Last Synced: 2025-08-16T07:55:41.952Z (9 months ago)
- Language: Ruby
- Homepage: https://testableapple.com/note-36
- Size: 2.59 MB
- Stars: 113
- Watchers: 4
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
## Description
*xcmonkey* is a tool for doing stress testing of iOS apps. It's inspired by and has similar goals to [*monkey*](https://developer.android.com/studio/test/monkey) on Android.
Under the hood, *xcmonkey* uses [iOS Development Bridge](https://fbidb.io/) 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
```bash
brew install facebook/fb/idb-companion
pip3.6 install fb-idb
```
## Installation
```bash
gem install xcmonkey
```
If you prefer to use [*bundler*](https://bundler.io/), add the following line to your `Gemfile`:
```ruby
gem 'xcmonkey'
```
## Usage
### To run a stress test
```bash
$ 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
```bash
xcmonkey repeat --session-path "./xcmonkey-session.json"
```
### To describe the required point
```bash
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 ` | Set device UDID | |
| | `-b, --bundle-id ` | Set target bundle identifier | |
| | `-s, --session-path ` | Path where test session should be saved | |
| | `-e, --event-count ` | 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 ` | Fixed delay between events | `0` |
## [fastlane](https://github.com/fastlane/fastlane) integration
To get started with [xcmonkey fastlane plugin](https://github.com/testableapple/fastlane-plugin-xcmonkey), add it to your project by running:
```bash
fastlane add_plugin xcmonkey
```
### Usage
```ruby
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](CODE_OF_CONDUCT.md).
## License
This project is licensed under the terms of the MIT license. See the [LICENSE](LICENSE) file.