kraken-mobile 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4bfa46c21f03853b64f32b256ba62bf2fc4083da
+  data.tar.gz: 85837852d965698ffa5d9b1740dbc02f893265bc
+SHA512:
+  metadata.gz: 8a46f5c652991f58a69bf6a4df6a87f76078e90055077acf16cdb1d00916629c9664dbacfe14a361dffd21b713fca01349809dfe27a9022c155e06865027a827
+  data.tar.gz: e1c1b7ae29b49f6094c1b73598235ff2743523fff4f0c73b0eea3fe6e4816d5e1f63e8640a174c75722194598fc4a5c0e6e5bf57cf9258779dc8793e4bc56f13

data/LICENSE

@@ -0,0 +1,8 @@
+Kraken-Mobile Copyright (2019) Ravelinx22. All rights reserved.
+The use and distribution terms for this software are covered by the
+Eclipse Public License 1.0
+(http://opensource.org/licenses/eclipse-1.0.php) which can be found in
+the file epl-v10.html at the root of this distribution.  By using this
+software in any fashion, you are agreeing to be bound by the terms of
+this license.  You must not remove this notice, or any other, from
+this software.

data/README.md

@@ -0,0 +1,169 @@
+<p align="center">
+  <a href="https://getbootstrap.com/">
+    <img src="https://raw.githubusercontent.com/ravelinx22/KrakenMobile/master/reporter/assets/images/kraken.png" alt="Bootstrap logo" width="140" height="193">
+  </a>
+</p>
+
+<h3 align="center">Kraken Mobile</h3>
+
+<p align="center">Kraken is an open source automated android E2E testing tool that supports and validates scenarios that involve the inter-communication between two or more users. It works in a Black Box manner meaning that it’s not required to have access to the source code of the application but instead it can be run with the APK (Android package file format). Kraken uses signaling for coordinating the communication between the devices using a file based protocol.</p>
+
+## Table of contents
+
+- [Technologies](#technologies)
+- [Installation](#installation)
+- [Signaling](#signaling)
+- [Writing your first test](#writing-your-first-test)
+- [Kraken steps](#kraken-steps)
+- [Running your tests](#running-your-tests)
+- [Kraken Settings](#kraken-settings)
+- [Properties file](#properties-file)
+
+## Technologies
+
+Kraken uses [calabash-android](https://github.com/calabash/calabash-android) for running automated E2E tests in each device or emulator and [cucumber](https://github.com/cucumber/cucumber-ruby) for running your feature files written with Gherkin sintax. 
+
+## Installation
+
+### Prerequisites
+
+Kraken requires Ruby 2.20 or higher but we recommend using ~2.3 version. We use calabash-android as runner, you can check their prerequisites at this [link](https://github.com/calabash/calabash-android/blob/master/documentation/installation.md)
+
+
+Installing and managing a Gem is done through the gem command. To install Kraken's gem run the following command
+
+    $ gem install kraken-mobile
+
+
+## Signaling
+
+Signaling is a protocol used for the communication of two or more devices running in parallel. It’s based in the idea that each emulator or real device has a communication channel where he can receive signals sent from other devices which contain information or actions that are supposed to be executed. This type of protocol is commonly used in automated mobile E2E testing tools that validate scenarios involving the inter-communication and collaboration of two or more applications.
+
+## Writing your first test
+
+### Generate cucumber feature skeleton
+
+First you need to generate the cucumber feature skeleton where your tests are going to be saved. To achieve this you should run `kraken-mobile gen`. It will create the skeleton in your current folder like this:
+
+    features
+    |_support
+    | |_app_installation_hooks.rb
+    | |_app_life_cycle_hooks.rb
+    | |_env.rb
+    |_step_definitions
+    | |_kraken_steps.rb
+    |_my_first.feature
+
+### Write a test
+
+The features goes in the features foler and should have the ".feature" extension.
+
+You can start out by looking at features/my_first.feature. You should also check calabash [predefined steps](https://github.com/calabash/calabash-android/blob/master/ruby-gem/lib/calabash-android/canned_steps.md).
+
+### Syntax
+
+In Kraken each feature is a test and each scenario within a feature is a test case that is run in a device. Each device is identified as an user and numbered from 1 to N. Ex: @user1, @user2, @user3. To check what is the number of a given device you should run `kraken-mobile devices`
+
+    List of devices attached
+    user1 - emulator-5554 - Android_SDK_built_for_x86
+    user2 - emulator-5556 - Android_SDK_built_for_x86
+
+After identifying what number each device has, you can write your test case giving each scenario the tag of a given device like so:
+
+    Feature: Example feature
+
+      @user1
+      Scenario: As a first user I say hi to a second user
+        Given I wait
+        Then I send a signal to user 2 containing "hi"
+
+      @user2
+      Scenario: As a second user I wait for user 1 to say hi
+        Given I wait for a signal containing "hi"
+        Then I wait
+
+## Kraken steps
+
+Kraken offers two main steps to help synchronizing your devices.
+
+### Signaling steps
+
+To wait for a signal coming from another device for 10 seconds that is Kraken default timeout use the following step.
+
+    Then /^I wait for a signal containing "([^\"]*)"$/
+
+To wait for a signal coming from another device for an specified number of seconds use the following step
+
+    Then /^I wait for a signal containing "([^\"]*)" for (\d+) seconds$/
+
+To send a signal to another specified device use the following step
+
+    Then /^I send a signal to user (\d+) containing "([^\"]*)"$/
+
+### Signaling functions
+
+Kraken internal implementation of the signaling steps use the following functions.
+
+#### readSignal(channel, content, timeout)
+
+Waits for a signal with the specified content in the channel passed by parameter. This functions waits for the specified number of seconds in the timeout parameter before throwing an exception.
+
+**Note: The channel parameter has to be the number of a device such as @user1, @user2, @userN**
+
+#### writeSignal(channel, content)
+
+Writes content to a channel passed by parameter.
+
+**Note: The channel parameter has to be the number of a device such as @user1, @user2, @userN**
+
+## Running your tests
+
+To run your test:
+
+    kraken-mobile run <apk>
+
+Kraken with the help of Calabash-Android will install an instrumentation along with your app and will start your tests in all devices connected (Check Kraken Settings section in order to learn how to specify in what devices your tests should be run).
+
+## Kraken Settings
+
+Kraken uses kraken_mobile_settings.json to specify in what devices the tests should be run.
+
+### Generate settings file
+
+The following command will show you the available connected devices or emulators and let you choose which ones you want to use.
+
+    kraken-mobile setup
+
+### Run tests with settings file
+
+    kraken-mobile run <apk> --configuration=<kraken_mobile_settings_path>
+
+## Properties file
+
+Kraken uses properties files to store sensitive data such as passwords or api keys that should be used in your test cases.
+
+### Generate properties file
+
+The properties files should be a manually created json file with the following structure.
+
+    {
+      "@user1": {
+        "PASSWORD": "test"
+      },
+      "@user2": {
+        "PASSWORD": "test2"
+      }
+    }
+    
+### Use properties file in your test
+
+You can use the specified properties using the following sintax.
+
+    @user1
+    Scenario: As a kjkhdkjds
+        Given I wait
+        Then I see the text "<PASSWORD>"
+
+### Run tests with settings file
+
+    kraken-mobile run <apk> --properties=<kraken_mobile_properties_path>

data/bin/kraken-mobile

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+
+require File.join(File.dirname(__FILE__), "kraken-mobile-helpers")
+require File.join(File.dirname(__FILE__), "kraken-mobile-setup")
+require File.join(File.dirname(__FILE__), "kraken-mobile-calabash-android")
+$LOAD_PATH << File.expand_path("../../lib", __FILE__)
+require 'kraken-mobile'
+require 'kraken-mobile/constants'
+
+#-------------------------------
+# AGV reader helper
+#-------------------------------
+
+def read_specified_runner
+  runner_command = ARGV.select { |arg| arg.include?("--runner=") }.first
+  if runner_command
+    formatted_runner_command = runner_command.strip.downcase
+    formatted_runner_command.slice!("--runner=")
+    formatted_runner_command
+  end
+end
+
+def read_specified_protocol
+  protocol_command = ARGV.select { |arg| arg.include?("--protocol=") }.first
+  if protocol_command
+    formatted_protocol_command = protocol_command.strip.downcase
+    formatted_protocol_command.slice!("--protocol=")
+    if KrakenMobile::Constants::SUPPORTED_PROTOCOLS.include?(formatted_protocol_command)
+      formatted_protocol_command
+    else # Protocol not supported.
+      raise "Specified protocol not supported."
+    end
+  else # If protocol not specified use file based as default.
+    KrakenMobile::Constants::FILE_PROTOCOL
+  end
+end
+
+def read_configuration
+  configuration_command = ARGV.select { |arg| arg.include?("--configuration=") }.first
+  if configuration_command
+    configuration_command = configuration_command.strip.downcase
+    configuration_command.slice!("--configuration=")
+    configuration_command
+  end
+end
+
+def read_properties
+  properties_command = ARGV.select { |arg| arg.include?("--properties=") }.first
+  if properties_command
+    properties_command = properties_command.strip.downcase
+    properties_command.slice!("--properties=")
+    properties_command
+  end
+end
+
+#-------------------------------
+# Command reader
+#-------------------------------
+
+if ARGV.length == 0
+    print_usage
+else
+  cmd = ARGV.shift
+  case cmd
+    when 'version'
+      require 'kraken-mobile/version'
+      puts KrakenMobile::VERSION
+    when 'devices'
+      require 'kraken-mobile/helpers/devices_helper/manager'
+      print_devices
+    when 'setup'
+      kraken_setup
+    else
+      runner_command = read_specified_runner()
+      protocol = read_specified_protocol()
+      configuration = read_configuration()
+      properties = read_properties()
+      if runner_command
+          case runner_command
+            when KrakenMobile::Constants::CALABASH_ANDROID
+              require File.join(File.dirname(__FILE__), "kraken-mobile-calabash-android")
+              handle_calabash_android(cmd, protocol, configuration, properties)
+            else
+              raise "Specified runner not supported."
+          end
+      else # If runner not specified use calabash android as default.
+        require File.join(File.dirname(__FILE__), "kraken-mobile-calabash-android")
+        handle_calabash_android(cmd, protocol, configuration, properties)
+      end
+  end
+end

data/bin/kraken-mobile-calabash-android.rb

@@ -0,0 +1,85 @@
+
+#-------------------------------
+# Helpers
+#-------------------------------
+def ensure_apk_is_specified
+  if ARGV.empty? || !is_apk_file?(ARGV.first)
+    puts "The first parameter must be the path to a valid apk file."
+    exit 1
+  end
+end
+
+def ensure_configuration_is_valid configuration
+  if !File.exist?(configuration) || !File.file?(configuration) || !configuration.end_with?(".json")
+    puts "The path of the configuration file is not valid."
+    exit 1
+  end
+end
+
+def ensure_properties_is_valid properties
+  if !File.exist?(properties) || !File.file?(properties) || !properties.end_with?(".json")
+    puts "The path of the properties file is not valid."
+    exit 1
+  end
+end
+
+#-------------------------------
+# Command reader
+#-------------------------------
+
+@features_dir = File.join(FileUtils.pwd, "features")
+@support_dir = File.join(@features_dir, "support")
+@source_dir = File.join(File.dirname(__FILE__), '..', 'calabash-android-features-skeleton')
+
+def handle_calabash_android cmd, protocol, configuration, properties
+  case cmd
+    when 'gen'
+      require File.join(File.dirname(__FILE__), "kraken-mobile-generate")
+      kraken_scaffold()
+    when 'resign'
+      require 'calabash-android/helpers'
+      ensure_apk_is_specified
+      puts "Resigning APK with Calabash-Android"
+      resign_apk(File.expand_path(ARGV.first))
+    when 'monkey'
+      require 'kraken-mobile/constants'
+      require 'calabash-android/helpers'
+      options = {
+        runner: KrakenMobile::Constants::MONKEY,
+      }
+      if configuration
+        ensure_configuration_is_valid File.expand_path(configuration)
+        options[:config_path] = File.expand_path(configuration)
+      else
+        ensure_apk_is_specified
+        options[:apk_path] = ARGV.first
+      end
+      # NOT AVAILABLE
+      #kraken = KrakenMobile::App.new(options)
+      #kraken.run_in_parallel
+    when 'run'
+      require 'kraken-mobile/constants'
+      require 'calabash-android/helpers'
+      options = {
+        feature_folder: @features_dir,
+        runner: KrakenMobile::Constants::CALABASH_ANDROID,
+        protocol: protocol
+      }
+      if configuration
+        ensure_configuration_is_valid File.expand_path(configuration)
+        options[:config_path] = File.expand_path(configuration)
+      else
+        ensure_apk_is_specified
+        options[:apk_path] = ARGV.first
+      end
+      if properties
+        ensure_properties_is_valid File.expand_path(properties)
+        options[:properties_path] = File.expand_path(properties)
+      end
+      kraken = KrakenMobile::App.new(options)
+      kraken.run_in_parallel
+    else
+      puts "Invalid command '#{cmd}'"
+      print_usage
+  end
+end

data/bin/kraken-mobile-generate.rb

@@ -0,0 +1,19 @@
+def kraken_scaffold
+  if File.exists?(@features_dir)
+    puts "A features directory already exists. Stopping..."
+    exit 1
+  end
+  msg("Question") do
+    puts "I'm about to create a subdirectory called features."
+    puts "features will contain all your kraken tests."
+    puts "Please hit return to confirm that's what you want."
+  end
+  exit 2 unless STDIN.gets.chomp == ''
+
+  FileUtils.cp_r(@source_dir, @features_dir)
+
+  msg("Info") do
+    puts "features subdirectory created. \n"
+  end
+
+end

data/bin/kraken-mobile-helpers.rb

@@ -0,0 +1,48 @@
+require "rubygems"
+require 'fileutils'
+
+#-------------------------------
+# Helpers
+#-------------------------------
+
+def print_usage
+  puts <<EOF
+  Usage: kraken-mobile <command-name> [parameters] [options]
+  <command-name> can be one of
+    run <apk>
+      runs Cucumber in the current folder with the environment needed.
+    version
+      prints the gem version.
+    devices
+      prints the list of devices attached.
+    setup
+      creates kraken-settings file specifying in what devices the tests are going to be run.
+    gen
+      generate a features folder structure.
+    resign <apk>
+      resigns the app with the currently configured keystore.
+EOF
+end
+
+def print_devices
+  runner = KrakenMobile::Constants::CALABASH_ANDROID
+  device_manager = KrakenMobile::DevicesHelper::Manager.new({runner: runner})
+  puts "List of devices attached"
+  device_manager.connected_devices.each_with_index do |device, index|
+    puts "user#{index+1} - #{device.id} - #{device.model}"
+  end
+end
+
+def is_apk_file?(file_path)
+    file_path.end_with? ".apk" and File.exist? file_path
+end
+
+def relative_to_full_path(file_path)
+    File.expand_path(file_path)
+end
+
+def msg(title, &block)
+  puts "\n" + "-"*10 + title + "-"*10
+  block.call
+  puts "-"*10 + "-------" + "-"*10 + "\n"
+end

data/bin/kraken-mobile-setup.rb

@@ -0,0 +1,50 @@
+require "io/console"
+require "tty-prompt"
+
+def kraken_setup
+  prompt = TTY::Prompt.new
+  runner = KrakenMobile::Constants::CALABASH_ANDROID
+  device_manager = KrakenMobile::DevicesHelper::Manager.new({runner: runner})
+  @settings = []
+
+  devices_connected = device_manager.connected_devices
+  if devices_connected.count <= 0
+    puts "No devices connected"
+    exit 1
+  end
+  number_of_devices = -1
+  while(number_of_devices <= 0 || number_of_devices > devices_connected.count)
+    number_of_devices = prompt.ask("How many devices do you want to use?", convert: :int)
+    prompt.error("Number of devices can't be less than 1.") if number_of_devices <= 0
+    prompt.error("You only have #{devices_connected.count} devices connected.") if number_of_devices > devices_connected.count
+  end
+
+  devices_connected_id = devices_connected.map { |device| device.id }
+  for i in 0...number_of_devices
+    selected_device_id = prompt.select("Choose your user #{i+1}", devices_connected_id)
+    valid_apk = false
+    entered_apk_path = nil
+
+    while(!valid_apk)
+      entered_text = prompt.ask("What APK user #{i+1} is going to run?", required: true)
+      entered_apk_path = File.expand_path(entered_text)
+      valid_apk = is_apk_file?(File.expand_path(entered_apk_path))
+      prompt.error("APK path is not valid.") unless valid_apk
+    end
+
+    device = devices_connected.select { |d| d.id == selected_device_id }.first
+    @settings[i] = {
+      id: device.id,
+      model: device.model,
+      config: {
+        apk_path: entered_apk_path
+      }
+    }
+    devices_connected_id.delete(selected_device_id)
+  end
+
+  open('kraken_mobile_settings.json', 'w') do |f|
+    f.puts @settings.to_json
+  end
+  puts "Saved your settings to .kraken_mobile_settings. You can edit the settings manually or run this setup script again"
+end