Skip to content

Commit c446f23

Browse files
ravelinx22ravelinx22
committed
2 parents 2e2d58c + 7228e4e commit c446f23

File tree

2 files changed

+114
-78
lines changed

2 files changed

+114
-78
lines changed

‎README.md‎

Lines changed: 114 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,203 @@
11
<p align="center">
2-
<img src="https://raw.githubusercontent.com/ravelinx22/KrakenMobile/master/reporter/assets/images/kraken.png" alt="kraken logo" width="140" height="193">
3-
</p>
2+
<img src="./reporter/assets/images/kraken.png" alt="kraken logo" width="140" height="193">
43

5-
<h3 align="center">Kraken Mobile</h3>
64

7-
<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>
5+
<h1 align="center">Kraken Mobile</h1>
86

9-
## Table of contents
7+
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 is 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.
108

11-
- [Technologies](#technologies)
12-
- [Installation](#installation)
13-
- [Signaling](#signaling)
14-
- [Writing your first test](#writing-your-first-test)
15-
- [Kraken steps](#kraken-steps)
16-
- [Running your tests](#running-your-tests)
17-
- [Kraken Settings](#kraken-settings)
18-
- [Properties file](#properties-file)
9+
**Kraken is partially supported by a Google Latin America Research Award (LARA) 2018**
1910

20-
## Technologies
11+
# Video
12+
[![krakenThumbnail](./reporter/assets/images/krakenThumbnail.jpg)](https://www.youtube.com/watch?v=hv5gFIpW3gM&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=1)
2113

22-
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.
14+
# Publications
2315

24-
## Installation
16+
- _"Kraken-Mobile: Cross-Device Interaction-based Testing of Android Apps"_, [William Ravelo-Méndez](https://ravelinx22.github.io/), [Camilo Escobar-Velásquez](https://caev03.github.io), and [Mario Linares-Vásquez](https://profesores.virtual.uniandes.edu.co/mlinaresv/en/inicio-en/), _Proceedings of the 35th IEEE International Conference on Software Maintenance and Evolution ([ICSME'19](https://icsme2019.github.io/))_, Tool Demo Track, Cleveland, OH, USA, September 30th - October 4th, 2019, to appear 4 pages (52% Acceptance Rate) [[pdf](https://thesoftwaredesignlab.github.io/KrakenMobile/assets/pdfs/icsme19.pdf)][[bibtex](https://thesoftwaredesignlab.github.io/KrakenMobile/assets/pdfs/icsme19.bib)]
2517

26-
### Prerequisites
18+
# Technologies
19+
20+
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.
2721

28-
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)
2922

23+
# Installation
3024

31-
Installing and managing a Gem is done through the gem command. To install Kraken's gem run the following command
25+
### Prerequisites
3226

33-
$ gem install kraken-mobile
27+
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.
3428

29+
```shell
30+
$ gem install kraken-mobile
31+
```
3532

36-
## Signaling
33+
# Signaling
3734

38-
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.
35+
Signaling is a protocol used for the communication of two or more devices running in parallel. It is 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.
3936

40-
## Writing your first test
37+
# Writing your first test
4138

4239
### Generate cucumber feature skeleton
4340

4441
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:
4542

46-
features
47-
|_support
48-
| |_app_installation_hooks.rb
49-
| |_app_life_cycle_hooks.rb
50-
| |_env.rb
51-
|_step_definitions
52-
| |_kraken_steps.rb
53-
|_my_first.feature
43+
```
44+
features
45+
|_support
46+
| |_app_installation_hooks.rb
47+
| |_app_life_cycle_hooks.rb
48+
| |_env.rb
49+
|_step_definitions
50+
| |_kraken_steps.rb
51+
|_my_first.feature
52+
```
5453

5554
### Write a test
5655

57-
The features goes in the features foler and should have the ".feature" extension.
58-
59-
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).
56+
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).
6057

6158
### Syntax
6259

63-
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`
60+
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`.
6461

65-
List of devices attached
66-
user1 - emulator-5554 - Android_SDK_built_for_x86
67-
user2 - emulator-5556 - Android_SDK_built_for_x86
62+
```shell
63+
List of devices attached
64+
user1 - emulator-5554 - Android_SDK_built_for_x86
65+
user2 - emulator-5556 - Android_SDK_built_for_x86
66+
```
6867

6968
After identifying what number each device has, you can write your test case giving each scenario the tag of a given device like so:
7069

71-
Feature: Example feature
72-
73-
@user1
74-
Scenario: As a first user I say hi to a second user
75-
Given I wait
76-
Then I send a signal to user 2 containing "hi"
70+
```Gherkin
71+
Feature: Example feature
72+
73+
@user1
74+
Scenario: As a first user I say hi to a second user
75+
Given I wait
76+
Then I send a signal to user 2 containing "hi"
7777
78-
@user2
79-
Scenario: As a second user I wait for user 1 to say hi
80-
Given I wait for a signal containing "hi"
81-
Then I wait
78+
@user2
79+
Scenario: As a second user I wait for user 1 to say hi
80+
Given I wait for a signal containing "hi"
81+
Then I wait
82+
```
8283

83-
## Kraken steps
84+
# Kraken steps
8485

8586
Kraken offers two main steps to help synchronizing your devices.
8687

8788
### Signaling steps
8889

8990
To wait for a signal coming from another device for 10 seconds that is Kraken default timeout use the following step.
90-
91-
Then /^I wait for a signal containing "([^\"]*)"$/
92-
91+
```
92+
Then /^I wait for a signal containing "([^\"]*)"$/
93+
```
9394
To wait for a signal coming from another device for an specified number of seconds use the following step
9495

95-
Then /^I wait for a signal containing "([^\"]*)" for (\d+) seconds$/
96+
```
97+
Then /^I wait for a signal containing "( [^\"]*)" for (\d+) seconds$/
98+
```
9699

97100
To send a signal to another specified device use the following step
98101

99-
Then /^I send a signal to user (\d+) containing "([^\"]*)"$/
102+
```
103+
Then /^I send a signal to user (\d+) containing "([^\"]*)"$/
104+
```
100105

101106
### Signaling functions
102107

103108
Kraken internal implementation of the signaling steps use the following functions.
104109

105-
#### readSignal(channel, content, timeout)
110+
```ruby
111+
readSignal(channel, content, timeout)
112+
```
106113

107114
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.
108115

109-
**Note: The channel parameter has to be the number of a device such as @user1, @user2, @userN**
116+
**Note: The channel parameter has to be the number of a device such as @user1, @user2, @userN**
110117

111-
#### writeSignal(channel, content)
118+
```ruby
119+
writeSignal(channel, content)
120+
```
112121

113122
Writes content to a channel passed by parameter.
114123

115124
**Note: The channel parameter has to be the number of a device such as @user1, @user2, @userN**
116125

117-
## Running your tests
126+
# Running your tests
118127

119128
To run your test:
120129

121-
kraken-mobile run <apk>
130+
```shell
131+
$ kraken-mobile run <apk>
132+
```
122133

123134
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).
124135

125-
## Kraken Settings
136+
# Kraken Settings
126137

127138
Kraken uses kraken_mobile_settings.json to specify in what devices the tests should be run.
128139

129140
### Generate settings file
130141

131142
The following command will show you the available connected devices or emulators and let you choose which ones you want to use.
132143

133-
kraken-mobile setup
144+
```shell
145+
$ kraken-mobile setup
146+
```
134147

135148
### Run tests with settings file
136149

137-
kraken-mobile run <apk> --configuration=<kraken_mobile_settings_path>
150+
``` shell
151+
$ kraken-mobile run <apk> --configuration=<kraken_mobile_settings_path>
152+
```
138153

139-
## Properties file
154+
# Properties file
140155

141156
Kraken uses properties files to store sensitive data such as passwords or api keys that should be used in your test cases.
142157

143158
### Generate properties file
144159

145-
The properties files should be a manually created json file with the following structure.
146-
147-
{
148-
"@user1": {
149-
"PASSWORD": "test"
150-
},
151-
"@user2": {
152-
"PASSWORD": "test2"
153-
}
154-
}
160+
The properties files should be a manually created JSON file with the following structure.
161+
162+
```json
163+
{
164+
"@user1": {
165+
"PASSWORD": "test"
166+
},
167+
"@user2": {
168+
"PASSWORD": "test2"
169+
}
170+
}
171+
```
155172

156173
### Use properties file in your test
157174

158175
You can use the specified properties using the following sintax.
159176

160-
@user1
161-
Scenario: As a kjkhdkjds
162-
Given I wait
163-
Then I see the text "<PASSWORD>"
177+
```Gherkin
178+
@user1
179+
Scenario: As a kjkhdkjds
180+
Given I wait
181+
Then I see the text "<PASSWORD>"
182+
```
164183

165184
### Run tests with settings file
166185

167-
kraken-mobile run <apk> --properties=<kraken_mobile_properties_path>
186+
```
187+
kraken-mobile run <apk> --properties=<kraken_mobile_properties_path>
188+
```
189+
190+
# Examples
191+
192+
| Application | Video | Feature File | Properties file | Settings File | Report Link |
193+
|:-------------|:-------------|:------------------|:-------|:-------|:-------|
194+
| Infinite Words | [video](https://www.youtube.com/watch?v=4lX7mO80w-4&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=3&t=0s)|[.feature](/examples/infinite-words/infinite_words.feature) | --- | --- | [report](/examples/infinite-words/report/index.html) |
195+
| QuizUp | [video](https://www.youtube.com/watch?v=2mhZVTK0r6k&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=4&t=1s) | [.feature](/examples/quizup/quizup.feature) | --- | --- | [report](/examples/quizup/report/index.html) |
196+
| Spotify/Shazam | [video](https://www.youtube.com/watch?v=7AKsfY1KFX0&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=5&t=0s) | [.feature](/examples/shazam/shazam.feature) | [.json](/examples/shazam/kraken_properties.json) | [.json](/examples/shazam/kraken_mobile_settings.json) | [report](/examples/shazam/report/index.html) |
197+
| Spunky | [video](https://www.youtube.com/watch?v=WOhRWkdFaVk&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=6&t=25s) | [.feature](/examples/spunky/spunky.feature) | --- | --- | [report](/examples/spunky/report/index.html) |
198+
| Picap | [video](https://www.youtube.com/watch?v=RozQrmH_Z5k&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=7&t=3s) | [.feature](/examples/picap/picap.feature) | [.json](/examples/picap/kraken_properties.json) | --- | [report](/examples/picap/report/index.html) |
199+
| AskFM | [video](https://www.youtube.com/watch?v=d9Gbdx8kFX8&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=8&t=0s) | [.feature](/examples/askfm/askfm.feature) | --- | --- | [report](/examples/askfm/report/index.html) |
200+
| Stick Men Fight | [video](https://www.youtube.com/watch?v=36OJKNj0nSo&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=9&t=4s) | [.feature](/examples/stick/stick.feature) | --- | --- | [report](/examples/stick/report/index.html) |
201+
| Tic Tac Toe | [video](https://www.youtube.com/watch?v=F9pDJDYsL_w&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=10&t=2s) | [.feature](/examples/tictactoe/tictactoe.feature) | --- | --- | [report](/examples/tictactoe/report/index.html) |
202+
| Tumblr | [video](https://www.youtube.com/watch?v=eqFej2uJz4k&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=11&t=3s) | [.feature](/examples/tumblr/tumblr.feature) | [.json](/examples/tumblr/kraken_properties.json) | --- | [report](/examples/tumblr/report/index.html) |
203+
| F3 | [video](https://www.youtube.com/watch?v=vESh6Jyp-so&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=12&t=0s) | [.feature](/examples/f3/f3.feature) | [.json](/examples/f3/kraken_properties.json) | --- | [report](/examples/f3/report/index.html) |

‎reporter/assets/images/krakenThumbnail.jpg‎

103 KB
Loading

0 commit comments

Comments
 (0)