-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathsetup.html.haml
303 lines (302 loc) · 16.8 KB
/
setup.html.haml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
---
layout: base
title: Getting started
author: Dominik Dary
---
.container-fluid
.row-fluid
.span3
#sidebar
%ul.nav.nav-tabs.nav-stacked
%li
%a{:href=>'#systemRequirements'} System Requirements
%li
%a{:href=>'#getAut'} Getting a test app
%li
%a{:href=>'#launchingSelendroid'} Launching selendroid
%li
%a{:href=>'#firstTest'} First Test
%li
%a{:href=>'#DesiredCapabilities'} Desired Capabilities
%li
%a{:href=>'#androidDevices'} Android Devices
.span9
%h1 Getting started with Selendroid
%p Selendroid is based on the Android instrumentation framework. Currently only the testing of one specific app is supported. Selendroid requires the following permission for your app:
%code
<uses-permission android:name="android.**permission.INTERNET"/>
%section#systemRequirements
%h2 System Requirements
%ol
%li Selendroid can be used on Mac, Linux and Windows.
%li <b>Java SDK</b> (minimum 1.6) must be installed and <em>JAVA_HOME</em> configured. IMPORTANT: If JAVA_HOME is pointing to a Java runtime environment, selendroid will produce errors because tools like the <em>jarsigner</em> are not available!</li>
%li Latest <a href="http://developer.android.com/sdk/index.html">Android-Sdk</a> must be installed and <em>ANDROID_HOME</em> set. If detailed instructions are needed, have a look at <a href="http://spring.io/guides/gs/android/">this guide</a>.
%li If you run selendroid on a 64bit Linux machine, please install:
%ol
%li <code>sudo dpkg --add-architecture i386</code>
%li <code>sudo apt-get update</code>
%li <code>sudo apt-get install libc6:i386 libncurses5:i386 libstdc++6:i386</code>
%li At least one Android virtual device must exist or an Android hardware device must be plugged in to the computer. For best practices about Android devices please read <a href="#androidDevices">this section</a>.
%section#getAut
%h2 Getting an application under test
%p Selendroid can be used to test already built apps. Those Android apps (apk file) must exist on the machine, where the <em>selendroid-standalone</em> server will be started. The reason for this is that a customized <em>selendroid-server</em> for the app under test (AUT) will be created. Both apps (selendroid-server and AUT) must be signed with the same certificate in order to install the apks on the device.
%p If you want to play around with selendroid, you can use our <em>selendroid-test-app</em> which we use to verify that actually selendroid works as expected. You can download this app <a href="#{site.selendroid_test_app_download_link}">here</a>.
%section#launchingSelendroid
%h2 Launching Selendroid
%p Download <a href="#{site.standalone_download_link}">selendroid-standalone.jar</a> and <em>cd</em> to the folder where you downloaded the jar, and run:
%pre
%code
java -jar selendroid-standalone-#{site.current_version}-with-dependencies.jar -app selendroid-test-app-#{site.current_version}.apk
%p Selendroid-standalone will start a http server on port 4444 and will scan all Android virtual devices (avd) that the user has created (~/.android/avd/). The Android target version and the screen size will be identified. If an emulator is running, it can be used since version <em>0.11.0</em>. Even an emulator that has been started manually after the selendroid-standalone got started can be used. If there are Android hardware devices plugged in, they will also be added to the device store.
%p You can check that the application(s) and the devices are recognized by opening a browser and navigating to: <a href="http://localhost:4444/wd/hub/status">http://localhost:4444/wd/hub/status</a>.
%p You should see a result similar to this:
%pre
%code.json
= preserve do
:escaped
{
status: 0,
value: {
"os": {
"name": "Android"
},
"build": {
"browserName": "selendroid",
"version": "#{site.current_version}"
},
"supportedApps": [{
"appId": "io.selendroid.testapp:#{site.current_version}",
"mainActivity": "io.selendroid.testapp.HomeScreenActivity",
"basePackage": "io.selendroid.testapp"
}],
"supportedDevices": [{
"screenSize": "320x480",
"targetPlatform": "ANDROID17",
"emulator": true,
"avdName": "latest"
}, {
"screenSize": "320x480",
"targetPlatform": "ANDROID16",
"emulator": true,
"avdName": "es"
}, {
"screenSize": "320x480",
"targetPlatform": "ANDROID10",
"emulator": true,
"avdName": "AVD_for_api10"
}]
}
%h3 Selendroid-Standalone command line parameters
%dl
%dt
:plain
-h, --help
%dd
Prints usage instructions to the terminal.
%dt
:plain
-port
%dd
Specify the port for selendroid-standalone to run on, the default is 4444.
%dt
:plain
-app, -aut
%dd
Specify the location of the application under test. Absolute path expected.
%dt
:plain
-timeoutEmulatorStart
%dd
Specify the timeout in milliseconds to start emulators, the default is 300000.
%dt
:plain
-emulatorPort
%dd
Specify the port number to start running emulators on.
%dt
:plain
-deviceScreenshot
%dd
This enables screenshots to be taken on the device instead of using the <em>ddmlib</em> library.
%dt
:plain
-selendroidServerPort
%dd
Specify the port the selendroid-standalone is using to communicate with instrumentation server, default is 8080.
%dt
:plain
-deviceLog
%dd
Specifies whether or not adb logging should be enabled for the device running the test.
%dt
:plain
-logLevel
%dd
Specifies the log level of selendroid. Available values are: ERROR, WARNING, INFO, DEBUG and VERBOSE. Default: ERROR
%dt
:plain
-keystore
%dd
Specify the file of the keystore to use.
%dt
:plain
-keystoreAlias
%dd
The alias of the keystore to be used
%dt
:plain
-keystorePassword
%dd
The password for the keystore to be used
%dt
:plain
-emulatorOptions
%dd
Specify the emulator options used for starting emulators: e.g. -no-audio.
%dt
:plain
-noWebviewApp
%dd
Specify if you don't want selendroid to auto-extract and have 'AndroidDriver' (webview only app) available.
%dt
:plain
-noClearData
%dd
Specify if user data should not be cleaned after the test session has ended.
%dt
:plain
-sessionTimeout
%dd
Specify the maximum session duration in seconds. Session will be forcefully terminated if it takes longer. Default is 30 minutes.
%dt
:plain
-serverStartTimeout
%dd
Maximum time in milliseconds to wait for the selendroid-server to come up on the device. Default: 20000
%dt
:plain
-keepAdbAlive
%dd
Specify and adb will not be terminated on server shutdown.
%dt
:plain
-hub
%dd
Specify to send a registration request to the given (Selenium grid hub) url. Example : http://localhost:4444/grid/register
%dt
:plain
-proxy
%dd
Specify the remote proxy to use on the grid. Example : io.selendroid.grid.SelendroidSessionProxy
%dt
:plain
-host
%dd
Specify host of the node. Ip address needs to be specified for registering to a grid hub (guessing can be wrong complex).
%dt
:plain
-folder
%dd
Specify an absolute path of a folder that will be monitored for new apps (.apk files) to sign and add to the app store. Can be ignored if not needed.
%section#firstTest
%h2 First Tests
%p Tests are written using the Selenium 2 client API. For Java we provide <em>selendroid-client</em> libraries that are used in the following example:
%pre
%code.java
= preserve do
:escaped
SelendroidCapabilities capa = new SelendroidCapabilities("io.selendroid.testapp:#{site.current_version}");
WebDriver driver = new SelendroidDriver(capa);
WebElement inputField = driver.findElement(By.id("my_text_field"));
Assert.assertEquals("true", inputField.getAttribute("enabled"));
inputField.sendKeys("Selendroid");
Assert.assertEquals("Selendroid", inputField.getText());
driver.quit();
%p If, for example, you prefer to write your tests in Python, the same test can be found <a href="https://github.com/selendroid/demoproject-selendroid/blob/master/src/main/python/FindElementTest.py">here</a>, and <a href="https://github.com/selendroid/demoproject-selendroid/blob/master/src/main/ruby/">here</a> in Ruby.
%p In order to create a new test session in the desired capabilities, the id of the app under test must be provided in the format: <code>io.selendroid.testapp:#{site.current_version}</code>. Please note, if the version is not specified in the id of the app under test then the latest version of the app will be automatically selected. Based on that information a matching Android device will be identified, otherwise the test session will throw an error and not start. Important: before filing a bug: please make sure the desired capabilities in your test match the <a href="http://localhost:4444/wd/hub/status">supported</a> apps and devices available.
%p After the found device has been initialized, a customized <em>selendroid-server</em> will be created and automatically installed on the device. The app under test will also be installed and the <em>selendroid-server</em> on the device will then be automatically started.
%p After the test session has been successfully initialized, the test commands such as 'find an element' and 'element interactions' are routed to this device. If the test session has ended, the emulator will stop automatically.
%h3#DesiredCapabilities Desired Capabilities (SelendroidCapabilities)
%h4 Mandatory properties
%p We recommend the use of <code>SelendroidCapabilities</code>. There you find convenient methods like:
%ul
%li <code>new SelendroidCapabilities( ... )</code>: This requests an app for the test session without any preference about emulator or hardware device.
%li <code>SelendroidCapabilities.emulator( ... )</code>: This requests an emulator and will fail the test session if no emulator is available.
%li <code>SelendroidCapabilities.device( ... )</code> This requests a hardware device and will fail the test session if no device is plugged in.
%li <code>SelendroidCapabilities.android( ... )</code> This starts a mobile web testing session.
%p The <code>SelendroidCapabilities</code> are only available for Java projects. For other programming languages use the following properties in the <em>DesiredCapabilities</em> of the Selenium client apis:
%h5 For testing native or hybrid apps:
%dl
%dt
aut
%dd
Specify the app id of the app under test (aut). E.g. <code>io.selendroid.testapp:#{site.current_version}</code>. If the version of the aut is not specified, then the latest version is assumed.
%h5 For testing Mobile Web:
%dl
%dt
browserName
%dd
Value must be <code>android</code> to start the 'Android driver webview app'.
%p Please note that either <code>aut</code> or <code>browserName</code> can be used for a test session.
%h4 Optional properties in the desired capabilities
%dl
%dt
emulator
%dd
If <code>True</code>, an emulator will be requested. If <code>False</code>, a hardware device will be requested.
%dt
platformVersion
%dd
Specify the Android target API version of the device. E.g. for KitKat it is: <code>19</code>
%dt
locale
%dd
Specify the locale of an emulator to be used in the test session. During the start the locale will be automatically configured. E.g. <code>de_CH</code>
%dt
screenSize
%dd
Specify the screen size of the device: e.g. <code>720x1280</code>
%dt
display
%dd
Specify the display number that is used to start the emulator on. Supported only in Linux platforms. E.g. <code>1</code>
%dt
preSessionAdbCommands
%dd
Specify a list of adb commands that will be executed on the target device before <em>selendroid-server</em> will be started. E.g. <code>shell setprop name selendroid</code>, please note that the adb command itself and the serial will be added by selendroid automatically.
%dt
model
%dd
Specify the model (e.g. <code>Nexus One</code>, <code>Nexus 7</code>, <code>Galaxy S3</code>) of an emulator when selecting a device.
%dt
apiTargetType
%dd
Specify the api library you need on your device. (e.g. <code>google</code>) if you need a device that has Google APIs.
%section#androidDevices
%h2 Devices
%p Selendroid supports testing on hardware devices as well as using Android emulators. In the capabilities the properties are used to find the device for the test execution. The supported properties in the capabilities are listed <a href="#DesiredCapabilities">here</a>.
%h3 Example for selecting a device
%p For running a test on the Android target platform 18 and on an emulator which is simulating a Nexus 7, the capabilities for the selendroid-test-app are:
%pre
%code.java
= preserve do
:escaped
SelendroidCapabilities capa = new SelendroidCapabilities("io.selendroid.testapp:0.8.0");
capa.setPlatformVersion(DeviceTargetPlatform.ANDROID18);
capa.setEmulator(true);
capa.setModel("Nexus 7");
%h3 Using Emulators
%p Selendroid can start and stop Android Virtual Devices (Avd). It cannot create new emulators, they must be created manually by the tester. After an emulator has been created, we recommend the first start be done manually in order to be sure everything works as expected.
%p When creating avds, please read the following configuration recommendations:
%ul
%li Whenever possible, use the Intel x86 ABI
%li Install <a href="http://software.intel.com/en-us/android/articles/installation-instructions-for-intel-hardware-accelerated-execution-manager-windows">Intel x86 Emulator Accelerator</a> on Mac and Windows and use KVM on Linux to enable hardware acceleration to massively speed up the Emulator
%li Use at least 1024MB of RAM per emulator</li>
%li Use at least 32MB of VM Heap per emulator</li>
%li Configure the hardware keyboard to be used: <code>hw.keyboard=yes</code>
%li Use the Host GPU. If only a black screen is displayed, please deactivate this option.
%li The number of emulators you can run in parallel per machine depends heavily on the hardware of the machine you use.
%h3 Using Hardware Devices
%ul
%li Please make sure the device has no screen lock configured.
%li Devices must be plugged in via USB to the computer that the <em>selendroid-standalone</em> component is running on.