monkey_master 1.0.0 → 1.1.0

data/.travis.yml

@@ -0,0 +1,11 @@
+language: ruby
+
+rvm:
+  - 2.0.0
+
+notifications:
+  email:
+    recipients:
+      - lukas.nagl@innovaptor.com
+    on_failure: change
+    on_success: never

data/README.md

@@ -1,5 +1,8 @@
-*monkey_master* - A tool for conveniently employing Android adb monkeys.
+`monkey_master` - A tool for conveniently employing Android adb monkeys.
 ================================================================
+
+[![Build Status](https://travis-ci.org/j4zz/monkey_master.svg)](https://travis-ci.org/j4zz/monkey_master)
+
 Android's adb offers the ui/application exerciser [monkey](http://developer.android.com/tools/help/monkey.html). Conveniently employing it can be cumbersome, though:
 
 * It's inconvenient to kill a running monkey.
@@ -7,15 +10,15 @@ Android's adb offers the ui/application exerciser [monkey](http://developer.andr
 * You either watch the log in your (running) sdk, or you manually handle logcat.
 * Managing all of the above on multiple devices is a real pain.
 
-*monkey_master* is a convenience tool for solving these issues. It can easily be combined with other tools, for example to build a fully automated build & test system.
+`monkey_master` is a convenience tool for solving these issues. It can easily be combined with other tools, for example to build a fully automated build & test system.
 
 Besides having convenience commands for starting and killing adb monkeys, it has multi-device support (simultaneously running monkeys on multiple devices) and automatically creates log files for each device.
 
-For an example of a *monkey_master* test setup, and the reasoning behind the project, visit: [http://innovaptor.com/blog/2013/08/18/building-an-automated-testing-and-error-reporting-system-for-android-apps-with-monkey-master-and-crashlytics.html](http://innovaptor.com/blog/2013/08/18/building-an-automated-testing-and-error-reporting-system-for-android-apps-with-monkey-master-and-crashlytics.html)
+For an example of a `monkey_master` test setup, and the reasoning behind the project, visit [this blog post](http://innovaptor.com/blog/2013/08/18/building-an-automated-testing-and-error-reporting-system-for-android-apps-with-monkey-master-and-crashlytics.html).
 
 Installation
 ================================================================
-*monkey_master* is available as a ruby gem:
+`monkey_master` is available as a ruby gem:
 
 	gem install monkey_master
 
@@ -23,7 +26,7 @@ Installation
 
 	export PATH=/YOUR/PATH/android-sdks/platform-tools:$PATH
 
-Furthermore, you need to have a device in development mode connected. Currently, *monkey_master* is not tested with an emulator. For a list of connected devices, use `adb devices`.
+Furthermore, you need to have a device in *development mode* connected. Currently, `monkey_master` is not tested with an emulator. For a list of connected devices, use `adb devices`.
 
 Usage
 ================================================================
@@ -40,18 +43,34 @@ An example for a test run could be:
 
 	monkey_master com.my.App --iterations 100
 
-If you want to stop the monkeys, either SIGINT the *monkey_master* during execution,
-or call:
+If you want to stop the monkeys, either SIGINT (keyboard interrupt) the `monkey_master` during execution, or call:
 
 	monkey_master -k
 
-If you have multiple devices connected, and want to use *monkey_master* on some of them only,
-call:
+If you have multiple devices connected, and want to use `monkey_master` on some of them only, call:
 
 	monkey_master com.my.App --devices DEVICEID1,DEVICEID2 --iterations 100
 
-Contributing
+Crash Reporting
+================================================================
+You might want to use `monkey_master` with a crash reporting tool such as [fabric](https://fabric.io/). Simply integrate the crash reporting library of your choice in your Android App, and `monkey_master`’s crashes will get reported there.
+
+Android Edge Cases
 ================================================================
-The initial version of *monkey_master* has been created with little ruby knowledge and with the pressure of an immediate need.
+Sometimes you encounter errors that only a monkey can generate, but that you can’t reasonably fix in your code. In case of such an error, you will want to exit gracefully if the user is a monkey (in order to suppress useless crash reports), but leave the error handling as it is for production.
 
+Furthermore, you might want to disable certain network calls, or redirect them to a test server.
+
+For such cases, there’s ActivityManager.isUserAMonkey():
+
+```java
+if(ActivityManager.isUserAMonkey()) {
+    // Work on the test server
+} else {
+    // Work on the production server
+}
+```
+
+Contributing
+================================================================
 Code style or beauty fixes are just as welcome as pull requests, bug reports or ideas.

data/Rakefile

@@ -1,9 +1,10 @@
 require "bundler/gem_tasks"
-require 'rake/testtask'
+require 'rspec/core/rake_task'
 
-Rake::TestTask.new do |t|
-  t.libs << 'test'
+# Default directory to look in is `/specs`
+# Run with `rake spec`
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color', '--format', 'documentation']
 end
 
-desc "Run tests"
-task :default => :test
+task default: :spec

data/bin/monkey_master

@@ -1,7 +1,6 @@
 #!/usr/bin/env ruby
 
 require 'docopt'
-
 require 'monkey_master'
 
 # Parse Command Line Options
@@ -9,44 +8,44 @@ doc = <<DOCOPT
 A tool for conveniently employing Android adb monkeys.
 
 Usage:
-  #{__FILE__} <app_id> [--devices <devices>] [--iterations <iterations>] [-k]
+  #{__FILE__} <app_id> [--devices <devices>] [--iterations <iterations>] [-k] [--adb <adb_args>]
   #{__FILE__} -k
   #{__FILE__} -h | --help
   #{__FILE__} --version
 
 Options:
-  -h --help     			Show this screen.
-  --version     			Show version.
-  --iterations <iterations>		The number of monkeys that should be run consecutively.
-  					It is preferable to run a high number of iterations of short-lived monkeys in order to handle freezes better.
-  --devices <devices>			Devices which should be used by the monkey commander separated by a ','. If not given, uses all devices.
-
+  -h --help           Show this screen.
+  --version           Show version.
+  --iterations <iterations>   The number of monkeys that should be run consecutively.
+            It is preferable to run a high number of iterations of short-lived monkeys in order to handle freezes better.
+  --devices <devices>     Devices which should be used by the monkey commander separated by a ','. If not given, uses all devices.
+  --adb <adb_args>      Arguments for running the adb monkey as a string, e.g. "--throttle 500". If not provided, reasonable defaults will be used.
 DOCOPT
 
 begin
-	opts = Docopt::docopt(doc)
-	commander = MonkeyMaster::MonkeyCommander.new(opts["<app_id>"])
-
-	devices = opts["--devices"]
-	commander.detect_devices(devices)
-
-	if(opts["-k"])
-		commander.kill_monkeys
-	end
-
-	if(opts["<app_id>"])
-		# An app id has been given, proceed with starting monkeys on the devices
-		iterations = opts["--iterations"]
-		if(iterations)
-			commander.iterations = iterations
-		end
-		commander.command_monkeys
-	end
-	exit 0
+  opts = Docopt::docopt(doc)
+  unless MonkeyMaster::ADB.adb?
+    puts 'ERROR: adb is not installed or not accessible'
+    exit 2
+  end
+  commander = MonkeyMaster::MonkeyCommander.new(opts['<app_id>'])
+
+  devices = opts['--devices']
+  commander.detect_devices(devices)
+
+  commander.kill_monkeys if opts['-k']
+
+  if opts['<app_id>']
+    # An app id has been given, proceed with starting monkeys on the devices
+    iterations = opts['--iterations']
+    commander.iterations = iterations if iterations
+    commander.command_monkeys(opts['--adb'])
+  end
+  exit 0
 rescue Docopt::Exit => e
-	puts e.message
+  puts e.message
 rescue ArgumentError => e
-	puts "ERROR: Invalid arguments: " + e.message
+  puts "ERROR: Invalid arguments: #{e.message}"
 end
 
-exit 1
+exit 1

data/lib/monkey_master.rb

@@ -2,4 +2,4 @@ module MonkeyMaster
 end
 
 require 'monkey_master/version'
-require 'monkey_master/monkey_commander.rb'
+require 'monkey_master/monkey_commander'

data/lib/monkey_master/adb.rb

@@ -0,0 +1,81 @@
+require 'mkmf'
+require 'pry'
+
+module MonkeyMaster
+  # Provide helpers to work with Android ADB
+  class ADB
+    # Run the adb monkey.
+    #
+    # +app_id+:: ID of the android app for which the monkey should be run
+    # +device+:: Device on which the adb monkey should be run
+    # +args+:: Arguments passed to the adb monkey
+    def self.monkey_run(app_id, device, args)
+      `adb -s #{device} shell monkey -p #{app_id} #{args}`
+      $?.exitstatus
+    end
+
+    # Force stop a monkey for an app.
+    #
+    # +app_id+:: ID of the android app for which the monkey should be stopped
+    def self.monkey_stop(app_id, device)
+      `adb -s #{device} shell am force-stop #{app_id}`
+    end
+
+    # Use ADB to detect connected Android devices.
+    def self.detect_devices
+      device_list = `adb devices | grep -v "List" | grep "device" | awk '{print $1}'`
+      device_list.split("\n")
+    end
+
+    # Kill ADB monkeys.
+    #
+    # +device+:: Devices for which the adb monkey should be killed
+    def self.kill_monkeys(devices)
+      unless devices
+        puts '[ADB] No devices specified yet.'
+        return
+      end
+
+      devices.each do |device|
+        puts "[ADB] KILLING the monkey on device #{device}."
+        `adb -s #{device} shell ps | awk '/com\.android\.commands\.monkey/ { system("adb -s #{device} shell kill " $2) }'`
+      end
+    end
+
+    # Start logging on a certain device with logcat
+    #
+    # +app_id+:: App for which logs should be retrieved
+    # +device+:: Device for which logging should be started
+    # +log+:: File that should be used for logging
+    def self.start_logging(app_id, device, log)
+      begin
+        timeout(5) do
+          puts "[ADB/LOGS] Logging device #{device} to #{log}."
+          `adb -s #{device} logcat -c #{log} &`
+          `adb -s #{device} logcat #{app_id}:W > #{log} &`
+        end
+      rescue Timeout::Error
+        end_logging
+        raise ArgumentError, 'It doesn’t seem like there are ready, connected devices.'
+      end
+    end
+
+    # End logging on multiple devices.
+    #
+    # +device+:: Devices for which logging should be stopped
+    def self.end_logging(devices)
+      devices.each do |device|
+        puts "[ADB/LOGS] KILLING the logcat process on device #{device}."
+        `adb -s #{device} shell ps | grep -m1 logcat | awk '{print $2}' | xargs adb -s #{device} shell kill`
+        puts "[ADB/LOGS] KILLING the logcat process for the device #{device} on the machine."
+        `ps ax | grep -m1 "adb -s #{device} logcat" | awk '{print $1}' | xargs kill`
+      end
+    end
+
+    # Check if adb is accessible as an executable
+    def self.adb?
+      adb = find_executable 'adb'
+      adb.nil? ? false : true
+    end
+  end
+end

data/lib/monkey_master/monkey_commander.rb

@@ -1,155 +1,131 @@
 require 'fileutils'
 require 'logger'
 require 'timeout'
+require 'pry'
+require_relative 'adb'
 
 module MonkeyMaster
-	# A class for conveniently employing Android adb monkeys.
-	#
-	# Author::    Lukas Nagl  (mailto:lukas.nagl@innovaptor.com)
-	# Copyright:: Copyright (c) 2013 Innovaptor OG
-	# License::   MIT
-	class MonkeyCommander
-		# Directory of the monkey logs.
-		attr_reader :log_dir
-		# Logger used for the monkey output.
-		attr_reader :logger
-		# The id of the app that should be tested by monkeys. E.g.: com.innovaptor.MonkeyTestApp
-		attr_writer :app_id
-		# The number of monkey iterations that should be run on each device.
-		attr_writer :iterations
-		# List of devices that should be used by the MonkeyCommander.
-		attr_writer :device_list
-	public
-		# Initialize the monkey master.
-		#
-	    # +app_id+:: The id of the app that should be tested by the monkeys, e.g. com.innovaptor.MonkeyTestApp
-		def initialize(app_id)
-			@app_id = app_id
-			@iterations = 1 # Default to a single iteration
-			@base_dir = Dir.pwd
-			time = Time.new
-			@log_dir = "monkey_logs" + time.strftime("%Y%m%d_%H%M%S")
-			@logger = Logger.new(STDOUT)
-			@logger.formatter = proc { |severity, datetime, progname, msg|
-			    "#{severity}|#{datetime}: #{msg}\n"
-			}
-		end
-
-		# Either create a list of devices from the parameter,
-		# or detect connected devices using adb.
-		#
-		# +devices+:: nil, for automatic device detection; or a list of device IDs separated by ','
-		def detect_devices(devices)
-			if(devices)
-				# Devices are given, create a list
-				devices = devices.split(',')
-				@device_list = devices
-			else
-				# No devices specified, detect them
-				device_list = %x(adb devices | grep -v "List" | grep "device" | awk '{print $1}')
-				device_list = device_list.split("\n")
-				@device_list = device_list
-			end
-		end
-
-		# Kill the monkey on each device.
-		def kill_monkeys
-			if(@device_list)
-				@device_list.each{|device|
-					@logger.info("[CLEANUP] KILLING the monkey on device #{device}.")
-					%x(adb -s #{device} shell ps | awk '/com\.android\.commands\.monkey/ { system("adb -s #{device} shell kill " $2) }')
-				}
-			else
-				@logger.warn("[CLEANUP] No devices specified yet.")
-			end
-		end
-
-		# Start running monkeys on all specified devices.
-		def command_monkeys
-			if(!@device_list || @device_list.empty?)
-				raise ArgumentError, "No devices found or specified."
-			end
-			if(!@app_id)
-				raise ArgumentError, "No app id specified."
-			end
-			prepare
-
-			masters = []
-			begin
-				@device_list.each{|device|
-					master = Thread.new{
-						# Monkey around in parallel
-
-						log_device_name = "monkey_current" + device + ".txt";
-						current_log = File.join(@log_dir, log_device_name)
-						start_logging(device, current_log)
-						@logger.info("[MASTER #{device}] Starting to command monkeys.")
-						@iterations.to_i.times do |i|
-							@logger.info("\t[MASTER #{device}] Monkey " + i.to_s + " is doing its thing...")
-
-							# Start the monkey
-							%x(adb -s #{device} shell monkey -p #{@app_id} -v 80000 --throttle 100 --ignore-timeouts --pct-majornav 10 --pct-appswitch 0 --kill-process-after-error)
-							if($? != 0)
-								@logger.info("\t\t[MASTER #{device}] Monkey encountered an error!")
-							end
-
-							# Archive the log
-							log_archiving_name = "monkeylog_" + device + "_" + i.to_s + ".txt"
-							FileUtils.cp(current_log, File.join(@log_dir, log_archiving_name))
-
-							# Clean the current log
-							File.truncate(current_log, 0)
-							@logger.info("\t\t[MASTER #{device}] Monkey " + i.to_s + " is killing the app now in preparation for the next monkey.")
-							%x(adb -s #{device} shell am force-stop #{@app_id})
-						end
-						@logger.info("[MASTER #{device}] All monkeys are done.")
-					}
-					masters.push(master)
-				}
-
-				masters.each{|master| master.join} # wait for all masters to finish
-			rescue SystemExit, Interrupt
-				# Clean and graceful shutdown, if possible
-				@logger.info("[MASTER] Received interrupt. Stopping all masters.")
-				masters.each{|master| master.terminate}
-			end
-
-			kill_monkeys
-			end_logging
-		end
-
-	private
-		# Do all necessary preparations that are necessary for the monkeys to run.
-		def prepare
-			if(!File.directory?(@log_dir))
-				Dir.mkdir(@log_dir);
-				@logger.info("[SETUP] Writing to the following folder: #{@log_dir}")
-			end
-			kill_monkeys
-		end
-
-		# Start logging on all devices.
-		def start_logging(device, current_log)
-			begin
-				Timeout::timeout(5) {
-		  			@logger.info("[SETUP] Creating the following log file: #{current_log}")
-					%x(adb -s #{device} logcat -c #{current_log} &)
-					%x(adb -s #{device} logcat *:W > #{current_log} &)
-				}
-			rescue Timeout::Error
-				end_logging
-				raise ArgumentError, "It doesn't seem like there are ready, connected devices."
-			end
-		end
-
-		# End logging on all devices.
-		def end_logging
-			@device_list.each{|device|
-				@logger.info("[CLEANUP] KILLING the logcat process on device #{device}.")
-				%x(adb -s #{device} shell ps | grep -m1 logcat | awk '{print $2}' | xargs adb -s #{device} shell kill)
-				@logger.info("[CLEANUP] KILLING the logcat process for the device #{device} on the machine.")
-				%x(ps ax | grep -m1 "adb -s #{device} logcat" | awk '{print $1}' | xargs kill)
-			}
-		end
-	end
+  # A class for conveniently employing Android adb monkeys.
+  #
+  # Author::    Lukas Nagl  (mailto:lukas.nagl@innovaptor.com)
+  # Copyright:: Copyright (c) 2013 Innovaptor OG
+  # License::   MIT
+  class MonkeyCommander
+    # Directory of the monkey logs.
+    attr_reader :log_dir
+    # Logger used for the monkey output.
+    attr_reader :logger
+    # The id of the app that should be tested by monkeys. E.g.: com.innovaptor.MonkeyTestApp
+    attr_writer :app_id
+    # The number of monkey iterations that should be run on each device.
+    attr_writer :iterations
+    # List of devices that should be used by the MonkeyCommander.
+    attr_writer :device_list
+
+    public
+
+    # Initialize the monkey master.
+    #
+    # +app_id+:: The id of the app that should be tested by the monkeys, e.g. com.innovaptor.MonkeyTestApp
+    def initialize(app_id)
+      @app_id = app_id
+      @iterations = 1 # Default to a single iteration
+      @base_dir = Dir.pwd
+      time = Time.new
+      @log_dir = 'monkey_logs' + time.strftime('%Y%m%d_%H%M%S')
+      @logger = Logger.new(STDOUT)
+      @logger.formatter = proc do |severity, datetime, _progname, msg|
+        "#{severity}|#{datetime}: #{msg}\n"
+      end
+    end
+
+    # Either create a list of devices from the parameter,
+    # or detect connected devices using adb.
+    #
+    # +devices+:: nil, for automatic device detection; or a list of device IDs separated by ','
+    def detect_devices(devices)
+      @device_list = devices ? devices.split(',') : ADB.detect_devices
+    end
+
+    # Kill the monkey on all detected devices.
+    def kill_monkeys
+      ADB.kill_monkeys(@device_list)
+    end
+
+    # Start running monkeys on all specified devices.
+    #
+    # +adb_args+:: Arguments passed to the adb monkeys
+    def command_monkeys(adb_args='-v 80000 --throttle 200 --ignore-timeouts --pct-majornav 20 --pct-appswitch 0 --kill-process-after-error')
+      @logger.info("[SETUP] Will run adb monkeys with the following arguments: #{adb_args}")
+      if !@device_list || @device_list.empty?
+        fail(ArgumentError, 'No devices found or specified. Check if development mode is on.')
+      end
+
+      fail(ArgumentError, 'No app id specified.') unless @app_id
+
+      prepare
+
+      masters = []
+      begin
+        @device_list.each do |device|
+          master = Thread.new do
+            # Monkey around in parallel
+
+            device_log = log_for_device(@app_id, device)
+
+            @logger.info("[MASTER #{device}] Starting to command monkeys.")
+            @iterations.to_i.times do |i|
+              @logger.info("\t[MASTER #{device}] Monkey #{i} is doing its thing…")
+
+              # Start the monkey
+              if ADB.monkey_run(@app_id, device, adb_args) != 0
+                @logger.info("\t\t[MASTER #{device}] Monkey encountered an error!")
+              end
+
+              # Archive and clean the log
+              archive_and_clean_log(device_log, "monkeylog_#{device}_#{i}.txt")
+
+              @logger.info("\t\t[MASTER #{device}] Monkey #{i} is killing the app now in preparation for the next monkey.")
+              ADB.monkey_stop(@app_id, device)
+            end
+            @logger.info("[MASTER #{device}] All monkeys are done.")
+          end
+          masters.push(master)
+        end
+
+        masters.each(&:join) # wait for all masters to finish
+      rescue SystemExit, Interrupt
+        # Clean and graceful shutdown, if possible
+        @logger.info('[MASTER] Received interrupt. Stopping all masters.')
+        masters.each(&:terminate)
+      end
+
+      ADB.kill_monkeys(@device_list)
+      ADB.end_logging(@device_list)
+    end
+
+    private
+
+    def archive_and_clean_log(device_log, name)
+      FileUtils.cp(device_log, File.join(@log_dir, name))
+      File.truncate(device_log, 0)
+    end
+
+    # start monkey log for a certain device
+    def log_for_device(app_id, device)
+      log_device_name = "monkey_current#{device}.txt"
+      log = File.join(@log_dir, log_device_name)
+      ADB.start_logging(app_id, device, log)
+      log
+    end
+
+    # Do all necessary preparations that are necessary for the monkeys to run.
+    def prepare
+      unless File.directory?(@log_dir)
+        Dir.mkdir(@log_dir)
+        @logger.info("[SETUP] Writing to the following folder: #{@log_dir}")
+      end
+      ADB.kill_monkeys(@device_list)
+    end
+  end
 end