monkey_master 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA512: 
+  metadata.gz: b983e4acff0f8b829bdd925d79fc8c6ceaa822f8b8f2fe7d78504d6878ed7c2c12a6f1297491672db250b088a458345d28795edde2a32fe02d16803cae58df45
+  data.tar.gz: df069919c860e5d650e979fed3153b9d6c6451cd0194a65be571bb8a364418e9f3163e223960444ae8f77d4e11a29f0e1039e7a3591ad76217533ed3ca1926f2
+SHA1: 
+  metadata.gz: 4772c7790a6dc9aaab02b3c51af3c7861e46b22a
+  data.tar.gz: 8204783357e7bacbef55815c00b8039f28d2c27c

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+monkey_logs

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in monkey_master.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Innovaptor OG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,57 @@
+*monkey_master* - A tool for conveniently employing Android adb monkeys.
+================================================================
+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.
+* You can't let it run unobserved for extended periods of time because it ends after a crash or a freeze.
+* 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.
+
+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)
+
+Installation
+================================================================
+*monkey_master* is available as a ruby gem:
+
+	gem install monkey_master
+
+`adb` needs to be in your *PATH* variable. To do this, you could add the following to your `~/.bashrc` or `~/.profile` for example:
+
+	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`.
+
+Usage
+================================================================
+
+	Usage:
+  		monkey_master <app_id> [--devices <devices>] [--iterations <iterations>] [-k]
+  		monkey_master -k
+  		monkey_master -h | --help
+  		monkey_master --version
+
+Usage Examples
+----------------------------------------------------------------
+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:
+
+	monkey_master -k
+
+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
+================================================================
+The initial version of *monkey_master* has been created with little ruby knowledge and with the pressure of an immediate need.
+
+Code style or beauty fixes are just as welcome as pull requests, bug reports or ideas.

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/bin/monkey_master

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require 'docopt'
+
+require 'monkey_master'
+
+# Parse Command Line Options
+doc = <<DOCOPT
+A tool for conveniently employing Android adb monkeys.
+
+Usage:
+  #{__FILE__} <app_id> [--devices <devices>] [--iterations <iterations>] [-k]
+  #{__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.
+
+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
+rescue Docopt::Exit => e
+	puts e.message
+rescue ArgumentError => e
+	puts "ERROR: Invalid arguments: " + e.message
+end
+
+exit 1

data/lib/monkey_master.rb

@@ -0,0 +1,5 @@
+module MonkeyMaster
+end
+
+require 'monkey_master/version'
+require 'monkey_master/monkey_commander.rb'

data/lib/monkey_master/monkey_commander.rb

@@ -0,0 +1,155 @@
+require 'fileutils'
+require 'logger'
+require 'timeout'
+
+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
+end

data/lib/monkey_master/version.rb

@@ -0,0 +1,3 @@
+module MonkeyMaster
+  VERSION = "1.0.0"
+end

data/monkey_master.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'monkey_master/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "monkey_master"
+  spec.version       = MonkeyMaster::VERSION
+  spec.authors       = ["Lukas Nagl"]
+  spec.email         = ["lukas.nagl@innovaptor.com"]
+  spec.description   = %q{A tool for conveniently employing Android adb monkeys.}
+  spec.summary       = %q{A tool for conveniently employing Android adb monkeys.}
+  spec.homepage      = "https://github.com/j4zz/monkey_master.git"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/test/test_monkey_master.rb

@@ -0,0 +1,50 @@
+require 'test/unit'
+require 'monkey_master'
+
+class MonkeyCommanderTest < Test::Unit::TestCase
+	# Test the kill option in case no devices are connected
+	def test_kill_no_devices
+		assert_nothing_raised do
+			commander = MonkeyMaster::MonkeyCommander.new("com.test.Example")
+			commander.kill_monkeys
+		end
+	end
+
+	# Test the kill option with a list of invalid devices
+	def test_kill_invalid_devices
+		assert_nothing_raised do
+			commander = MonkeyMaster::MonkeyCommander.new("com.test.Example")
+			commander.device_list = ["80123","34555"]
+			commander.kill_monkeys
+		end
+	end
+
+	# Test trying regular execution in case no devices are connected
+	def test_command_no_devices
+		assert_raise ArgumentError do
+			commander = MonkeyMaster::MonkeyCommander.new("com.test.Example")
+			# no devices
+			commander.command_monkeys
+		end
+	end
+
+	# Test trying regular execution with an invalid app id
+	def test_command_no_app_id
+		assert_raise ArgumentError do
+			commander = MonkeyMaster::MonkeyCommander.new(nil)
+			commander.device_list = ["80123","34555"]
+			# no app id
+			commander.command_monkeys
+		end
+	end
+
+	# Test trying regular execution when invalid devices are given
+	def test_command_invalid_devices
+		assert_raise ArgumentError do
+			commander = MonkeyMaster::MonkeyCommander.new("com.test.Example")
+			commander.device_list = ["80123","34555"]
+			# invalid devices, should raise an exception
+			commander.command_monkeys
+		end
+	end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification 
+name: monkey_master
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Lukas Nagl
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-08-18 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.3"
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - &id003 
+      - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: A tool for conveniently employing Android adb monkeys.
+email: 
+- lukas.nagl@innovaptor.com
+executables: 
+- monkey_master
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/monkey_master
+- lib/monkey_master.rb
+- lib/monkey_master/monkey_commander.rb
+- lib/monkey_master/version.rb
+- monkey_master.gemspec
+- test/test_monkey_master.rb
+homepage: https://github.com/j4zz/monkey_master.git
+licenses: 
+- MIT
+metadata: {}
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id003
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id003
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A tool for conveniently employing Android adb monkeys.
+test_files: 
+- test/test_monkey_master.rb