Skip to content

Commit 3d81169

Browse files
caev03caev03
committed
update Readme
1 parent bc4ab1f commit 3d81169

File tree

2 files changed

+110
-80
lines changed

2 files changed

+110
-80
lines changed

‎README.md‎

Lines changed: 110 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -1,167 +1,197 @@
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+
<h2 align="center">Kraken Mobile</h2>
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+
# Video
10+
[![krakenThumbnail](./reporter/assets/images/krakenThumbnail.jpg)](https://www.youtube.com/watch?v=hv5gFIpW3gM&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=1)
1911

20-
## Technologies
12+
# Technologies
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+
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.
2315

24-
## Installation
25-
26-
### Prerequisites
27-
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)
2916

17+
# Installation
3018

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

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

23+
```shell
24+
$ gem install kraken-mobile
25+
```
3526

36-
## Signaling
27+
# Signaling
3728

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.
29+
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.
3930

40-
## Writing your first test
31+
# Writing your first test
4132

4233
### Generate cucumber feature skeleton
4334

4435
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:
4536

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
37+
```
38+
features
39+
|_support
40+
| |_app_installation_hooks.rb
41+
| |_app_life_cycle_hooks.rb
42+
| |_env.rb
43+
|_step_definitions
44+
| |_kraken_steps.rb
45+
|_my_first.feature
46+
```
5447

5548
### Write a test
5649

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).
50+
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).
6051

6152
### Syntax
6253

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`
54+
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`.
6455

65-
List of devices attached
66-
user1 - emulator-5554 - Android_SDK_built_for_x86
67-
user2 - emulator-5556 - Android_SDK_built_for_x86
56+
```shell
57+
List of devices attached
58+
user1 - emulator-5554 - Android_SDK_built_for_x86
59+
user2 - emulator-5556 - Android_SDK_built_for_x86
60+
```
6861

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

71-
Feature: Example feature
64+
```Gherkin
65+
Feature: Example feature
66+
67+
@user1
68+
Scenario: As a first user I say hi to a second user
69+
Given I wait
70+
Then I send a signal to user 2 containing "hi"
7271
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"
72+
@user2
73+
Scenario: As a second user I wait for user 1 to say hi
74+
Given I wait for a signal containing "hi"
75+
Then I wait
76+
```
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
82-
83-
## Kraken steps
78+
# Kraken steps
8479

8580
Kraken offers two main steps to help synchronizing your devices.
8681

8782
### Signaling steps
8883

8984
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-
85+
```
86+
Then /^I wait for a signal containing "([^\"]*)"$/
87+
```
9388
To wait for a signal coming from another device for an specified number of seconds use the following step
9489

95-
Then /^I wait for a signal containing "([^\"]*)" for (\d+) seconds$/
90+
```
91+
Then /^I wait for a signal containing "( [^\"]*)" for (\d+) seconds$/
92+
```
9693

9794
To send a signal to another specified device use the following step
9895

99-
Then /^I send a signal to user (\d+) containing "([^\"]*)"$/
96+
```
97+
Then /^I send a signal to user (\d+) containing "([^\"]*)"$/
98+
```
10099

101100
### Signaling functions
102101

103102
Kraken internal implementation of the signaling steps use the following functions.
104103

105-
#### readSignal(channel, content, timeout)
104+
```ruby
105+
readSignal(channel, content, timeout)
106+
```
106107

107108
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.
108109

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

111-
#### writeSignal(channel, content)
112+
```ruby
113+
writeSignal(channel, content)
114+
```
112115

113116
Writes content to a channel passed by parameter.
114117

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

117-
## Running your tests
120+
# Running your tests
118121

119122
To run your test:
120123

121-
kraken-mobile run <apk>
124+
```shell
125+
$ kraken-mobile run <apk>
126+
```
122127

123128
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).
124129

125-
## Kraken Settings
130+
# Kraken Settings
126131

127132
Kraken uses kraken_mobile_settings.json to specify in what devices the tests should be run.
128133

129134
### Generate settings file
130135

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

133-
kraken-mobile setup
138+
```shell
139+
$ kraken-mobile setup
140+
```
134141

135142
### Run tests with settings file
136143

137-
kraken-mobile run <apk> --configuration=<kraken_mobile_settings_path>
144+
``` shell
145+
$ kraken-mobile run <apk> --configuration=<kraken_mobile_settings_path>
146+
```
138147

139-
## Properties file
148+
# Properties file
140149

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

143152
### Generate properties file
144153

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-
}
154+
The properties files should be a manually created JSON file with the following structure.
155+
156+
```json
157+
{
158+
"@user1": {
159+
"PASSWORD": "test"
160+
},
161+
"@user2": {
162+
"PASSWORD": "test2"
163+
}
164+
}
165+
```
155166

156167
### Use properties file in your test
157168

158169
You can use the specified properties using the following sintax.
159170

160-
@user1
161-
Scenario: As a kjkhdkjds
162-
Given I wait
163-
Then I see the text "<PASSWORD>"
171+
```Gherkin
172+
@user1
173+
Scenario: As a kjkhdkjds
174+
Given I wait
175+
Then I see the text "<PASSWORD>"
176+
```
164177

165178
### Run tests with settings file
166179

167-
kraken-mobile run <apk> --properties=<kraken_mobile_properties_path>
180+
```
181+
kraken-mobile run <apk> --properties=<kraken_mobile_properties_path>
182+
```
183+
184+
# Examples
185+
186+
| Application | Video | Feature File | Properties file | Settings File | Report Link |
187+
|:-------------|:-------------|:------------------|:-------|:-------|:-------|
188+
| Infinite Words | [video](https://www.youtube.com/watch?v=MgIy9FA-cjk&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=2)|[.feature](/examples/infinite-words/infinite_words.feature) | --- | --- | [report](/examples/infinite-words/report/index.html) |
189+
| QuizUp | [video](https://www.youtube.com/watch?v=b0iA16KSk4k&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=3) | [.feature](/examples/quizup/quizup.feature) | --- | --- | [report](/examples/quizup/report/index.html) |
190+
| Spotify/Shazam | [video](https://www.youtube.com/watch?v=E0eZwDzrXRk&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=12&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) |
191+
| Spunky | [video](https://www.youtube.com/watch?v=cDcuETcGmz8&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=5) | [.feature](/examples/spunky/spunky.feature) | --- | --- | [report](/examples/spunky/report/index.html) |
192+
| Picap | [video](https://www.youtube.com/watch?v=u-0A-ZFTM2E&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=6) | [.feature](/examples/picap/picap.feature) | [.json](/examples/picap/kraken_properties.json) | --- | [report](/examples/picap/report/index.html) |
193+
| AskFM | [video](https://www.youtube.com/watch?v=QKYQnZxdDG4&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=7) | [.feature](/examples/askfm/askfm.feature) | --- | --- | [report](/examples/askfm/report/index.html) |
194+
| Stick Men Fight | [video](https://www.youtube.com/watch?v=7aeg4ry82bQ&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=8) | [.feature](/examples/stick/stick.feature) | --- | --- | [report](/examples/stick/report/index.html) |
195+
| Tic Tac Toe | [video](https://www.youtube.com/watch?v=YjRB9O0NFLc&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=9) | [.feature](/examples/tictactoe/tictactoe.feature) | --- | --- | [report](/examples/tictactoe/report/index.html) |
196+
| Tumblr | [video](https://www.youtube.com/watch?v=gITe0c7SW3o&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=10) | [.feature](/examples/tumblr/tumblr.feature) | [.json](/examples/tumblr/kraken_properties.json) | --- | [report](/examples/tumblr/report/index.html) |
197+
| F3 | [video](https://www.youtube.com/watch?v=Qx7ZYkTuFX4&list=PLF5U8kfVgRcJ3RCHt7cWmwlqN93brbVW-&index=11) | [.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)