protractor
Version:
Webdriver E2E test wrapper for Angular.
367 lines (292 loc) • 13 kB
Markdown
Setting up your Browser
=======================
Protractor is agnostic to how you set up your browser - it wraps WebDriverJS, so all browser setup for WebDriverJS applies. This doc serves as a collection for information surrounding how to set up browsers.
Configuring Browsers
--------------------
In your Protractor configuration file, all browser set up is done within the `capabilities` JSON object. This is passed directly to the WebDriver Builder.
See [the DesiredCapabilities Docs](https://code.google.com/p/selenium/wiki/DesiredCapabilities) for full information on which properties are available.
Switching to a browser besides Chrome
-------------------------------------
Simply set a different browser name in the capabilites object
```javascript
capabilities: {
'browserName': 'firefox'
}
```
You may need to install a separate binary to run another browser, such as IE or Android.
### Adding chrome-specific options
Chrome options are nested in the `chromeOptions` object. A full list of options is at [the chromedriver site](https://sites.google.com/a/chromium.org/chromedriver/capabilities). For example, to show an FPS counter in the upper right, your configuration would look like this:
```javascript
capabilities: {
'browserName': 'chrome',
'chromeOptions': {
'args': ['show-fps-counter=true']
}
},
```
If running with chromeOnly and chromeOptions together, chromeOptions.args and chromeOptions.extensions are required due to [Issue 6627](https://code.google.com/p/selenium/issues/detail?id=6627&thanks=6627&ts=1385488060) of selenium-webdriver currently(@2.37.0). So in order to avoid the issue, you may simply set them(or one of them) to an empty array.
Testing against multiple browsers
---------------------------------
If you would like to test against multiple browsers at once, use the multiCapabilities configuration option.
```javascript
multiCapabilities: [{
'browserName': 'firefox'
}, {
'browserName': 'chrome'
}]
```
Protractor will run tests in parallel against each set of capabilities. Please note that if multiCapabilities is defined, the runner will ignore the `capabilities` configuration.
Browser Support
---------------
Protractor uses webdriver, so protractor support for a particular browser is tied to the capabilities available in the Driver for that browser. Notably, Protractor requires the driver to implement asynchronous script execution.
| Driver | Support | Known Issues |
|------------------------|--------------|-----------------|
|ChromeDriver |Yes | |
|FirefoxDriver |Yes |[#480](https://github.com/angular/protractor/issues/480)|
|SafariDriver |Yes |[#481](https://github.com/angular/protractor/issues/481), SafariDriver does not support modals|
|IEDriver |Yes |IEDriver can be slow|
|OperaDriver |No | |
|ios-Driver |No | |
|Appium - iOS/Safari |Yes | drag and drop not supported (session/:sessionid/buttondown unimplemented) |
|Appium - Android/Chrome |Yes | |
|Selendroid |Yes | |
How to set up Protractor with Appium - Android/Chrome
-------------------------------------
###### Set up
* Install Java SDK (>1.6) and configure JAVA_HOME (Important: make sure it's not pointing to JRE).
* Follow http://spring.io/guides/gs/android/ to install and set up Android developer environment. Do not set up Android Virtual Device as instructed here
* From commandline, ```android avd``` and then install an AVD, taking note of the following
* Start with an ARM ABI
* Enable hardware keyboard: ```hw.keyboard=yes```
* Enable hardware battery: ```hw.battery=yes```
* Use the Host GPU
* Here's an example:
Phone:
```shell
> android list avd
Available Android Virtual Devices:
Name: LatestAndroid
Device: Nexus 5 (Google)
Path: /Users/hankduan/.android/avd/LatestAndroid.avd
Target: Android 4.4.2 (API level 19)
Tag/ABI: default/armeabi-v7a
Skin: HVGA
```
Tablet:
```shell
> android list avd
Available Android Virtual Devices:
Name: LatestTablet
Device: Nexus 10 (Google)
Path: /Users/hankduan/.android/avd/LatestTablet.avd
Target: Android 4.4.2 (API level 19)
Tag/ABI: default/armeabi-v7a
Skin: WXGA800-7in
```
* Follow http://ant.apache.org/manual/index.html to install ant and set up the environment
* Follow http://maven.apache.org/download.cgi to install mvn (Maven) and set up the environment.
* NOTE: Appium suggests installing Maven 3.0.5 (I haven't tried later versions, but 3.0.5 works for sure)
* Install Appium using node ```npm install -g appium```. Make sure you don't install as sudo or else Appium will complain
* You can do this either if you installed node without sudo, or you can chown the global node_modules lib and bin directories
* Start emulator manually (at least the first time) and unlock screen
```shell
> emulator -avd LatestAndroid
```
* Your devices should show up under adb now
```shell
> adb devices
List of devices attached
emulator-5554 device
```
* If the AVD does not have chrome (and it probably won't if it just created), you need to install it
* You can get v34.0.1847.114 from http://www.apk4fun.com/apk/1192/
* Once you download the apk, install to your AVD as such:
```shell
> adb install ~/Desktop/chrome-browser-google-34.0.1847.114-www.apk4fun.com.apk
2323 KB/s (30024100 bytes in 12.617s)
Success
```
* If you check your AVD now, it should have Chrome
###### Running test
* Ensure app is running if testing local app (Skip if testing public website)
```shell
> ./scripts/web-server.js
Starting express web server in /workspace/protractor/testapp on port 8000
```
* If your AVD isn't already started from the setup, start it now
```shell
> emulator -avd LatestAndroid
```
* Start Appium
```shell
> appium
info: Welcome to Appium v1.0.0-beta.1 (REV 6fcf54391fb06bb5fb03dfcf1582c84a1d9838b6)
info: Appium REST http interface listener started on 0.0.0.0:4723
info: socket.io started
```
*Note Appium listens to port 4723 instead of 4444*
* Configure protractor, i.e.
```javascript
exports.config = {
seleniumAddress: 'http://localhost:4723/wd/hub',
specs: [
'basic/*_spec.js'
],
chromeOnly: false,
capabilities: {
device: 'android',
'browserName': '',
//'deviceName' : 'emulator-5554',
'app' : 'chrome'
},
baseUrl: 'http://10.0.2.2:' + (process.env.HTTP_PORT || '8000'),
};
```
*note three things:*
-under capabilities: browserName is '', device is 'android', and app is 'chrome'
-baseUrl is 10.0.2.2 instead of localhost because it is used to access the localhost of the host machine in the android emulator
-selenium address is using port 4723
How to set up Protractor with Appium - iOS/Safari
-------------------------------------
###### Set up
* Install Java SDK (>1.6) and configure JAVA_HOME (Important: make sure it's not pointing to JRE).
* Follow http://ant.apache.org/manual/index.html to install ant and set up the environment
* Follow http://maven.apache.org/download.cgi to install mvn (Maven) and set up the environment.
* NOTE: Appium suggests installing Maven 3.0.5 (I haven't tried later versions, but 3.0.5 works for sure)
* Install Appium using node ```npm install -g appium```. Make sure you don't install as sudo or else Appium will complain
* You can do this either if you installed node without sudo, or you can chown the global node_modules lib and bin directories
###### Running test
* Ensure app is running if testing local app (Skip if testing public website)
```shell
> ./scripts/web-server.js
Starting express web server in /workspace/protractor/testapp on port 8000
```
* Start Appium
```shell
> appium
info: Welcome to Appium v1.0.0-beta.1 (REV 6fcf54391fb06bb5fb03dfcf1582c84a1d9838b6)
info: Appium REST http interface listener started on 0.0.0.0:4723
info: socket.io started
```
*Note Appium listens to port 4723 instead of 4444*
* Configure protractor, i.e.
iPhone:
```javascript
exports.config = {
seleniumAddress: 'http://localhost:4723/wd/hub',
specs: [
'basic/*_spec.js'
],
chromeOnly: false,
capabilities: {
browserName: '',
device: 'iPhone',
app: 'safari'
},
baseUrl: 'http://localhost:' + (process.env.HTTP_PORT || '8000')
};
```
iPad:
```javascript
exports.config = {
seleniumAddress: 'http://localhost:4723/wd/hub',
specs: [
'basic/*_spec.js'
],
chromeOnly: false,
capabilities: {
browserName: '',
device: 'iPad',
app: 'safari',
deviceName: 'iPad Simulator'
},
baseUrl: 'http://localhost:' + (process.env.HTTP_PORT || '8000')
};
```
*note three things:*
-note capabilities
-baseUrl is localhost (not 10.0.2.2)
-selenium address is using port 4723
How to set up Protractor with Selendroid
-------------------------------------
###### Set up
* Install Java SDK (>1.6) and configure JAVA_HOME (Important: make sure it's not pointing to JRE).
* Follow http://spring.io/guides/gs/android/ to install and set up Android developer environment. Do not set up Android Virtual Device as instructed here
* from commandline, 'android avd' and then follow Selendroid's recommendation (http://selendroid.io/setup.html#androidDevices). Take note of the emulator accelerator. Here's an example:
```shell
> android list avd
Available Android Virtual Devices:
Name: myAvd
Device: Nexus 5 (Google)
Path: /Users/hankduan/.android/avd/Hank.avd
Target: Android 4.4.2 (API level 19)
Tag/ABI: default/x86
Skin: WVGA800
```
###### Running test
* Ensure app is running if testing local app (Skip if testing public website)
```shell
> ./scripts/web-server.js
Starting express web server in /workspace/protractor/testapp on port 8000
```
* Start emulator manually (at least the first time)
```shell
> emulator -avd myAvd
HAX is working and emulator runs in fast virt mode
```
*note the last line that tells you the emulator accelerator is running*
* Start selendroid
```shell
> java -jar selendroid-standalone-0.9.0-with-dependencies.jar
...
```
* Once selendroid is started, you should be able to go to "http://localhost:4444/wd/hub/status" and see your device there, i.e.
```javascript
{"value":{"os":{"name":"Mac OS X","arch":"x86_64","version":"10.9.2"},"build":{"browserName":"selendroid","version":"0.9.0"},"supportedDevices":[{"emulator":true,"screenSize":"WVGA800","avdName":"Hank","androidTarget":"ANDROID19"}],"supportedApps":[{"mainActivity":"io.selendroid.androiddriver.WebViewActivity","appId":"io.selendroid.androiddriver:0.9.0","basePackage":"io.selendroid.androiddriver"}]},"status":0}
```
* Configure protractor, i.e.
```javascript
exports.config = {
seleniumAddress: 'http://localhost:4444/wd/hub',
specs: [
'basic/*_spec.js'
],
chromeOnly: false,
capabilities: {
'browserName': 'android'
},
baseUrl: 'http://10.0.2.2:' + (process.env.HTTP_PORT || '8000')
};
```
*note two things:*
-browserName is 'android'
-baseUrl is 10.0.2.2 instead of localhost because it is used to access the localhost of the host machine in the android emulator
PhantomJS
-------------------------------------
In order to test locally with [PhantomJS](http://phantomjs.org/), you'll need to either have it installed globally, or relative to your project. For global install see the [PhantomJS download page](http://phantomjs.org/download.html). For relative install run: `npm install --save-dev phantomjs`.
Add phantomjs to the driver capabilities, and include a path to the binary if using local installation:
```javascript
capabilities: {
'browserName': 'phantomjs',
/*
* Can be used to specify the phantomjs binary path.
* This can generally be ommitted if you installed phantomjs globally.
*/
'phantomjs.binary.path':'./node_modules/phantomjs/bin/phantomjs',
/*
* Command line arugments to pass to phantomjs.
* Can be ommitted if no arguments need to be passed.
* Acceptable cli arugments: https://github.com/ariya/phantomjs/wiki/API-Reference#wiki-command-line-options
*/
'phantomjs.cli.args':['--logfile=PATH', '--loglevel=DEBUG']
}
```
Appendix A: Using with the Protractor Library
---------------------------------------------
If you are not using the Protractor runner (for example, you're using Mocha) and you are setting up webdriver yourself, you will need to create a capabilities object and pass it in to the webdriver builder. The `webdriver.Capabilities` namespace offers some preset options. See [the webdriver capabilities source](https://code.google.com/p/selenium/source/browse/javascript/webdriver/capabilities.js).
```javascript
driver = new webdriver.Builder().
usingServer('http://localhost:4444/wd/hub').
withCapabilities(webdriver.Capabilities.phantomjs()).
build();
```