diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..176a458f9 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto diff --git a/.gitignore b/.gitignore index b42b5795b..a1b39709a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,13 @@ node_modules/ selenium/ testapp/inbrowsertest/ -docs/build/ +website/bower_components/ +website/build/ +website/docgen/build/ chromedriver.log libpeerconnection.log -changes.sh xmloutput* npm-debug.log + +*.swp diff --git a/.jshintrc b/.jshintrc index 145034a7a..d87c2efaa 100644 --- a/.jshintrc +++ b/.jshintrc @@ -16,5 +16,7 @@ "loopfunc": true, "sub": true, "undef": true, - "quotmark": "single" + "quotmark": "single", + "evil": true, + "curly": true } diff --git a/.npmignore b/.npmignore index 038ccd490..93e651f1f 100644 --- a/.npmignore +++ b/.npmignore @@ -1,16 +1,19 @@ debugging/ +docs/ +scripts/ spec/ +stress/ selenium/ -debugging/ -testapp/inbrowsertest -docs/build +testapp/ +website/ +.gitattributes +.gitignore +.jshintrc .npmignore .travis.yml -changes.sh chromedriver.log libpeerconnection.log npm-debug.log -new.txt xmloutput* release.md diff --git a/.travis.yml b/.travis.yml index e8aab56fe..abd7a1aa0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,22 +1,41 @@ language: node_js +sudo: false node_js: - - "0.10" + - "4" + - "5" env: - matrix: - - JOB=smoke - - JOB=suite global: - SAUCE_USERNAME=angular-ci - SAUCE_ACCESS_KEY=9b988f434ff8-fbca-8aa4-4ae3-35442987 + - BROWSER_STACK_USERNAME=angularteam1 + - BROWSER_STACK_ACCESS_KEY=BWCd4SynLzdDcv8xtzsB - LOGS_DIR=/tmp/protractor-build/logs - BROWSER_PROVIDER_READY_FILE=/tmp/sauce-connect-ready + matrix: + - JOB=full + - JOB=smoke + - JOB=bstack + +matrix: + allow_failures: + - env: "JOB=smoke" + - env: "JOB=bstack" + exclude: + - env: JOB=smoke + node_js: "5" + - env: JOB=bstack + node_js: "5" + before_script: + - npm run pretest - mkdir -p $LOGS_DIR - - ./scripts/sauce_connect_setup.sh - - ./scripts/wait_for_browser_provider.sh + - ./scripts/travis_setup.sh script: - ./scripts/testserver.sh - - ./scripts/testonsauce.sh + - ./scripts/test_on_travis.sh + +after_script: + - ./scripts/print_logs.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 1097cee7d..7df632c2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,1576 @@ +# 3.0.0 + +_We're releasing version 3.0 with some breaking changes. In summary - Jasmine 1.3 is removed, only Jasmine 2 is now supported, old Node.JS support is dropped, and plugins now need to be explicitly required. Full details below._ + +## Dependency Version Upgrades + +- ([18e1f71](https://github.com/angular/protractor/commit/18e1f71a4dd868709f4e259e05a8a196921e22be)) + chore(webdriver): upgrade Protractor to webdriver 2.48.2 + +- ([1f44a6e](https://github.com/angular/protractor/commit/1f44a6ef3f7ae8680a03a3cc7a7c06f75a8c7d4c)) + chore(deps): bump chromedriver and iedriver versions IEDriver from 2.47.0 to 2.48.0 + + ChromeDriver from 2.19 to 2.20. Changelog: + http://chromedriver.storage.googleapis.com/2.20/notes.txt + +## Features + +- ([97e6703](https://github.com/angular/protractor/commit/97e6703eb0e7a5dffc1017d0a44f0dfeeb91f327)) + feat(protractor): Add protractor.prototype.restart + +- ([2007f06](https://github.com/angular/protractor/commit/2007f06078b6569a2cfd9f361f17d765c07bc7f8)) + feat(protractor): add flag to stop protractor from tracking $timeout + +- ([a40a4ba](https://github.com/angular/protractor/commit/a40a4ba2a509bc762f1f5937454fdbf074405f07)) + feat(ElementArrayFinder#get): Implemented ability to pass promise as index to + ElementArrayFinder#get + +- ([a54c0e0](https://github.com/angular/protractor/commit/a54c0e0d72b9d7d1d8364ade5046e5007ff53906)) + feat(plugins): Add config option to disable logging of warnings in console plugin + + Running tests in multiple browsers ends up printing out a lot of useless warnings I'm already + aware of. To make skimming through logs in the case of an actual failure easier, I want to be able + to disable the logging of warnings in the console plugin. + +- ([7015010](https://github.com/angular/protractor/commit/7015010188dfb70c1e49e4f2eae19d5ba1126b34)) + feat(driver providers): Add BrowserStack support. + + Also added BrowserStack to CI + +## Bug Fixes + +- ([7cba4ec](https://github.com/angular/protractor/commit/7cba4ecf0f3915dfec33dbc04decd42857744b37)) + fix(ng-repeat): properly detect the end of an ng-repeat-start block + + Discovered while investigating issue #2365 + +## Breaking Changes + +- ([2bde92b](https://github.com/angular/protractor/commit/2bde92b3e745e09ad3876932b2d187365e9aaa31)) + chore(jasmine): remove jasmine 1.3 + + and update docs. Also, use jasmine 2 for running all Protractor's unit tests. + + BREAKING CHANGE: Now, both jasmine and jasmine2 frameworks use jasmine 2.3. Users still using + jasmine version <2 will have to upgrade. + +- ([18e1f71](https://github.com/angular/protractor/commit/18e1f71a4dd868709f4e259e05a8a196921e22be)) + chore(webdriver): upgrade Protractor to webdriver 2.48.2 + + BREAKING CHANGE: 1) Users will no longer be able to use node versions <4. 2) There is significant + changes to the control flow, and tests may need to be + modified to be compliant with the new control flow. See + https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + +- ([ac1e21e](https://github.com/angular/protractor/commit/ac1e21e7e09a773de981bf9e70b0fcd489d17a83)) + chore(plugins): Split first party plugins into seperate repos + + BREAKING CHANGE: + + The Accessibility, NgHint, Timeline, and Console plugins are now located in their own separate + node modules. You will need to explicitly require each module you use. See https://github.com/angular/protractor/blob/master/docs/plugins.md#first-party-plugins for info for each module. + +- ([ddb8584](https://github.com/angular/protractor/commit/ddb8584a59343284904676ef6d8db5c1c996b900)) + chore(cucumber): Remove cucumber from internal implementation + + BREAKING CHANGE: + + Cucumber has been community maintained for a while, and in order to allow it to move faster, it is no longer part of the core Protractor library. It is now published on npm under `protractor-cucumber-framework` and will require setting `frameworkPath` in your configuration file. See https://github.com/angular/protractor/blob/master/docs/frameworks.md#using-cucumber for full instructions on use now. + + +# 2.5.1 +_This release is a hotfix for node 0.10 support_ + +- ([039ffa7](https://github.com/angular/protractor/commit/039ffa7bfa291084263ae3fa944bbf21394ce9a3)) + fix(configParser): Remove path.parse so protractor works with node < v0.12 + + Closes #2588 + +# 2.5.0 +_This release contains a hotfix for windows path issues and early support for Angular2 apps_ + + +## Features +- ([c5d37c2](https://github.com/angular/protractor/commit/c5d37c2abebf9aa9dd3324df93ac447529eea53b)) + feat(lib): add useAllAngularAppRoots option + + This allows waiting for all angular applications on the page, for angular2 apps only. + +- ([f246880](https://github.com/angular/protractor/commit/f24688030a63c9de4ce759ac9c6fab79ef773ed5)) + feat(lib): add support for waiting for angular2 + + Use Angular2's testability API, if present, when waiting for stability or loading a page. + + Closes #2396 + +## Bug Fixes + +- ([d6aebba](https://github.com/angular/protractor/commit/d6aebbad6e9b191fef141472887637ee4318438e)) + fix(config): Fixes absolute path parsing in windows + + This allows absolute paths absolute paths in to be properly parsed in windows. This should + maintain the line-number feature introduced in ff88e without breakage. + +- ([04e5bfb](https://github.com/angular/protractor/commit/04e5bfbfcade0cbbef58213bc7b227b5db753d57)) + chore(runner): make plugins optional param for createBrowser + + +# 2.4.0 + +_This release contains only a version update to `selenium-webdriver`, webdriver javascript bindings, and associated bug fixes._ + +## Dependency Version Upgrades +- ([9a202ab](https://github.com/angular/protractor/commit/9a202ab5573f24c9919639f1b75fd9cd2b383383)) + chore(dependencies): update selenium-webdriver to 2.47.0 + + Along with it, update `jasminewd2` to avoid situations where the control flow gets locked up and + hangs. + + *Potential Breaking Change*: + + This is passing all existing Protractor tests, but there is a possibility that the changes to the + control flow will cause some test flows to hang. If this causes issues, such as tests hanging or commands executing out of order, please revisit your use of functions affecting the control flow, such as `flow.execute`. + + See the selenium-webdriver changelog at https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + + +## Bug Fixes +- ([f034e01](https://github.com/angular/protractor/commit/f034e010156a85cf1826b95eb7f41f50ef5a1791)) + fix(synchronizing): use the same control flow when ignoring sync + + Previously, the order of frames and tasks on the control flow was different depending on + `browser.ignoreSynchronization`. This fixes the inconsistency by creating an empty task when + ignoreSynchronization is true. + + Practically, this fixes the polling spec failing after the update to selenium-webdriver@2.47.0. + + +# 2.3.0 + +_This release contains updates which fix some issues with dependencies that had gotten stale. However, it does not yet contain an update to the selenium-webdriver dependency, because of potential breaking changes. That update will be done in a separate Protractor@2.4.0 release. See [issue 2245](https://github.com/angular/protractor/issues/2245)._ + +## Dependency Version Upgrades + +- ([cfd8d00](https://github.com/angular/protractor/commit/cfd8d000c2aa1686c4a90164baf4e04976ee0587)) + feat(webdriver): update webdriver and chromedriver to latest version + + Updating Selenium standalone from 2.45.0 to 2.47.0 Updating ChromeDriver from 2.15 to 2.19 + Selenium Changelog: + https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + ChromeDriver Changelog: http://chromedriver.storage.googleapis.com/2.19/notes.txt + +- ([802b20f](https://github.com/angular/protractor/commit/802b20f153f2c201d8b37378bf8feb93f649a95f)) + chore(selenium): update selenium from 2.47.0 to 2.47.1 + +- ([7a7aca8](https://github.com/angular/protractor/commit/7a7aca8a264ae07cbbb90e7e7469533a52276488)) + chore(jasmine): bump jasmine version from 2.3.1 to 2.3.2 + +- ([eab828e](https://github.com/angular/protractor/commit/eab828e12c671cbf5cdf9b09df050cc59f0dd862)) + chore(travis): test against node 4 + + Test against node 4 on Travis, and remove support for node 0.10. + +- ([96def81](https://github.com/angular/protractor/commit/96def81dc7d364e789fc290e97aee0f898648a10)) + chore(saucelabs): updated saucelabs dependency to 1.0.1 to support proxy + +## Features + +- ([c989a7e](https://github.com/angular/protractor/commit/c989a7eeed5a0a55d2fbd37dc7278a7967889852)) + feat(webdriver-manager): add --ie32 commandline option + + The new option allows to download the 32-bit version of the IE driver on a 64-bit system, as the + 64-bit version has been broken for over a year now (the sendKeys() function works very slowly on + it). + +- ([ff88e96](https://github.com/angular/protractor/commit/ff88e969d55585cc4267d75c12c0cafc78a01895)) + feat(cucumber): Allow cucumber tests containing line numbers + + example: + ```js + specs: [ + 'cucumber/lib.feature:7' + ] + ``` + +## Bug Fixes + +- ([1487e5a](https://github.com/angular/protractor/commit/1487e5abf69bc1540226502aacadc8b3b42b0092)) + fix(protractor.wrapDriver): allow browser instances to work even if they were not set up through + the runner + + Fixes #2456 + +- ([2ff7a07](https://github.com/angular/protractor/commit/2ff7a0771b6695dc49566ed81548b3fe2cebf11c)) + fix(Chrome Accessibility Plugin): resolving the location of AUDIT_FILE + +- ([f9b0a92](https://github.com/angular/protractor/commit/f9b0a92079b55384d4560fef9400bb473672ce9c)) + fix(debugger): Fix potential debugger lockups + +# 2.2.0 + +## Breaking Changes + +- If you use the plugin API, it has changed a lot. See + [`docs/plugins.md`](docs/plugins.md) for details. The good news is that it + is being taken out of beta, so it should be more stable in the future. + +## Dependency Version Upgrades + +- ([786ab05](https://github.com/angular/protractor/commit/786ab0541bff9b561b35dbbf0ffc1e9d4a788d10)) + chore(dependencies): update request to 2.57 + + Closes #2205 + +## Features + +- ([f2a11a7](https://github.com/angular/protractor/commit/f2a11a7369319edac0f1221a1c6ab0f9a2cc73eb)) + feat(plugins): Changed and expanded the plugin API + + * Changed the plugin API so that it is more uniform (see docs/plugins.md) + * Updated existing plugins to the new API + * Added the `onPageLoad` and `onPageSync` entry points for plugins for modifying `browser.get` + * Added the `waitForPromise` and `waitForCondition` entry points for plugins for modifying + `waitForAngular` + * Added tests + + This closes #2126 and helps out @andresdominguez + +- ([aded26b](https://github.com/angular/protractor/commit/aded26bc9ee6172d6f64361207f6a8b04da09b0d)) + feat(webdriver-manager): update download logic with streaming + + Also adds a content length check to make sure the downloaded binaries are the correct size. This + seems to fix up some unreliable download issues that we were previously having. + +- ([7aeebd6](https://github.com/angular/protractor/commit/7aeebd6543d89b7d8b9474bc45651b88c5c2d396)) + feat(plugins): reporting loaded plugins + +- ([6c10378](https://github.com/angular/protractor/commit/6c10378b9a4e7cae9ba491a63ae11f942c833100)) + feat(protractor): expose pending $http and $timeout on a timeout + + Now when a test times out while waiting for Angular to be stable, pending + $timeout and $http tasks will be reported to the console. + +## Bug Fixes + +- ([c30afdd](https://github.com/angular/protractor/commit/c30afddb80b6138fc5f648f70f2891067d8eeef4)) + fix(test): fixed tests under npm test + +- ([3508335](https://github.com/angular/protractor/commit/3508335199fee5dad74c66d9ee19b8bf448c2e62)) + fix(element): ElementArrayFinder.count was slow + + The bug fix for #1903 + (https://github.com/angular/protractor/commit/2a765c76e121de13ff86a279fe3f21cb15c17783) was + causing ElementArrayFinder.prototype.count to be slow because of the extranous checks that must be + performed. However, the checks could be delayed into the isPresent check, which will mitigate this + issue + + fixes(#2359) + +- ([b147033](https://github.com/angular/protractor/commit/b14703319c0d6bb6a69b76d0fd3732e2ea1fbebc)) + fix(by.exactRepeater): should split by "=" + + Closes #2335 + +- ([4c9886b](https://github.com/angular/protractor/commit/4c9886b410ea4d82098af322044a37908a112138)) + fix(Chrome Accessibility Plugin) No error context + + If your tests fail because of StaleElementReferenceError then there is no context about where this + is coming from. By having the failure be handled inside of the plugin then grunt can fail + gracefully. Additionally, this provides context about where the error originated from. + + Fixes #2331 + +- ([d15ccdc](https://github.com/angular/protractor/commit/d15ccdcf82bda29c803c3a5642896f16d7e4f938)) + fix(phantomJS): Reset URL cannot be a data url for PhantomJS + + When trying to use the lates version of Angular with PhantomJS we get a message complaining about + "Detected a page unload event". This was fixed in earlier versions of Angular, see issue #85, but + reappeared now. The problem is that using data urls to reset the page causes this issue, so we + have to do as we do with Safari and use "about:blank" instead + +- ([e6369ac](https://github.com/angular/protractor/commit/e6369ac973d58a17415ab1211050af26236c6105)) + docs(tutorial): use Jasmine v2 in the tutorial + +- ([e60dc0f](https://github.com/angular/protractor/commit/e60dc0ff4fc4a6d22e877d4182605913fae5d5cb)) + fix(browser.refresh): use timeout in milliseconds + + When invoked without arguments browser.refresh used a 10-millisecond timeout, wrongly documented + as seconds. It now delegates timeout handling to browser.get, which defaults to + DEFAULT_GET_PAGE_TIMEOUT (10 seconds). + +- ([0262268](https://github.com/angular/protractor/commit/0262268fa43b9eefac815d986740efa07bb15818)) + fix(cucumber): fix beforeFeature event handler call guard + + Fixes the run failures reported in https://github.com/cucumber/cucumber-js/issues/342. + +# 2.1.0 + +## Dependency Version Upgrades + +- ([25b1fa0](https://github.com/angular/protractor/commit/25b1fa052c195f6f56adcd3f5a116cb5eac238b0)) + feat(jasmine): update jasmine dependency to 2.3.1 + + Updated from 2.1.1. See Jasmine's changelog at + https://github.com/jasmine/jasmine/tree/master/release_notes + + Closes #1795. Closes #2094. Closes #1768. + +- ([25e3b86](https://github.com/angular/protractor/commit/25e3b8611f7333f0829aa3c315a0397891bbada7)) + chore(chromedrivier): Update chromedriver to 2.15 + +## Features + +- ([45341c9](https://github.com/angular/protractor/commit/45341c944bf60537849776c7f362ee0442b219e6)) + feat(explorer): allow element explorer to start as a server + + If element explorer is run with a port (i.e. --debuggerServerPort 1234), it will start up a server + that listens to command from the port instead of a repl that listens to process.stdin. + +- ([cf9a26f](https://github.com/angular/protractor/commit/cf9a26f1b4bdca7d928794d24738786be074619a)) + feat(plugins): allow plugins.postTest to know what test just ran + +- ([0f80696](https://github.com/angular/protractor/commit/0f806964324cbeb4bceb54c5bd82c639b9f99a49)) + feat(plugins): inline plugins + +- ([de49969](https://github.com/angular/protractor/commit/de499696eb88721cb073a195025ae48f59cbc905)) + feat(debugger): make element explorer work with node 0.12.0 + + Node has changed its debugger significantly in 0.12.0, and these changes are necessary to get it + to work now. + + Specifically here are the key points to take note: + + * Before, the process continues running after `process._debugProcess(pid);` is called, but now, + the process stops. + > To over come this, the call to `process._debugProcess(pid)` is moved from protractor into the + debugger client. Secondly, because the process stops after the call, we call `reqContinue` once + the debugger connection is established, so that protractor continues into the first break point + (for backwards compatibility, we added an extra empty webdriver command so that in earlier + versions of node, protractor doesn't go past the first break point from the reqContinue). + + * Before repl provides '(foobar\n)' when an user inputs 'foobar'. Now it is just 'foobar\n'. + > We will parse and strip away both the parenthesis and '\n' to support all versions of node. + + * Additionally (non-related to node 0.12.0), this change makes debugger processes fail fast if the + port is taken. + +- ([7b96db0](https://github.com/angular/protractor/commit/7b96db0ffb06608b12aa14765133cce42a0cad7f)) + feat(browser.get): Return a promise that handles errors in browser.get + +## Bug Fixes + +- ([815ff5d](https://github.com/angular/protractor/commit/815ff5d092c8dda88e2a1d4c5c80f66bf20892fa)) + fix(jasmine2): be consistent about passing assertions in output JSON + + See #2051 + +- ([e6e668c](https://github.com/angular/protractor/commit/e6e668c8d7353c8e797f730b30b996c6a6eb770f)) + chore(jasmine): update jasminewd2 to 0.0.4 + + This improves the control flow schedule messages for debugging and fixes an issue with the `this` + variable inside tests. See https://github.com/angular/jasminewd/issues/22 + +- ([e599cf3](https://github.com/angular/protractor/commit/e599cf301d1ff0fe705b2362fa6b4b17859ab8da)) + fix(taskscheduler): label sharded tasks with numbers instead of letters + + Letters run into a problem with a maximum of 26. See #2042 + +- ([fda3236](https://github.com/angular/protractor/commit/fda323664db65a5c8f1590b9841fcfa53d4ab8fd)) + fix(config): add sauceAgent property to protractor config + + Closes #2040 + +- ([fa699b8](https://github.com/angular/protractor/commit/fa699b8f1a6b807f2405d6829609797a9a3f8768)) + fix(debugger): fix 'getControlFlowText()' broken in webdriver 2.45 + +- ([b783dd8](https://github.com/angular/protractor/commit/b783dd865dfd16e5099a863d36d497499026b208)) + fix(browser): remove subsequent duplicate module + + browser.removeMockModule() misses next duplicate module because of iteration over an array it's + modifying. + +- ([e3d4ad1](https://github.com/angular/protractor/commit/e3d4ad164a04451fce3a57f06121355343c97f48)) + fix(stacktrace): remove jasmine2 specific stacktraces + +- ([3cded9b](https://github.com/angular/protractor/commit/3cded9b8da247dc69c78a6fa0e25fe70f6c0f801)) + fix(locators): escape query in byExactBinding + + See http://stackoverflow.com/q/3561711 + + Closes #1918 + +- ([e18d499](https://github.com/angular/protractor/commit/e18d4990878d70f77b29e8678eecbaab7c8cefb5)) + fix(cucumber): process no-snippets param for cucumber framework + +# 2.0.0 + +_Why is this change version 2.0? Protractor is following semver, and there's some breaking changes here._ + +## Dependency Version Upgrades + +- ([34f0eeb](https://github.com/angular/protractor/commit/34f0eebd7e73b10e9b990caa06b63b6fd22b2589)) + fix(element): update to selenium-webdriver@2.45.1 and remove element.then + + This change updates the version of WebDriverJS (selenium-webdriver node module) from 2.44 to + 2.45.1. See the full changelog at + https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + +- ([8976e75](https://github.com/angular/protractor/commit/8976e75dc1817817e6bd2dbb0b6cbc78d72035e9)) + chore(jasmine): bump version of jasminewd2 + +## Features + +- ([997937d](https://github.com/angular/protractor/commit/997937d189fb3a9fb51f1b2e4756981c8958ceba)) + feat(console plugin): Added new console plugin + +- ([ef6a09d](https://github.com/angular/protractor/commit/ef6a09d798fd04124224f6ca48eb64d13eb01eff)) + feat(webdriver-manager): allow a custom cdn for binaries + + Added a cdn value for each binary to be overrided by the cli argument + `alternate_cdn`. + +## Bug Fixes + +- ([fb92be6](https://github.com/angular/protractor/commit/fb92be6d588e7302989bd171a064739359bb3c74)) + fix(accessibility): improve output for long elements + + Instead of just printing the first N characters of the element's template, print the first and + last N/2. + + See #1854 + +- ([2a765c7](https://github.com/angular/protractor/commit/2a765c76e121de13ff86a279fe3f21cb15c17783)) + fix(element): return not present when an element disappears + +- ([8a3412e](https://github.com/angular/protractor/commit/8a3412e98614bb69978869b34b5b7243619f015d)) + fix(bug): by.buttonText() should not be effected by CSS style + + Closes issue #1904 + +- ([5d23280](https://github.com/angular/protractor/commit/5d232807f1e32a9a3ba5a5e4f07ace5d535fc3cd)) + fix(debugger): fix issue where output does not display circular dep and functions + +- ([ef0fbc0](https://github.com/angular/protractor/commit/ef0fbc096035bb01d136897ca463892ceca56b73)) + fix(debugger): expose require into debugger + +## Breaking Changes + +- ([34f0eeb](https://github.com/angular/protractor/commit/34f0eebd7e73b10e9b990caa06b63b6fd22b2589)) + fix(element): update to selenium-webdriver@2.45.1 and remove element.then + + This change updates the version of WebDriverJS (selenium-webdriver node module) from 2.44 to + 2.45.1. See the full changelog at + https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + + To enable the update and remove confusion, this removes the `element().then` function unless there + is an action result. This function is completely unnecessary, because it would always resolve to + itself, but the removal may cause breaking changes. + + Before: + ```js + element(by.css('foo')).then(function(el) { + return el.getText().then(...); + }); + ``` + + After: + ```js + element(by.css('foo')).getText().then(...); + ``` + + In other words, an ElementFinder is now no longer a promise until an action has been called. + + Before: + ```js + var el = element(by.css('foo')); + + protractor.promise.isPromise(el); // true + protractor.promise.isPromise(el.click()); // true + ``` + + After: + ```js + var el = element(by.css('foo')); + + protractor.promise.isPromise(el); // false + protractor.promise.isPromise(el.click()); // true + ``` + + Also, fixes `filter` and `map` to work with the new WebDriverJS. + +- ([3c04858](https://github.com/angular/protractor/commit/3c048585ac811726d6c6d493ed6d43f6a3570bee)) + chore(config): remove deprecated `chromeOnly` + + This has been replaced with `directConnect`. + +- Due to ([1159612](https://github.com/angular/protractor/commit/1159612ed76bb65612dbb2cc648e45928a251b10)) + + Due to changes in how scheduling works on the control flow, specs + in Jasmine1 will no longer wait for multiple commands scheduled in `onPrepare` + or in the global space of the test file. + + Before: + ```js + onPrepare: function() { + browser.driver.manage().window().maximize(); + + // This second command will not finish before the specs start. + browser.get('http://juliemr.github.io/protractor-demo'); + } + ``` + + To fix, return the last promise from onPrepare: + + After: + ```js + onPrepare: function() { + browser.driver.manage().window().maximize(); + return browser.get('http://juliemr.github.io/protractor-demo'); + } + ``` + +- Due to ([1159612](https://github.com/angular/protractor/commit/1159612ed76bb65612dbb2cc648e45928a251b10)) + + Due to changes in WebDriverJS, `wait` without a timeout will now default + to waiting for 0 ms instead of waiting indefinitely. + + Before: + ```js + browser.wait(fn); // would wait indefinitely + ``` + + After + ```js + browser.wait(fn, 8000) // to fix, add an explicit timeout + ``` + + This will be reverted in the [next version of WebDriverJS](https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md#v2460-dev). + + +# 1.8.0 + +## Dependency Version Upgrades + +- ([1159612](https://github.com/angular/protractor/commit/1159612ed76bb65612dbb2cc648e45928a251b10)) + fix(webdriver): bump selenium to 2.45.0 + + Bump the selenium standalone binary to 2.45.0. + + See https://code.google.com/p/selenium/source/browse/java/CHANGELOG for a full list of changes to + the selenium server. + + Closes #1734 + +## Features + +- ([54163dc](https://github.com/angular/protractor/commit/54163dcd22cee27cf16685fbb4d53a2712233d26)) + feat(a11yPlugin): plugin for integrating with Chrome Accessibility Developer Tools + + Also includes missing Angular map files. See plugins/accessibility/index.js for usage. + +- ([658902b](https://github.com/angular/protractor/commit/658902bd04bf809bde2751db79e93ae00de2f810)) + feat(plugins): add postTest hook for plugins + + Additionally, add some tests to make sure that plugins can fail properly. + + Closes #1842 + +- ([13d34c9](https://github.com/angular/protractor/commit/13d34c9192a06634827d89bf356bea33fea75747)) + feat(a11yPlugin): add support for Tenon.io + +- ([5f8cffd](https://github.com/angular/protractor/commit/5f8cffd95c50ab4e7949376425f10e13747eb922)) + feat(plugins): allow plugins to export a name for use in reporting + +## Bug Fixes + +- ([aabdd56](https://github.com/angular/protractor/commit/aabdd567ee62d0d48fad499ee5decbb5d7d6b939)) + fix(debugger): breakpoint isn't set properly for windows + +- ([361ae21](https://github.com/angular/protractor/commit/361ae21ee761eb78d1e2c9b2b7d270873a28ef81)) + fix(plugins): add a 'test' or 'fail' string to plugins + + Closes #1843 + +- ([847e739](https://github.com/angular/protractor/commit/847e73961e52caa1537df269589d9cfe6373b986)) + fix(webdriver-manager): unzipping ie driver should overwrite old version + +# 1.7.0 + +## Dependency Version Upgrades + +- ([2658865](https://github.com/angular/protractor/commit/2658865640d82617e69208cdb2263a2073a20156)) + feat(webdriver): bump chromedriver to 2.14 + + Chromedriver 2.14 contains support for accessing elements inside the shadow DOM. + +## Features + +- ([d220ecf](https://github.com/angular/protractor/commit/d220ecf5ebc7ba023eab728d4a684e978ff77c83)) + feat(locators): add by.deepCss selector for finding elements in the shadow dom + + Usage: + + ``` + element(by.deepCss('.foo')) + equivalent to 'element(by.css('* /deep/ .foo')) + ``` + +- ([324f69d](https://github.com/angular/protractor/commit/324f69d6aa7c23ad77f1d50e26e0a56bade40132)) + feat(locators): add by.exactRepeater + +- ([eb9d567](https://github.com/angular/protractor/commit/eb9d56755fa93401502e7608c7c3d0f16927c082)) + feat(frameworks): add support for custom frameworks + + Usage: + + ```js + exports.config = { + framework: 'custom', + frameworkPath: '/path/to/your/framework/index.js' + } + ``` + +- ([9bc1c53](https://github.com/angular/protractor/commit/9bc1c53e40161521b0c125a810f86235c974f100)) + feat(expectedConditions): add helper library for syncing with non-angular apps + + Usage: + + ```javascript + var EC = protractor.ExpectedConditions; + var button = $('#xyz'); + var isClickable = EC.elementToBeClickable(button); + + browser.get(URL); browser.wait(isClickable, 5000); //wait for an element to become clickable + button.click(); + ``` + + You can also customize the conditions: + + ```javascript + var urlChanged = function() { + return browser.getCurrentUrl().then(function(url) { + return url != 'http://www.angularjs.org'; + }); + }; + + // condition to wait for url to change, title to contain 'foo', and $('abc') element to contain text 'bar' + var condition = EC.and(urlChanged, EC.titleContains('foo'), + EC.textToBePresentInElement($('abc'), 'bar')); + $('navButton').click(); browser.wait(condition, 5000); //wait for condition to be true. + // do other things + ``` + +- ([fb099de](https://github.com/angular/protractor/commit/fb099dedf92a64732d88401dd1b0d4d30b22650d)) + feat(elementExplorer): Combine browser.pause with elementExplorer + + * reuse logic for browser.pause for elementExplorer + * introduce browser.enterRepl + * allow customization of driver for elementExplorer + * fix bug where repl cannot return an ElementFinder (related #1600) + + Closes #1314, #1315 + +- ([9def5e0](https://github.com/angular/protractor/commit/9def5e0e67e031949010fed4ed47178a534c99e8)) + feat(runner): add browser.getProcessedConfig method + + Now, instances of the `browser` object have a `getProcessedConfig` method which returns a promise + that resolves to the current Protractor configuration object for the current runner instance. This + means that if multiCapabilities are being used or tests are sharded, `getProcessedConfig` will + return an object with the `capabilities` and `specs` property specific to the current instance. + + Closes #1724 + +## Bug Fixes + +- ([ccb165d](https://github.com/angular/protractor/commit/ccb165d99b69e1ae66e4c1badd2f4e04f1481e75)) + fix(webdriver-manager): unzipping chromedriver should override old version + + See #1813 + +# 1.6.1 + +## Bug Fixes + +- ([92c5d17](https://github.com/angular/protractor/commit/92c5d17844a2b4dc56c483ab4a65e2bf631175f9)) + fix(element): test crashes when using certain locators with `fromWebElement_` + + Protractor crashes when one uses locators with findElementsOverride (i.e. any custom protractor + locator like by.binding/repeater/etc) in map/filter/then/each/reduce + +# 1.6.0 + +## Features + +- ([1e60a95](https://github.com/angular/protractor/commit/1e60a9504c883a95f3500eafa38e1fc11dc28c9b)) + feat(frameworks): add jasmine2 framework + + Jasmine2.x may now be used by setting `framework: jasmine2` in your config. + See https://github.com/angular/protractor/blob/master/docs/jasmine-upgrade.md + +- ([0b93003](https://github.com/angular/protractor/commit/0b930035905d1868225667de358222e51394f3ac)) + feat(jasmine2): add 'grep' option to jasmine2 + + Allow users to filter the specs that they want to run using simple string match. To use this + feature, either: 1) specify jasmineNodeOpts.grep in your conf.js file + or 2) via commandline like "protractor conf.js --grep='pattern to match'" + +- ([4368842](https://github.com/angular/protractor/commit/4368842da73d4ed501df21b61daf71951e59524b)) + feat(wddebugger): enable repl (with autocomplete) for browser.pause + + See https://github.com/angular/protractor/blob/master/docs/debugging.md for + usage. + +- ([9c9ed31](https://github.com/angular/protractor/commit/9c9ed31591f5a3c552222ad7feb1ecd650973902)) + feat(launcher): allow multicapabilities to take array of promises + + Enables adding `getMultiCapabilities: function(){}` to your configuration file. The function + returns either multiCapabilities or a promise of a multiCapabilities that is resolved after + `afterLaunch` and before driver set up. If this is specified, both capabilities and + multiCapabilities will be ignored. + + Also allows specifying `seleniumAddress` in the capabilities/multiCapabilities object, which will + override the global `seleniumAddress`. This allows you to use a different `seleniumAddress` per + capabilities. + + Breaking Changes: + `capabilities` can no longer be a promise. Use getMultiCapabilities if you need to return a + promise. + `seleniumAddress` can no longer be a promise. Likewise, use getMultiCapabilities. + +- ([1670384](https://github.com/angular/protractor/commit/167038499aacfd5def03472f9f548529b273e1e0)) + feat(runner): allow protractor to restart browser between tests + + Enables adding `restartBrowserBetweenTests: true` to your configuration file. Note that this will + slow down test suites considerably. Closes #1435 + +- ([56beb24](https://github.com/angular/protractor/commit/56beb24b9473ceedc491f3ca00fbce1bb9a18f29)) + feat(protractor): add browser.getRegisteredMockModules() + + Now `browser.getRegisteredMockModules()` returns a list of the functions or strings that have + been registered as mock modules. For troubleshooting. + + Closes #1434. + +- ([5a404c2](https://github.com/angular/protractor/commit/5a404c27326fdb130e5d4ac5c4704b4013c78853)) + feat(timeline): add timeline plugin + + This plugin gathers test timeline information from the protractor test process, the selenium + client logs (if available), and sauce labs (if available), and presents the output visually. This + improves understanding of where latency issues are in tests. See #674 + + Usage: + + Add the plugin to your configuration file: + + ```js + exports.config = { + plugins: [{ + path: 'node_modules/protractor/plugins/timeline/index.js', + + // Output json and html will go in this folder. + outdir: 'timelines', + + // Optional - if sauceUser and sauceKey are specified, logs from + // SauceLabs will also be parsed after test invocation. + sauceUser: 'Jane', + sauceKey: 'abcdefg' + }], + // other configuration settings + }; + ``` + +- ([a9d83f7](https://github.com/angular/protractor/commit/a9d83f7ebbce1be7f7f8c2986d1bfebccff1d6f3)) + feat(plugins): add postResults hook for plugins + + Allows plugins to include a postResults function, which will be called after webdriver has been + quit and the environment has been torn down. This step may not modify the contents of the test + results object. + +## Dependency Version Upgrades + +- ([2b4ac07](https://github.com/angular/protractor/commit/2b4ac07eaccafec2ad88c05747a75268a3529759)) + feat(webdriver): version bumps for chromedriver and supported browsers + + Chromedriver to 2.13. CI browser version bumps for Chrome 39 and Firefox 34. + + +## Bug Fixes + +- ([adf30ba](https://github.com/angular/protractor/commit/adf30ba701d2a1ec992912001723de19366bea57)) + fix(test): use a platform agnostic way to run minijasminenode + +- ([50ee0b4](https://github.com/angular/protractor/commit/50ee0b4d1a1b93cedf3d099d349b937b25ee9e79)) + fix(test): allow to run 'npm start' or 'npm test' from windows too + +- ([b28355d](https://github.com/angular/protractor/commit/b28355dabde4c507ac620b973104e98e96279f2a)) + fix(cucumber): emit on cucumber scenario instead of step + +- ([33dcd77](https://github.com/angular/protractor/commit/33dcd777fe34c6682b64bda0adc4f3595b03394b)) + fix(util): webdriver could deadlock + + when prepare scripts containing promises are wrapped in a flow.execute + +- ([a877268](https://github.com/angular/protractor/commit/a877268f35cb0df8f34f60b71ad7201fef58d189)) + fix(locators): ng-repeat-start should not return extra null element + +- ([d505249](https://github.com/angular/protractor/commit/d505249fff773d0eaee8b17435ab751be8fbefa6)) + fix(waitforangular): improve error messages when waitForAngular fails + + Previously, caught errors were being interpreted as an empty object, causing lots of errors such + as + 'Uncaught exception: Error while waiting for Protractor to sync with the page: {}' Now the error + message will be displayed, and a more useful custom message will be thrown if the variable + 'angular' is not present or the root element is not part of the ng-app. + + See #1474 + +## Breaking Changes + +- Due to ([9c9ed31](https://github.com/angular/protractor/commit/9c9ed31591f5a3c552222ad7feb1ecd650973902)) + feat(launcher): allow multicapabilities to take array of promises + + Breaking Changes: + `capabilities` can no longer be a promise. Use getMultiCapabilities if you need to return a + promise. + `seleniumAddress` can no longer be a promise. Likewise, use getMultiCapabilities. + + Why is this breaking change not causing a major version bump? This feature was + not fully supported previously and we worked with all known users when making + the change. + + +# 1.5.0 + +## Features + +- ([55a91ea](https://github.com/angular/protractor/commit/55a91ea137395891248db148df75dd6408c3b3a2)) + feat(launcher): reorganize launcher + add option to store test results as JSON + + You may now use `config.resultJsonOutputFile` to specify a location for + output. See docs/referenceConf.js for more usage. + +- ([6a88642](https://github.com/angular/protractor/commit/6a886425a11b28fce83b6eec1f52296c4f78b7f0)) + feat(plugins): basic tools for adding plugins + +- ([2572feb](https://github.com/angular/protractor/commit/2572febe2c607d459a21e2ba99a1dcece2083d2d)) + feat(plugin): ngHint plugin + + For information on usage, see `plugins/ngHintPlugin.js`. More documentation + on plugins will be added soon. + +- ([0bbfd2b](https://github.com/angular/protractor/commit/0bbfd2b6d38392938781d846ad37b5a0fd964004)) + feat(protractor/runner): allow multiple browser in test + + Closes https://github.com/angular/protractor/issues/381 + Usage: `browser.forkNewDriverInstance`. + +- ([8b5ae8b](https://github.com/angular/protractor/commit/8b5ae8ba3d2b3f1de75c0add91694e39e9c591a8)) + feat(troubleshoot): Add more information when the --troubleshoot flag is used + + Improve error messages and add debug info when + - the configuration file cannot be parsed + - a webdriver session cannot be started + - more than one element is found using `element` + + Unify format used for warnings and errors. + +## Bug Fixes + +- ([30023f2](https://github.com/angular/protractor/commit/30023f2689171bc4f51a173d9cfd62a18fe276c5)) + fix(runner): setTestPreparer does not work + + setTestPreparer would always set the testPrepare to config.onprepare during + `runner.run()`. This is breaking for code that relies on setTestPreparer directly. + +- ([47f12ba](https://github.com/angular/protractor/commit/47f12ba31754346062a1e1d20380346a1c7a0659)) + fix(clientsidescripts): make findByCssContainingText tolerate elements with no + textContent/innerText + +- ([6a9b87c](https://github.com/angular/protractor/commit/6a9b87cac9b85cde6ae464eafe4abbba27e4fe4f)) + fix(elementexplorer): eval always treat result as promise + +- ([289dbb9](https://github.com/angular/protractor/commit/289dbb91a0676add40c12bb85d134904c57dcefd)) + fix(util): properly handle exceptions from onPrepare and onExit + +- ([a132fac](https://github.com/angular/protractor/commit/a132fac0afed5dc5fe8e2663e5aa1c1a90586920)) + fix(jasmine): fix errors when iit was used + + Errors were due to Jasmine not calling reportSpecStarting when iit was used, but calling + reportSpecResults. + + Closes #1602 + +## Breaking Changes + +- ([0bbfd2b](https://github.com/angular/protractor/commit/0bbfd2b6d38392938781d846ad37b5a0fd964004)) + feat(protractor/runner): allow multiple browser in test + + `protractor.getInstance()` had been unused (replaced by global `browser` in v0.12.0) + and is now removed. + + Before: + ```js + var myBrowser2 = protractor.getInstance(); + ``` + + After: + ```js + // In normal tests, just use the exported global browser + var myBrowser2 = browser; + ``` + + If you are creating your own instance of the Protractor class, you may still + use `protractor.wrapDriver` as before. + + +# 1.4.0 + +## Features + +- ([adef9b2](https://github.com/angular/protractor/commit/adef9b208fcba2a9d60347bda38a3fe3fac6bf50)) + feat(runner): add a new method of getting browser drivers - directConnect + + directConnect as an option on the configuration will replace chromeOnly. Now, WebDriverJS allows + Firefox to be used directly as well, so directConnect will work for Chrome and Firefox, and throw + an error if another browser is used. + + This change deprecates but does not remove the chromeOnly option. + +- ([0626963](https://github.com/angular/protractor/commit/06269636f52f9b3a9c73beb6191ae89a7a376cfb)) + feat(config): Option to exclude test for specific capability + + Add the option to exclude spec files for a specific capability. This way you can ignore spec + files for one capability only. For example if the test is known to fail in the capability. + + Closes #1230 + +- ([710cad7](https://github.com/angular/protractor/commit/710cad7c5a2d838a0c4184defa1b7d4240f577f6)) + feat(runner/frameworks): Change interface contract of the protractor runner instance so that it + returns a promise instead of calling a callback function + +- ([50f44f4](https://github.com/angular/protractor/commit/50f44f430851cbd76dbb3a41d6071198f6f479a4)) + feat(protractor): add clone methods for ElementFinder and ElementArrayFinder + +- ([eedf50b](https://github.com/angular/protractor/commit/eedf50b48ca55f18e8555ce5aa64ad92b03887c8)) + feat(launcher): add beforeLaunch and afterLaunch + +- ([8dd60b7](https://github.com/angular/protractor/commit/8dd60b73a3013bd29213c8d281819da6e545c7ff)) + feat(protractor): wrap negative indices for ElementArrayFinder.get(i) + + Closes #1213 + +- ([be236e7](https://github.com/angular/protractor/commit/be236e7f44c5306df36b62bb21bb3ba940c86944)) + feat(debugging): use custom messages when executing scripts to improve stack traces + + Now, instead of asynchronous events during executeScript all being described as + `WebDriver.executeScript`, they have their own custom messages. The schedule shown when debugging + will be more informative. + +## Dependency Version Upgrades + +- ([889a5a7](https://github.com/angular/protractor/commit/889a5a70c1f980d09a615cf1e8ceaea33272ba8e)) + feat(webdriver): version bumps for webdriver, chromedriver, webdriverJS + + Upgrade to WebDriver 2.44.0 and ChromeDriver 2.12. + +## Bug Fixes + +- ([2fbaf52](https://github.com/angular/protractor/commit/2fbaf52fd59f03929e173ebf760a97de34bf91d4)) + fix(element): use the root element only to find the testability API, not scope searches + + In 9a8f45a a change was introduced which made Protractor's custom locators (by.binding, by.model, + etc) use config.rootElement as the root for all their searches. This meant that + config.rootElement was used both to specify how to get hold of Angular's injector as well as + where to begin searching for elements. This does not work for all cases, for example if a dialog + should be searched for elements but is a sibling, not a child, of ng-app. + + This reverts that change, and uses document as the parent for all searches. This is consistent + with the behavior of the native locators by.id, by.css, and friends, which do not scope their + search based on config.rootElement. + +- ([9db5327](https://github.com/angular/protractor/commit/9db5327e4ada7eb3caa271b394bcda0ba5e8fd62)) + fix(ElementFinder): ElementFinder should allow null as success handler. Passes the value to the + next in the chain. + +- ([0858280](https://github.com/angular/protractor/commit/0858280db156f924ef126c3aaeae6973b8d44067)) + fix(locators): by.cssContainingText now operates on pre-transformed text + + Previously, the implementation depended on the browser. Now, it will always operate on the text + before text-transform is applied. Closes #1217 + +- ([1a4eea4](https://github.com/angular/protractor/commit/1a4eea4eb89362822dc86be6904c1ddfba95661e)) + fix(elementexplorer): elementexplorer hangs when returning ElementFinder + +- ([f4e6b40](https://github.com/angular/protractor/commit/f4e6b40c597dc1c59dc7eccfe236abcc336a46a9)) + fix(runner): webdriver could get into lock when there is async promise + +- ([cf284b9](https://github.com/angular/protractor/commit/cf284b994fb6766c8ab34d0af9b4ccf8fd866bd1)) + fix(clientsidescripts): by.exactBinding not working because of regex typo + + Closes #1441 + +- ([9cc0f63](https://github.com/angular/protractor/commit/9cc0f6398146ed9bfc757c1efc05d1806bab1e16)) + fix(runner): gracefully shutdown browsers after test + +- ([86ead2c](https://github.com/angular/protractor/commit/86ead2c5a20d474e59c3b9796b5438dc2090a6ed)) + fix(webdriver-manager): Avoid incompatibility between request with callback and pipe. + +- ([7283fdf](https://github.com/angular/protractor/commit/7283fdfa1e4c69bcab6af8f28f8f1b77634a50fd)) + fix(launcher): exit code is always 100 for sharded and 1 for nonsharded tests + +# 1.3.1 + +## Bug Fixes + +- ([714e4e2](https://github.com/angular/protractor/commit/714e4e28ab90fb5dfeca4375a68469ef609e2722)) + fix(locators): fix regression passing root element to locator scripts + + Closes #1378 + +# 1.3.0 + +## Features + +- ([4f1fe68](https://github.com/angular/protractor/commit/4f1fe68882dedba662752e722b9e7b76bfed19b6)) + feat(runner): Allow onCleanup to accept a file + +- ([548f0c0](https://github.com/angular/protractor/commit/548f0c09748502cb6ae87e602db09e6df78df348)) + feat(webdriver): bump WebDriver to version 2.43 + +- ([466b383](https://github.com/angular/protractor/commit/466b3831569dc28c5fc2be31fbdf96574e57c3f0)) + feat(protractor): allow advanced features for ElementArrayFinder + + changed ElementFinder as a subset of an ElementArrayFinder. + + This enables actions on ElementArrayFinders, such as: + `element.all(by.css('.foo')).click()` + + The function `filter` now returns an ElementArrayFinder, so you may also do: + `element.all(by.css('.foo')).filter(filterFn).click()` + + or + + `element.all(by.css('.foo')).filter(filterFn).last().click()` + +- ([7bd2dde](https://github.com/angular/protractor/commit/7bd2dde0a6fca8c8481ad68d0683b4f411d611b9)) + chore(angular): upgrade angular to version 1.3. + + This change updates Protractor's test application from 1.2.9 to 1.3.0-r0. + + There is a significant behind-the-scenes change in the implementation of locating elements and + waiting for the page to be stable. If you are updating your application to Angular 1.3, you may + run into some changes you will need to make in your tests: + + - `by.binding` no longer allows using the surrounding `{{}}`. Previously, these + were optional. + Before: `var el = element(by.binding('{{foo}}'))` + After: `var el = element(by.binding('foo'))` + + - Prefixes `ng_` and `x-ng-` are no longer allowed for models. Use `ng-model`. + + - `by.repeater` cannot find elements by row and column which are not children + of the row. For example, if your template is + `
{{foo.name}}
` + Before: `var el = element(by.repeater('foo in foos').row(2).column('foo.name'))` + After: You may either enclose `{{foo.name}}` in a child element or simply use: + `var el = element(by.repeater('foo in foos').row(2))` + +- ([ee82f9e](https://github.com/angular/protractor/commit/ee82f9e3d0656b3c88f041f0115743352bc08941)) + feat(webdriver-manager): ignore ssl checks with --ignore_ssl option + + Allow ability to ignore SSL checks when downloading webdriver binaries. Usage: `webdriver-manager + update --ignore_ssl` + +## Bug Fixes + +- ([838f5a2](https://github.com/angular/protractor/commit/838f5a2b248b1539b7ece13a8ccb921eda08ee45)) + fix(element): isPresent should not throw on chained finders + + Now, `$('nonexistant').$('foo').isPresent()` will return false instead of throwing an error. This + change also adds tests that ensure that catching errors from promises works as expected. + +## Breaking Changes + +- ([f7c3c37](https://github.com/angular/protractor/commit/f7c3c370a239218f6143a4992b1fc4763f4cdd3d)) + feat(webdriver): update to WebDriverJS 2.43.5 + + Breaking Changes WebDriverJS has introduced changes in the way that Promises are handled in + version 2.43. See + https://github.com/SeleniumHQ/selenium/blob/master/javascript/node/selenium-webdriver/CHANGES.md + - `webdriver.WebElement` has now been split into `webdriver.WebElementPromise` + and `webdriver.WebElement` so that it does not resolve to itself. This change + should be largely transparent to users. + - `WebElement.toWireValue` has been removed. + + +# 1.2.0 + +## Features + +- ([830f511](https://github.com/angular/protractor/commit/830f51128d1ca6c8858c99617b2752172044a752)) + feat(protractor): allow file:// baseUrls + + Modified protractor to support testing node-webkit by using string concatenation vs url.resolve() + when the baseUrl begins with file:// + + Closes #1266. + +- ([71b9c97](https://github.com/angular/protractor/commit/71b9c97432316a8409c7c83e28a3b1eba2d83f25)) + feat(cucumber): process the Cucumber 'coffee' param + +## Bug Fixes + +- ([ade9a92](https://github.com/angular/protractor/commit/ade9a9277558a564e15e46266a82aeb43261d958)) + fix(webdriver-manager): always use https for downloading webdriver binaries + + This fixes issues with unzipping - see #1259 + +- ([9a8f45a](https://github.com/angular/protractor/commit/9a8f45af49633f1637c88960ba079d7d425ca72c)) + fix(locators): locators should use the root element provided in config + + Previously, locators used 'document' as the root for their search. After this change, they will + use the root element provided in the config file - + `config.rootElement`. This will make sure behavior is correct if there are multiple angular apps + on one page, and also enables the getTestability path, because that requires a root element under + an ng-app. + +# 1.1.1 +This is a minor release with no functional changes. It contains a couple +implementation switches that new versions of Angular will use. + +# 1.1.0 + +## Features + +- ([316961c](https://github.com/angular/protractor/commit/316961c6a5d7410d73a2784a9622b106008b0930)) + feat(runner/hosted): add support for promises for seleniumAddress and capabilities + + Change driverProviders/hosted to resolve promise values in configuration to allow async jobs in + setup. Specifically, seleniumAddress, capabilities, and multiCapabilities may be promises. + Primarily, this would be for a network call to acquire a selenium host or to start a proxy + server. + +- ([953faf7](https://github.com/angular/protractor/commit/953faf7ebee345f686bfedff61ebcb29c5170083)) + feat(runner): allow onPrepare functions to return a promise + + If onPrepare is a function which returns a promise (or a file which exports a promise), the test + runner will now wait for that promise to be fulfilled before starting tests. + +- ([6de2e32](https://github.com/angular/protractor/commit/6de2e32328fc30b43428973457db08f34b7c1839)) + feat(runner): Add support for async onCleanUp functions + + If the onCleanUp function returns a promise, the process will allow it to resolve before exiting. + This is useful for performing async operations like writing to a file or calling an API at the + end of a test run. + +- ([cd575ee](https://github.com/angular/protractor/commit/cd575ee3a4d8c0930db23ad66649bf0d665ce2d6)) + feat(sauce provider): allow for custom server addresses when running against SauceLabs. + + Use `config.sauceSeleniumAddress` to connect to a custom URL for Sauce Labs. + +- ([1b16c26](https://github.com/angular/protractor/commit/1b16c26ac143910d3f3e92a3db4ac6ab168a8544)) + feat(suites): allow more than one suite from the command line + + Allow a comma-separated list of suites be provided on the command line, like + `--suite=suite1,suite2` + +- ([25cf88c](https://github.com/angular/protractor/commit/25cf88c29449cef6b925d19ec9cd17671f1befc9)) + feat(ElementArrayFinder): keep a reference to the original locator + +## Bug Fixes + +- ([d15d35a](https://github.com/angular/protractor/commit/d15d35a82a5a267bb7ae9c675017f091901c019f)) + fix issue where ElementFinder.then does not return a promise + + See https://github.com/angular/protractor/issues/1152 + +- ([9e36584](https://github.com/angular/protractor/commit/9e365848820a9a56547e884592e5ea13ef8460ea)) + fix(webdriver-manager): removed ssl on chromedriver url for consistency + + Other URLs use http, make chromedriver use this as well. + +- ([0da1e0c](https://github.com/angular/protractor/commit/0da1e0c65ba7a2b55ad2f5a4582e229dd876f940)) + fix(protractor): add dummy isPending function + + See https://github.com/angular/protractor/issues/1021 + +- ([9814af1](https://github.com/angular/protractor/commit/9814af11f35973f0b4a3325fcd0d9e0d91233e61)) + fix issue where color formatting text is leaking + + See https://github.com/angular/protractor/issues/1131 + +- ([8f1b447](https://github.com/angular/protractor/commit/8f1b4472430ec2d24f102d284e807b073d17ad81)) + fix(launcher): fix issue where test passes on unexpected failures + + +# 1.0.0 + +No changes from rc6. + +# 1.0.0-rc6 + +## Dependency Version Upgrades + +- ([b6ab644](https://github.com/angular/protractor/commit/b6ab644dd8105d3f64e347342a0ae2ad2f0100fc)) + chore(jasminewd): update to version 1.0.4 + + This version contains a fix for too many timeout messages. + +## Bug Fixes + +- ([0c4a70e](https://github.com/angular/protractor/commit/0c4a70e0ffbbf4373dbd9f1ab29daabe9338d57b)) + fix(protractor) fix stack traces for WebElement errors + + When angular/protractor@3c0e727136ab3d397c1a9a2bb02692d0aeb9be40 refactored `element()` into the + ElementFinder object, the function lost some of its error handling. This removed references to + frames inside tests (`it()` blocks), making it hard to tell where the error was actually + occurring. + + This commit fixes these problems, showing full stack traces for WebElement errors. + +# 1.0.0-rc5 + +## Features + +- ([51a5e89](https://github.com/angular/protractor/commit/51a5e89f7dace45e61d8eab70e1ea6e9354d4de6)) + feat(config): allow setting the get page timeout globally from the config + + To change the timeout for how long a page is allowed to stall on `browser.get`, change + `getPageTimeout: timeout_in_millis` in the configuration. As before, you may also change the + timeout for one particular `get` call by using a second parameter: + `browser.get(url, timeout_in_sec)` + +## Bug Fixes + +- ([985ff27](https://github.com/angular/protractor/commit/985ff27c9a94cca83af8db5bf7e570d826b23838)) + fix(configParser): load new functions from configs + + Closes #1043 + +## Breaking Changes + +- ([51a5e89](https://github.com/angular/protractor/commit/51a5e89f7dace45e61d8eab70e1ea6e9354d4de6)) + feat(config): allow setting the get page timeout globally from the config + + This change contains a small breaking change for consistency. Previously, the second parameter to + `get` changed the timeout in seconds. Now, the units are milliseconds. This is consistent with + all the other timeouts, as well as base JavaScript functions like setTimeout. + + - before: `browser.get(url, 4)` + - after: `browser.get(url, 4000)` + +# 1.0.0-rc4 + +## Bug Fixes + +- ([ab1d0be](https://github.com/angular/protractor/commit/ab1d0be8cd83b37906b9b8750dd9d85d72)) + fix(navigation): fix using browser.get with safari driver + + SafariDriver fails with data urls - see #1049. Reverting to use about:blank for now. + +# 1.0.0-rc3 + +## Features + +- ([f0e7984](https://github.com/angular/protractor/commit/f0e7984cdd169df947142c1cff0bd1bc33ac995b)) + feat(launcher): append capability tag for all output + +## Bug Fixes + +- ([1198dde](https://github.com/angular/protractor/commit/1198ddef9e353383819fca3a40bdaba0db22f96f)) + fix(navigation): use empty html data urls for page resets instead of about:blank + + Except on internet explorer, which does not allow data urls. + + Closes #1023. + +# 1.0.0-rc2 + +## Dependency Version Updates + +- ([e10e1a4](https://github.com/angular/protractor/commit/e10e1a4a8ae5013982f00d209e6fab1ff2b1d2a1)) + chore(minijasminenode): update minijasminenode dependency to v1.1.0 + + This adds several options for the reporter, which can be included in protractor's + `config.jasmineNodeOpts` + ```js + // If true, output nothing to the terminal. Overrides other printing options. + silent: false, + // If true, print timestamps for failures + showTiming: true, + // Print failures in real time. + realtimeFailure: false + ``` + +- ([be0bb00](https://github.com/angular/protractor/commit/be0bb00db6f51e381e31e80c6808a202270ecb20)) + chore(jasminewd): update jasminewd to v1.0.3 + + This fixes extra logging when a timeout occurs. + +## Features + +- ([82c1d47](https://github.com/angular/protractor/commit/82c1d47462779688bb8c9ac74ba3a6ecfefb7775)) + feat(protractor): add iteration index to ElementArrayFinder.each + +- ([62bcf7e](https://github.com/angular/protractor/commit/62bcf7e1c84ed720bc17435c40e1f78c50ba194c)) + feat(webdriver-manager): minor proxy enhancements + + Added error handling for request - previously, any errors coming from the request module were + silently swallowed. + + Fixed error handling to remove empty files when a download fails for some reason. + + Also evaluating both uppercase and lowercase proxy variables. Many tools use proxy variables in + the form https_proxy, others use HTTPS_PROXY. + +## Bug Fixes + +- ([dbf7ab5](https://github.com/angular/protractor/commit/dbf7ab5fdf7832676f37328e2ad96b9097db3f62)) + fix(mocha): mocha globals should be re-wrapped for every new suite + + Closes #523, closes #962 + + +# 1.0.0-rc1 + +## Dependency Version Updates + +- ([0dc0421](https://github.com/angular/protractor/commit/0dc04217a6a5b772d42b1463c91d89beca7df258)) + chore(selenium): version bumps to selenium 2.42.2 + +## Features + +- ([6906c93](https://github.com/angular/protractor/commit/6906c9326a4a83d81a0d09bdc1446cccb579d699)) + feat(webdriver-manager): use proxy for webdriver-manager + +- ([7d90880](https://github.com/angular/protractor/commit/7d9088025c5a1c37428ea3f1cee3dc8d3793f79e)) + feat(locators): implement by.options + +- ([4e1cfe5](https://github.com/angular/protractor/commit/4e1cfe5ad0f22947d21b4ebecd7cd05e0319af1a)) + feature(launcher): aggregate failures at the end and output message from the launcher + +- ([ff3d5eb](https://github.com/angular/protractor/commit/ff3d5ebc071a8806259f5da20018f2d937409455)) + feat(locators): add toString() wrapper for this.message + +- ([c892c2a](https://github.com/angular/protractor/commit/c892c2a1a773cc24cc6565efe2db892776143104)) + feat(protractor): implement reduce and filter for ElementArrayFinder + + See https://github.com/angular/protractor/issues/877 + +- ([8920028](https://github.com/angular/protractor/commit/8920028f42e683dc45e18a6dd9386bd862548010)) + feat(pause): allow the user to specify a port to be used for debugging + + Using browser.pause(portNumber) will now start the debugger on the specified port number. + + Closes #956 + +## Bug Fixes + +- ([f9082d0](https://github.com/angular/protractor/commit/f9082d0460c7b6465d53c37f326a0f66412c21ce)) + fix(clientsidescripts): make exactBinding more exact + + See https://github.com/angular/protractor/issues/925 + +- ([6641c81](https://github.com/angular/protractor/commit/6641c8168d74914d4826c5968771a2aec8299833)) + fix(launcher): report summary when specs fail + +- ([36e0e0a](https://github.com/angular/protractor/commit/36e0e0aaf090b0c9b5450fa59ba2da4c4237442a)) + fix(protractor): allow exceptions from actions to be catchable + + See https://github.com/angular/protractor/issues/959 + +- ([e86eb72](https://github.com/angular/protractor/commit/e86eb726ad20737d463341afdb4c56b4d19ef414)) + fix(protractor): removing a mock module that was never added now is a noop + + It used to remove the last module - now is a noop. + + Closes #764 + +- ([bf26f76](https://github.com/angular/protractor/commit/bf26f76ba5dc99d02ea4cd7fc198dce410a9f58c)) + fix(locators): findind elements by text should trim whitespace + + WebDriver always trims whitespace from around the text of an element, so to be consistent we + should trim the text from button elements before doing a by.buttonText. + + Closes #903, Closes #904. + +- ([48798b0](https://github.com/angular/protractor/commit/48798b0a8ac1fc56d0cdd80e177d67fdf592069c)) + fix(elementexplorer): element.all hangs in interactive mode + +# 0.24.2 +_Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time._ + +## Bug Fixes + +- ([a43f983](https://github.com/angular/protractor/commit/a43f98391d36cead7378d1dd26f54248f39300b7)) + fix(protractor): make ElementFinder.then resolve to itself instead of null + +- ([31d42a3](https://github.com/angular/protractor/commit/31d42a3875c5b95893d8a20d00dc5365c289ff98)) + fix(protractor): throw index-out-of-bounds + + See https://github.com/angular/protractor/issues/915 + - to make error more specific instead of propagate later + +# 0.24.1 +_Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time._ + +## Bug Fixes + +- ([59af936](https://github.com/angular/protractor/commit/59af936e1ef6e21432f7876144554db145083d46)) + fix(locators): Missing information in warning/error messages + + Webdriver's built-in locators (such as `by.css()`) appeared as + 'undefined' in protractor's messages. + + For instance, if a locator matched multiple elements, protractor would print the following + message: 'warning: more than one element found for locator undefined- you may need to be more + specific'. + +- ([13373f5](https://github.com/angular/protractor/commit/13373f5de18690e1994b32e092105cfe3ad1753d)) + fix(launcher): output error messages when child processes exit with error + + Version 0.24.0 introduced a bug where child processes would error without outputting the error + message. Fix. See #902. + +- ([72668fe](https://github.com/angular/protractor/commit/72668fe5ebbdc8126ff16887814f763198128ab5)) + fix(cssShortcut): fix $$ global throwing error + +# 0.24.0 +_Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time._ + +## Features + +- ([7299155](https://github.com/angular/protractor/commit/729915554cfa440bda0eec8a1c4bf423f4089481)) + feat(sauceprovider): append spec filename to capabilities.name + +- ([f22456d](https://github.com/angular/protractor/commit/f22456d3cf0768a577371776d716b8888a74397d)) + refactor(jasminewd): use jasminewd from its own node module + + The Jasmine Webdriver Adapter is now its own npm module. The code has been moved to + http://www.github.com/angular/jasminewd. + + Remove the code from Protractor, and add a dependency on jasminewd@1.0.0. + +- ([f23565d](https://github.com/angular/protractor/commit/f23565d5db4fbb102cfec8311ce9dfaee52e9113)) + feat(protractor): new API allowAnimations(bool) on protractor elements. + +- ([876a3c0](https://github.com/angular/protractor/commit/876a3c04c07a9f8d97e1edca3ec1f76e51e1a310)) + feat(runner): support running dart2js spec files + + This commit supports running Dart2JS output in NodeJS. Officially, Dart2JS in supposed to only + generate code for running in a real webbrowser. With this patch, the dart2js code can also be + executed in NodeJS. + + Ref: + https://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/sdk/lib/js/dart2js/js_dart2js.dart?spec=svn32943&r=32943#487 + +- ([8d46e21](https://github.com/angular/protractor/commit/8d46e210b91ed1521f6692a2cf35f60740c0ace6)) + feat(runner): support sourcemaps in spec files + + This feature allows folks who are generating their spec files from a different language to see + stack traces that use the line numbers from their sources before translation. + + This commit introduces a dependency on the `source-map-support` library. + + For general information about sourcemaps, refer: + - http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/ + - https://github.com/evanw/node-source-map-support + - https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/view + +## Bug Fixes + +- ([56daa54](https://github.com/angular/protractor/commit/56daa54e2e269064bd44bc05ed0bbf2c44657ca8)) + fix(clientsidescripts): convert non-Error exceptions to Errors + + If any functions called by clientSideScripts throws a an exception that doesn't inherit from + `Error`, the stack trace is completely unhelpful and the message is just "unknown error."  This + commit wraps such errors into + `Error` instances so that we have meaningful stack traces and the correct exception message.  + (e.g. This is the common case when running dart2js code.  This commit gives us the Dart stack + trace and exception message.) + + In addition, I've pushed the construction of the string to install into the browser into + clientsidescripts.js. + +- ([00c6abe](https://github.com/angular/protractor/commit/00c6abef16c47868974eed8ad1a4c38494b2a504)) + fix(element): fix WebElement.$ using the incorrect By object + + Closes #852 + +- ([0500b2c](https://github.com/angular/protractor/commit/0500b2c3b2698fe41bedf694b92aad884f3b0d0e)) + fix(navigation): ignore unknown JS errors when looking for the URL + + This should address #841 + + Ignoring the error and trying again has worked for all of my test cases, and the error has never + occurred more than once in a row. + +- ([c8c85e0](https://github.com/angular/protractor/commit/c8c85e0d94d7a7211b000650f01af714663611ad)) + fix(locators): fix by.repeater finding all rows for IE + + Previously, element.all(by.repeater('foo in foos')) would find non-element nodes for + ng-repeat-start elements, which could cause IEDriver to fall over if the test tried to get text + from those nodes. + +## Breaking Changes + +- ([3c0e727](https://github.com/angular/protractor/commit/3c0e727136ab3d397c1a9a2bb02692d0aeb9be40)) + refactor(protractor): reorganize internal structure of elementFinder/webelement + + - Allow chaining of actions (i.e. `element(By.x).clear().sendKeys('abc')`) + - first(), last(), and get(index) are not executed immediately, allowing + them to be placed in page objects + - Rework the way that elementFinder and wrappedWebElement is represented + - Breaking changes: + - element.all is chained differently + ``` + Before: element(By.x).element.all(By.y) + Now: element(By.x).all(By.y) + + However, using element.all without chaining did not change, + i.e. `element.all(By.x)` + ``` + + - Changed the way for retrieving underlying webElements + ``` + Before: element(By.x).find(), element(By.x).findElement(By.y), + and element(By.x).findElements(By.y) + Now: element(By.x).getWebElement(), + element(By.x).element(By.y).getWebElement(), + and element(By.x).element(By.y).getWebElements(), + respectively + ``` + - browser.findElement returns a raw WebElement so $, $$, and + evaluate will no longer be available + +- ([fbfc72b](https://github.com/angular/protractor/commit/fbfc72bad15667990232bb9ff1da503e03d16230)) + feat(launcher): Add support for maxSession + + - add support for maxSession and capability-specific specs + - cleaned up launcher (refactored out taskScheduler.js) + - Breaking change: + - changed the config to shard test files; also sharding is specific to + capabilities now + ``` + Before: config.splitTestsBetweenCapabilities + Now: config.capabilities.shardTestFiles or config.multiCapabilities[index].shardTestFiles + ``` + +- ([9e5d9e4](https://github.com/angular/protractor/commit/9e5d9e4abb7d0928e6092a711fda527554994be7)) + feat(locators): remove deprecated locator APIs + + This is a **breaking change**. The following deprecated Locator APIs have been removed. + + - `by.input` + - `by.select` + - `by.selectedOption` + - `by.textarea` + + `input`, `select`, and `textarea` can be replaced by `by.model`. + + `element(by.selectedOption('foo'))` can be replaced by + `element(by.model('foo')).$('option:checked')` + # 0.23.1 _Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time._ @@ -307,7 +1880,7 @@ _Note: Major version 0 releases are for initial development, and backwards incom fix(jasminewd): include full pre-async-call stack trace in expectation failure message - ([b6df2cf](https://github.com/angular/protractor/commit/b6df2cfcfd35b31e2e473604b6df9add744c6c2d)) - fix(configParser): load coffee and typescript for child processes + fix(configParser): load coffee and LiveScript for child processes Without loading coffee in configParser.js, child processes which try and load a coffeescript config file do not have coffee registered with node's required, and child tests fail. @@ -375,7 +1948,7 @@ _Note: Major version 0 releases are for initial development, and backwards incom window.clientSideScripts.findInputs('username'); Also, any custom locators using addLocator will now break since the - arguments order has chnaged. To migrate the code follow the example below: + arguments order has changed. To migrate the code follow the example below: Before: @@ -811,7 +2384,7 @@ _Note: Major version 0 releases are for initial development, and backwards incom _Note: Major version 0 releases are for initial development, and backwards incompatible changes may be introduced at any time._ -This change introduces major syntax updates. Using the new syntax is recommeded, but the old version is still supported for now. Note also that the test application, docs, and example tests have been updated. +This change introduces major syntax updates. Using the new syntax is recommended, but the old version is still supported for now. Note also that the test application, docs, and example tests have been updated. ## Features @@ -932,7 +2505,7 @@ Adds better messages in the selenium server install script, and also makes the script output a 'start' executable which can be used to quickly start up the selenium standalone. *not yet windows friendly*. Closes #108. -- ([b32f5a5](https://github.com/angular/protractor/commit/b32f5a59169f1324271bd5abc09c17fcd9c4f249)) feat(config): add exmples for dealing with log-in +- ([b32f5a5](https://github.com/angular/protractor/commit/b32f5a59169f1324271bd5abc09c17fcd9c4f249)) feat(config): add examples for dealing with log-in Adds examples for how to log in when the login page is not written in Angular. New examples are in spec/login. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7560a028b..bce989178 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,25 +4,71 @@ Contributing Questions --------- -Please ask questions on [StackOverflow](http://stackoverflow.com/questions/tagged/protractor), -and read through the [FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md) -and issue archives. +Please first read through the [FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md). + +Please ask questions on [StackOverflow](http://stackoverflow.com/questions/tagged/protractor), [Google Group discussion list](https://groups.google.com/forum/?fromgroups#!forum/angular), or [Gitter](https://gitter.im/angular/protractor). + +Any questions posted to Protractor's Github Issues will be closed with this note: + +Please direct general support questions like this one to an appropriate support channel, see https://github.com/angular/protractor/blob/master/CONTRIBUTING.md#questions + +Thank you! Issues ------- +====== -If you have a bug or enhancement request, please file an issue. -Before submitting an issue, please search the issue archive, read the +If you have a bug or feature request, please file an issue. +Before submitting an issue, please search the issue archive to help reduce duplicates, and read the [FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md). -When submitting an issue, please include context from your test and -your application. If there's an error, please include the error text. +Try running with troubleshooting messages (`protractor --troubleshoot`) against your configuration to make sure that there is not an error with your setup. + +When submitting an issue, please include a reproducible case that we can actually run. Protractor has a test Angular application available at `http://www.protractortest.org/testapp` which you can use for the reproducible test case. If there's an error, please include the error text. Please format code and markup in your issue using [github markdown](https://help.github.com/articles/github-flavored-markdown). -Pull Requests -------------- +Contributing to Source Code (Pull Requests) +=========================================== + +Loosely, follow the [Angular contribution rules](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md). + + * If your PR changes any behavior or fixes an issue, it should have an associated test. + * New features should be general and as simple as possible. + * Breaking changes should be avoided if possible. + * All pull requests require review. No PR will be submitted without a comment from a team member stating LGTM (Looks good to me). + +Protractor specific rules +------------------------- + + * JavaScript style should generally follow the [Google JS style guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml). + * Wrap code at 80 chars. + * Document public methods with jsdoc. + * Be consistent with the code around you! + +Commit Messages +--------------- + +Please write meaningful commit messages - they are used to generate the changelog, so the commit message should tell a user everything they need to know about a commit. Protractor follows AngularJS's [commit message format](https://docs.google.com/a/google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.z8a3t6ehl060). + +In summary, this style is + + (): + + + +Where `` is one of [feat, fix, docs, style, refactor, test, chore] and +`` is a quick descriptor of the location of the change, such as cli, clientSideScripts, element. + +Testing your changes +-------------------- + +Test your changes on your machine by running `npm start` to start up the test application, +then `npm test` to run the test suite. This assumes you have a Selenium Server running +at localhost:4444. -Follow [these guidelines](https://github.com/angular/protractor/blob/master/docs/contributing.md). +When you submit a PR, tests will also be run on the Continuous Integration environment +through Travis. If your tests fail on Travis, take a look at the logs - if the failures +are known flakes in Internet Explorer or Safari you can ignore them, but otherwise +Travis should pass. diff --git a/LICENSE b/LICENSE index f92b4b0c1..4662726f9 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ The MIT License -Copyright (c) 2010-2014 Google, Inc. +Copyright (c) 2010-2015 Google, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 79e37d435..9683166ff 100644 --- a/README.md +++ b/README.md @@ -1,117 +1,58 @@ -Protractor [![Build Status](https://travis-ci.org/angular/protractor.png?branch=master)](https://travis-ci.org/angular/protractor) +Protractor [![Build Status](https://travis-ci.org/angular/protractor.png?branch=master)](https://travis-ci.org/angular/protractor) [![Join the chat at https://gitter.im/angular/protractor](https://badges.gitter.im/angular/protractor.svg)](https://gitter.im/angular/protractor) ========== -Protractor is an end to end test framework for [AngularJS](http://angularjs.org/) applications built on top of [WebDriverJS](https://code.google.com/p/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would. +[Protractor](http://angular.github.io/protractor) is an end-to-end test framework for [AngularJS](http://angularjs.org/) applications. Protractor is a [Node.js](http://nodejs.org/) program built on top of [WebDriverJS](https://github.com/SeleniumHQ/selenium/wiki/WebDriverJs). Protractor runs tests against your application running in a real browser, interacting with it as a user would. -Protractor can be run as a standalone binary, or included into your tests as a library. Use [Protractor as a library](https://github.com/angular/protractor/blob/master/docs/library-only.md) if you would like to manage WebDriver and your test setup yourself. +Compatibility +------------- -For more information - - [read the docs](https://github.com/angular/protractor/tree/master/docs/getting-started.md) - - [Read the FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md) - - See the [supported browsers](https://github.com/angular/protractor/tree/master/docs/browser-setup.md) - - [See the API](https://github.com/angular/protractor/blob/master/docs/api.md) +Protractor 3 is compatible with nodejs v4 and newer. -To run the sample tests ------------------------ +When using nodejs v0.12, use protractor 2 (`npm install -g protractor@2`). -Install protractor with. +Getting Started +--------------- - npm install -g protractor +The Protractor documentation for users is located in the [protractor/docs](https://github.com/angular/protractor/tree/master/docs) folder. -Start up a selenium server (See the appendix below for help with this). By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`. +To get set up and running quickly: + - The [Protractor Website](http://angular.github.io/protractor) + - Work through the [Tutorial](http://angular.github.io/protractor/#/tutorial) + - Take a look at the [Table of Contents](http://angular.github.io/protractor/#/toc) -The node module's example folder contains a simple test suite which runs against angularjs.org. Run with: +Once you are familiar with the tutorial, you’re ready to move on. To modify your environment, see the Protractor Setup docs. To start writing tests, see the Protractor Tests docs. - protractor example/conf.js +To better understand how Protractor works with the Selenium WebDriver and Selenium Server see the reference materials. -Using the Protractor runner ---------------------------- +Getting Help +------------ -The Protractor runner is a binary which accepts a config file. Install protractor with +Check the [Protractor FAQ](https://github.com/angular/protractor/blob/master/docs/faq.md) and read through the [Top 20 questions on StackOverflow](http://stackoverflow.com/questions/tagged/protractor?sort=votes&pageSize=20). - npm install -g protractor - # Run the line below to see command line options - protractor +Please ask usage and debugging questions on [StackOverflow](http://stackoverflow.com/questions/tagged/protractor) (use the ["protractor"](http://stackoverflow.com/questions/ask?tags=protractor) tag), the [Gitter](https://gitter.im/angular/protractor) chat room, or in the [Angular discussion group](https://groups.google.com/forum/?fromgroups#!forum/angular). (Please do not ask support questions here on Github.) -You will need a *configuration file* containing setup info and *test files* containing the actual test scripts. The config file specifies how the runner should start webdriver, where your test files are, and global setup options. The test files use Jasmine framework by default ([read about using mocha instead](https://github.com/angular/protractor/tree/master/docs/using-mocha.md)). -Create a configuration file - an example with detailed comments is shown in `node_modules/protractor/referenceConf.js`. Edit the configuration file to point to your test files. - -```javascript -// myConf.js -exports.config = { - seleniumAddress: 'http://localhost:4444/wd/hub', - specs: ['myTest.js', 'myTestFolder/*Test.js'] -} -``` - -The configuration file must specify a way to connect to webdriver. This can be - * `seleniumAddress`: The address of a running selenium server. - * `seleniumServerJar`: The location of the selenium standalone .jar file on your machine. Protractor will use this to start up the selenium server. - * `sauceUser` and `sauceKey`: The username and key for a [SauceLabs](http://www.saucelabs.com) account. Protractor will use this to run tests on SauceLabs. - If none of the above are specific, Protractor will try to start the standalone .jar from the default location in node_modules/protractor/selenium. - -The runner exposes global variables `browser`, `by` and `element`. Check out [getting started docs](https://github.com/angular/protractor/blob/master/docs/getting-started.md) to learn how to write a test. - -```javascript -// myTest.js -describe('angularjs homepage', function() { - it('should greet the named user', function() { - browser.get('http://www.angularjs.org'); - - element(by.model('yourName')).sendKeys('Julie'); - - var greeting = element(by.binding('yourName')); - - expect(greeting.getText()).toEqual('Hello Julie!'); - }); -}); -``` - -Run with - - protractor myConf.js - - -Cloning and running Protractor's own tests ------------------------------------------- -Clone the github repository. +For Contributors +---------------- +Clone the github repository: git clone https://github.com/angular/protractor.git cd protractor npm install + ./bin/webdriver-manager update + cd website + npm install + cd .. -Start up a selenium server. By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`. +Start up a selenium server. By default, the tests expect the selenium server to be running at `http://localhost:4444/wd/hub`. A selenium server can be started with `webdriver-manager`. -Protractor's test suite runs against the included testapp. Start that up with + bin/webdriver-manager start + +Protractor's test suite runs against the included test application. Start that up with npm start Then run the tests with npm test - - -Appendix A: Setting up a standalone selenium server ---------------------------------------------------- - -WebdriverJS does not natively include the selenium server - you must start a standalone selenium server. All you need is the latest [selenium-server-standalone.](http://selenium-release.storage.googleapis.com/index.html). To drive individual browsers, you may need to install separate driver binaries. - -To use with chrome browsers, [download chromedriver](http://chromedriver.storage.googleapis.com/index.html). -[More information about chromedriver](https://sites.google.com/a/chromium.org/chromedriver/) - -The `webdriver-manager` script is included in the npm package to manage downloads for you. To see the options, run - - npm install -g protractor - webdriver-manager - -Download and start the selenium server with - - webdriver-manager update - webdriver-manager start - -Note the [Java Development Kit (JDK)](http://www.oracle.com/technetwork/java/javase/downloads/index.html) is also required to run the webdriver. You may have to download and install it if your computer does not already have it. - -For alternate ways to download and start the selenium standalone, see -[the webdriver docs](http://docs.seleniumhq.org/docs/03_webdriver.jsp#running-standalone-selenium-server-for-use-with-remotedrivers). diff --git a/bin/elementexplorer.js b/bin/elementexplorer.js index ec7eeb712..a9a5a47b2 100755 --- a/bin/elementexplorer.js +++ b/bin/elementexplorer.js @@ -32,119 +32,15 @@ * Typing tab at a blank prompt will fill in a suggestion for finding * elements. */ - -var webdriver = require('selenium-webdriver'); -var protractor = require('../lib/protractor.js'); -var repl = require('repl'); -var util = require('util'); -var vm = require('vm'); - -var driver, browser; - -var INITIAL_SUGGESTIONS = [ - 'element(by.id(\'\'))', - 'element(by.css(\'\'))', - 'element(by.name(\'\'))', - 'element(by.binding(\'\'))', - 'element(by.xpath(\'\'))', - 'element(by.tagName(\'\'))', - 'element(by.className(\'\'))' -]; - -var list = function(locator) { - return browser.findElements(locator).then(function(arr) { - var found = []; - for (var i = 0; i < arr.length; ++i) { - arr[i].getText().then(function(text) { - found.push(text); - }); - } - return found; - }); -}; - -var flowEval = function(code, context, file, callback) { - - var vmErr, - result, - flow = webdriver.promise.controlFlow(); - - flow.execute(function() { - try { - result = vm.runInThisContext(code, file); - } catch (e) { - vmErr = e; - callback(vmErr, null); - } - if (vmErr && process.domain) { - process.domain.emit('error', vmErr); - process.domain.exit(); - } - return result; - }).then(function(res) { - if (!vmErr) { - callback(null, res); - } - }, function(err) { - callback('There was a webdriver error: ' + err.name + ' ' + err.message, - null); - }); -}; - -var startRepl = function() { - var flowRepl = repl.start({ - 'useGlobal': true, - 'eval': flowEval - }); - - var originalComplete = flowRepl.complete; - - flowRepl.complete = function(line, completeCallback) { - if (line == '') { - completeCallback(null, [INITIAL_SUGGESTIONS, '']); - } else { - originalComplete.apply(this, arguments); - } - }; - - flowRepl.on('exit', function() { - driver.quit(); - util.puts('Shutting down. Goodbye.'); - }); -}; - -var startUp = function() { - driver = new webdriver.Builder(). - usingServer('http://localhost:4444/wd/hub'). - withCapabilities({'browserName': 'chrome'}).build(); - - driver.getSession().then(function(session) { - driver.manage().timeouts().setScriptTimeout(11000); - - browser = protractor.wrapDriver(driver); - - // Set up globals to be available from the command line. - global.driver = driver; - global.protractor = protractor; - global.browser = browser; - global.$ = browser.$; - global.$$ = browser.$$; - global.element = browser.element; - global.by = global.By = protractor.By; - global.list = list; - - - util.puts('Type to see a list of locator strategies.'); - util.puts('Use the `list` helper function to find elements by strategy:'); - util.puts(' e.g., list(by.binding(\'\')) gets all bindings.'); - util.puts(''); - - var url = process.argv[2] || 'about:blank'; - util.puts('Getting page at: ' + url); - driver.get(url); - - startRepl(); - }); -}; - -startUp(); +console.log('Please use "protractor [configFile] [options] --elementExplorer"' + + ' for full functionality\n'); + +if (process.argv.length > 3) { + console.log('usage: elementexplorer.js [urL]'); + process.exit(1); +} else if (process.argv.length === 3) { + process.argv[2] = ('--baseUrl=' + process.argv[2]); +} + +process.argv.push('--elementExplorer'); +require('../lib/cli.js'); diff --git a/bin/webdriver-manager b/bin/webdriver-manager index af601e969..1a5dea1e6 100755 --- a/bin/webdriver-manager +++ b/bin/webdriver-manager @@ -2,6 +2,7 @@ var fs = require('fs'); var os = require('os'); +var url = require('url'); var request = require('request'); var http = require('http'); var path = require('path'); @@ -14,7 +15,7 @@ var childProcess = require('child_process'); */ var SELENIUM_DIR = path.resolve(__dirname, '../selenium'); -var versions = require('../package.json').webdriverVersions; +var versions = require('../config.json').webdriverVersions; /** * Get the major and minor version but ignore the patch (required for selenium @@ -30,8 +31,9 @@ var binaries = { isDefault: true, prefix: 'selenium-server-standalone', filename: 'selenium-server-standalone-' + versions.selenium + '.jar', + cdn: 'https://selenium-release.storage.googleapis.com/', url: function() { - return 'http://selenium-release.storage.googleapis.com/' + + return this.cdn + shortVersion(versions.selenium) + '/' + 'selenium-server-standalone-' + versions.selenium + '.jar'; } @@ -41,8 +43,9 @@ var binaries = { isDefault: true, prefix: 'chromedriver_', filename: 'chromedriver_' + versions.chromedriver + '.zip', + cdn: 'https://chromedriver.storage.googleapis.com/', url: function() { - var urlPrefix = 'https://chromedriver.storage.googleapis.com/' + + var urlPrefix = this.cdn + versions.chromedriver + '/chromedriver_'; if (os.type() == 'Darwin') { return urlPrefix + 'mac32.zip'; @@ -62,8 +65,9 @@ var binaries = { isDefault: false, prefix: 'IEDriverServer', filename: 'IEDriverServer_' + versions.iedriver + '.zip', + cdn: 'https://selenium-release.storage.googleapis.com/', url: function() { - var urlPrefix = 'http://selenium-release.storage.googleapis.com/' + + var urlPrefix = this.cdn + shortVersion(versions.iedriver) + '/IEDriverServer'; if (os.type() == 'Windows_NT') { if (os.arch() == 'x64') { @@ -73,10 +77,23 @@ var binaries = { } } } + }, + ie32: { + name: 'IEDriver-32bit', + isDefault: false, + prefix: 'IEDriverServer', + filename: 'IEDriverServer_' + versions.iedriver + '.zip', + cdn: 'https://selenium-release.storage.googleapis.com/', + url: function() { + var urlPrefix = this.cdn + + shortVersion(versions.iedriver) + '/IEDriverServer'; + if (os.type() == 'Windows_NT') { + return urlPrefix + '_Win32_' + versions.iedriver + '.zip'; + } + } } }; - var cli = optimist. usage('Usage: webdriver-manager \n' + 'Commands:\n' + @@ -85,10 +102,14 @@ var cli = optimist. ' status: list the current available drivers'). describe('out_dir', 'Location to output/expect '). default('out_dir', SELENIUM_DIR). - describe('seleniumPort', 'Optional port for the selenium standalone server'); + describe('seleniumPort', 'Optional port for the selenium standalone server'). + describe('ignore_ssl', 'Ignore SSL certificates').boolean('ignore_ssl'). + default('ignore_ssl', false). + describe('proxy', 'Proxy to use for the install or update command'). + describe('alternate_cdn', 'Alternate CDN to the binaries'); for (bin in binaries) { - cli.describe(bin, 'install or update ' + binaries[bin].name). + cli.describe(bin, 'Install or update ' + binaries[bin].name). boolean(bin). default(bin, binaries[bin].isDefault); } @@ -105,6 +126,17 @@ if (!fs.existsSync(argv.out_dir) || !fs.statSync(argv.out_dir).isDirectory()) { fs.mkdirSync(argv.out_dir); } +var resolveProxy = function(fileUrl) { + var protocol = url.parse(fileUrl).protocol; + if (argv.proxy) { + return argv.proxy; + } else if (protocol === 'https:') { + return process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy; + } else if (protocol === 'http:') { + return process.env.HTTP_PROXY || process.env.http_proxy; + } +}; + /** * Function to download file using HTTP.get. * TODO: look into using something instead of request here, to avoid the @@ -114,17 +146,44 @@ var httpGetFile = function(fileUrl, fileName, outputDir, callback) { console.log('downloading ' + fileUrl + '...'); var filePath = path.join(outputDir, fileName); var file = fs.createWriteStream(filePath); - var req = request(fileUrl); - req.on('response', function(res) { - if (res.statusCode !== 200) { - throw new Error('Got code ' + res.statusCode + ' from ' + fileUrl); - } - }); - req.on('data', function(data) { - file.write(data); - }); - req.on('end', function() { - file.end(function() { + var ignoreSSL = argv.ignore_ssl; + var contentLength = 0; + + if (ignoreSSL) { + console.log('Ignoring SSL certificate'); + } + + var options = { + url: fileUrl, + strictSSL: !ignoreSSL, + proxy: resolveProxy(fileUrl) + }; + + request(options) + .on('response', function(response) { + if (response.statusCode !== 200) { + fs.unlink(filePath); + console.error('Error: Got code ' + response.statusCode + ' from ' + fileUrl); + } + contentLength = response.headers['content-length']; + }) + .on('error', function(error) { + console.error('Error: Got error ' + error + ' from ' + fileUrl); + fs.unlink(filePath); + }) + .pipe(file); + + file.on('close', function() { + fs.stat(filePath, function(err, stats) { + if (err) { + console.error('Error: Got error ' + error + ' from ' + fileUrl); + } + if (stats.size != contentLength) { + console.error('Error: corrupt download for ' + fileName + + '. Please re-run webdriver-manager update'); + fs.unlink(filePath); + return; + } console.log(fileName + ' downloaded to ' + filePath); if (callback) { callback(filePath); @@ -190,12 +249,10 @@ var existingFiles = fs.readdirSync(argv.out_dir); for (name in binaries) { bin = binaries[name]; + bin.cdn = argv.alternate_cdn || bin.cdn; var exists = fs.existsSync(path.join(argv.out_dir, bin.filename)); - var outOfDateExists = false; - existingFiles.forEach(function(file) { - if (file.indexOf(bin.prefix) != -1 && file != bin.filename) { - outOfDateExists = true; - } + var outOfDateExists = existingFiles.some(function(file) { + return file.indexOf(bin.prefix) !== -1 && file !== bin.filename; }); bin.exists = exists; bin.outOfDateExists = outOfDateExists; @@ -216,7 +273,7 @@ switch (argv._[0]) { args.push('-Dwebdriver.chrome.driver=' + path.join(argv.out_dir, executableName('chromedriver'))); } - if (binaries.ie.exists) { + if (binaries.ie.exists || binaries.ie32.exists) { args.push('-Dwebdriver.ie.driver=' + path.join(argv.out_dir, executableName('IEDriverServer'))); } @@ -259,7 +316,7 @@ switch (argv._[0]) { // Expected contents of the zip: // mac/linux: chromedriver // windows: chromedriver.exe - zip.extractAllTo(argv.out_dir); + zip.extractAllTo(argv.out_dir, true); if (os.type() != 'Windows_NT') { fs.chmodSync(path.join(argv.out_dir, 'chromedriver'), 0755); } @@ -271,7 +328,16 @@ switch (argv._[0]) { var zip = new AdmZip(filename); // Expected contents of the zip: // IEDriverServer.exe - zip.extractAllTo(argv.out_dir); + zip.extractAllTo(argv.out_dir, true); + }); + } + if (argv.ie32) { + downloadIfNew(binaries.ie32, argv.out_dir, existingFiles, + function(filename) { + var zip = new AdmZip(filename); + // Expected contents of the zip: + // IEDriverServer.exe + zip.extractAllTo(argv.out_dir, true); }); } break; diff --git a/config.json b/config.json new file mode 100644 index 000000000..898633fc9 --- /dev/null +++ b/config.json @@ -0,0 +1,7 @@ +{ + "webdriverVersions": { + "selenium": "2.48.2", + "chromedriver": "2.20", + "iedriver": "2.48.0" + } +} diff --git a/debugging/failureConf.js b/debugging/failureConf.js index 5fac92312..f094378f6 100644 --- a/debugging/failureConf.js +++ b/debugging/failureConf.js @@ -1,4 +1,4 @@ -var env = require('../environment.js'); +var env = require('../spec/environment.js'); // Examples of tests to show how debugging works with Protractor. Tests // should be run against the testapp. @@ -8,18 +8,15 @@ exports.config = { // Spec patterns are relative to the current working directly when // protractor is called. specs: [ - 'failure_spec.js', + 'failure_spec.js' ], capabilities: env.capabilities, baseUrl: env.baseUrl, - // ----- Options to be passed to minijasminenode. + // ----- Options to be passed to jasmine. jasmineNodeOpts: { - onComplete: null, - isVerbose: false, - showColors: true, - includeStackTrace: true + showColors: true } }; diff --git a/debugging/failure_spec.js b/debugging/failure_spec.js index bba699429..85fd7f722 100644 --- a/debugging/failure_spec.js +++ b/debugging/failure_spec.js @@ -15,18 +15,18 @@ describe('modes of failure', function() { var nonExistant = element(by.binding('nopenopenope')).getText(); }); - it('should fail to click a hidden element', function () { + it('should fail to click a hidden element', function() { browser.get('index.html#/form'); - element(by.id("hiddenbutton")).click(); + element(by.id('hiddenbutton')).click(); }); it('should fail to use protractor on a non-Angular site', function() { browser.get('http://www.google.com'); }, 20000); - it('should fail within a promise', function () { + it('should fail within a promise', function() { browser.get('index.html#/form'); - var greeting = element(by.binding('{{greeting}}')); + var greeting = element(by.binding('greeting')); greeting.getText().then(function(text) { expect(text).toEqual('This is not what it equals'); @@ -36,7 +36,7 @@ describe('modes of failure', function() { it('should fail an assertion', function() { browser.get('index.html#/form'); - var greeting = element(by.binding('{{greeting}}')); + var greeting = element(by.binding('greeting')); expect(greeting.getText()).toEqual('This is not what it equals'); }); @@ -44,7 +44,7 @@ describe('modes of failure', function() { it('should fail comparing a promise to another promise', function() { browser.get('index.html#/form'); - var greeting = element(by.binding('{{greeting}}')); + var greeting = element(by.binding('greeting')); expect(greeting.getText()).toEqual(greeting.getAttribute('value')); }); diff --git a/debugging/timeoutConf.js b/debugging/timeoutConf.js index f4049ff3e..dc5e3fb32 100644 --- a/debugging/timeoutConf.js +++ b/debugging/timeoutConf.js @@ -1,4 +1,4 @@ -var env = require('../environment.js'); +var env = require('../spec/environment.js'); // Examples of tests to show how timeouts works with Protractor. Tests // should be run against the testapp. @@ -8,18 +8,15 @@ exports.config = { // Spec patterns are relative to the current working directly when // protractor is called. specs: [ - 'timeout_spec.js', + 'timeout_spec.js' ], capabilities: env.capabilities, baseUrl: env.baseUrl, - // ----- Options to be passed to minijasminenode. + // ----- Options to be passed to jasmine. jasmineNodeOpts: { - onComplete: null, - isVerbose: false, - showColors: true, - includeStackTrace: true + showColors: true } }; diff --git a/docs/api-overview.md b/docs/api-overview.md new file mode 100644 index 000000000..c270d0a52 --- /dev/null +++ b/docs/api-overview.md @@ -0,0 +1,92 @@ +Working with Spec and Config Files +================================== + +Protractor needs two files to run, the test or spec file, and the configuration file. + +Spec files +========== + +Protractor tests are written using the syntax of your test framework, for example [Jasmine](http://jasmine.github.io/), and the [Protractor API](/docs/api.md). + +Example Spec File +----------------- +This simple script ([example_spec.js](/example/example_spec.js)) tests the 'The Basics' example on the [angularjs.org](http://www.angularjs.org) homepage. + +```js +describe('angularjs homepage', function() { + it('should greet the named user', function() { + // Load the AngularJS homepage. + browser.get('http://www.angularjs.org'); + + // Find the element with ng-model matching 'yourName' - this will + // find the element - and then + // type 'Julie' into it. + element(by.model('yourName')).sendKeys('Julie'); + + // Find the element with binding matching 'yourName' - this will + // find the

Hello {{yourName}}!

element. + var greeting = element(by.binding('yourName')); + + // Assert that the text element has the expected value. + // Protractor patches 'expect' to understand promises. + + expect(greeting.getText()).toEqual('Hello Julie!'); + }); +}); +``` + +Global Variables +---------------- + +Protractor exports these global variables to your spec (test) file: + + - `browser` - A wrapper around an instance of WebDriver, used for navigation and page-wide information. The `browser.get` method loads a page. Protractor expects Angular to be present on a page, so it will throw an error if the page it is attempting to load does not contain the Angular library. (If you need to interact with a non-Angular page, you may access the wrapped webdriver instance directly with `browser.driver`). + + - `element` - A helper function for finding and interacting with DOM elements on the page you are testing. The `element` function searches for an element on the page. It requires one parameter, a locator strategy for locating the element. See [Using Locators](/docs/locators.md) for more information. See Protractor's findelements test suite ([elements_spec.js](/spec/basic/elements_spec.js)) for more examples. + + - `by` - A collection of element locator strategies. For example, elements can be found by CSS selector, by ID, or by the attribute they are bound to with ng-model. See [Using Locators](/docs/locators.md). + + - `protractor` - The Protractor namespace which wraps the WebDriver namespace. Contains static variables and classes, such as `protractor.Key` which enumerates the codes for special keyboard signals. + + +Config Files +============ + +The configuration file tells Protractor how to set up the Selenium Server, which tests to run, how to set up the browsers, and which test framework to use. The configuration file can also include one or more global settings. + +Example Config File +------------------- + +A simple configuration ([conf.js](https://github.com/angular/protractor/tree/master/example)) is shown below. +```js +// An example configuration file +exports.config = { + // The address of a running selenium server. + seleniumAddress: 'http://localhost:4444/wd/hub', + + // Capabilities to be passed to the webdriver instance. + capabilities: { + 'browserName': 'chrome' + }, + + // Spec patterns are relative to the configuration file location passed + // to protractor (in this example conf.js). + // They may include glob patterns. + specs: ['example-spec.js'], + + // Options to be passed to Jasmine-node. + jasmineNodeOpts: { + showColors: true, // Use colors in the command line report. + } +}; +``` + +Reference Config File +--------------------- + +The [reference config file](/docs/referenceConf.js) file provides explanations for all of the Protractor configuration options. Default settings include the standalone Selenium Server, the Chrome browser, and the Jasmine test framework. Additional information about various configuration options is available here: + + - [Setting Up the Selenium Server](/docs/server-setup.md) + - [Setting Up the Browser](/docs/browser-setup.md) + - [Choosing a Framework](/docs/frameworks.md) + - [Using Page Objects to Organize Tests](/docs/page-objects.md) diff --git a/docs/api.md b/docs/api.md index d330e1b34..5648cca88 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,3500 +1,4 @@ -Protractor API 0.22.0 +Protractor API ============== - - -##protractor - -* [element](#element) -* [elementFinder.find](#elementfinderfind) -* [elementFinder.isPresent](#elementfinderispresent) -* [elementFinder.locator](#elementfinderlocator) -* [elementFinder.element](#elementfinderelement) -* [elementFinder.$](#elementfinder) -* [element.all](#elementall) -* [elementArrayFinder.count](#elementarrayfindercount) -* [elementArrayFinder.get](#elementarrayfinderget) -* [elementArrayFinder.first](#elementarrayfinderfirst) -* [elementArrayFinder.last](#elementarrayfinderlast) -* [elementArrayFinder.each](#elementarrayfindereach) -* [elementArrayFinder.map](#elementarrayfindermap) -* [Protractor](#protractor) -* [Protractor.prototype.waitForAngular](#protractorprototypewaitforangular) -* [Protractor.prototype.wrapWebElement](#protractorprototypewrapwebelement) -* [element.$](#element) -* [element.findElement](#elementfindelement) -* [element.$$](#element) -* [element.findElements](#elementfindelements) -* [element.isElementPresent](#elementiselementpresent) -* [element.evaluate](#elementevaluate) -* [Protractor.prototype.findElement](#protractorprototypefindelement) -* [Protractor.prototype.findElements](#protractorprototypefindelements) -* [Protractor.prototype.isElementPresent](#protractorprototypeiselementpresent) -* [Protractor.prototype.addMockModule](#protractorprototypeaddmockmodule) -* [Protractor.prototype.clearMockModules](#protractorprototypeclearmockmodules) -* [Protractor.prototype.removeMockModule](#protractorprototyperemovemockmodule) -* [Protractor.prototype.get](#protractorprototypeget) -* [Protractor.prototype.refresh](#protractorprototyperefresh) -* [Protractor.prototype.navigate](#protractorprototypenavigate) -* [Protractor.prototype.setLocation](#protractorprototypesetlocation) -* [Protractor.prototype.getLocationAbsUrl](#protractorprototypegetlocationabsurl) -* [Protractor.prototype.debugger](#protractorprototypedebugger) -* [Protractor.prototype.pause](#protractorprototypepause) - -##locators - -* [ProtractorBy](#protractorby) -* [WebdriverBy.prototype](#webdriverbyprototype) -* [ProtractorBy.prototype.addLocator](#protractorbyprototypeaddlocator) -* [ProtractorBy.prototype.binding](#protractorbyprototypebinding) -* [ProtractorBy.prototype.exactBinding](#protractorbyprototypeexactbinding) -* [ProtractorBy.prototype.select](#protractorbyprototypeselect) -* [ProtractorBy.prototype.selectedOption](#protractorbyprototypeselectedoption) -* [ProtractorBy.prototype.input](#protractorbyprototypeinput) -* [ProtractorBy.prototype.model](#protractorbyprototypemodel) -* [ProtractorBy.prototype.buttonText](#protractorbyprototypebuttontext) -* [ProtractorBy.prototype.partialButtonText](#protractorbyprototypepartialbuttontext) -* [ProtractorBy.prototype.textarea](#protractorbyprototypetextarea) -* [ProtractorBy.prototype.repeater](#protractorbyprototyperepeater) -* [ProtractorBy.prototype.cssContainingText](#protractorbyprototypecsscontainingtext) - -##webdriver - -* [webdriver.WebDriver](#webdriverwebdriver) -* [webdriver.WebDriver.attachToSession](#webdriverwebdriverattachtosession) -* [webdriver.WebDriver.createSession](#webdriverwebdrivercreatesession) -* [webdriver.WebDriver.prototype.controlFlow](#webdriverwebdriverprototypecontrolflow) -* [webdriver.WebDriver.prototype.schedule](#webdriverwebdriverprototypeschedule) -* [webdriver.WebDriver.prototype.getSession](#webdriverwebdriverprototypegetsession) -* [webdriver.WebDriver.prototype.getCapabilities](#webdriverwebdriverprototypegetcapabilities) -* [webdriver.WebDriver.prototype.quit](#webdriverwebdriverprototypequit) -* [webdriver.WebDriver.prototype.actions](#webdriverwebdriverprototypeactions) -* [webdriver.WebDriver.prototype.executeScript](#webdriverwebdriverprototypeexecutescript) -* [webdriver.WebDriver.prototype.executeAsyncScript](#webdriverwebdriverprototypeexecuteasyncscript) -* [webdriver.WebDriver.prototype.call](#webdriverwebdriverprototypecall) -* [webdriver.WebDriver.prototype.wait](#webdriverwebdriverprototypewait) -* [webdriver.WebDriver.prototype.sleep](#webdriverwebdriverprototypesleep) -* [webdriver.WebDriver.prototype.getWindowHandle](#webdriverwebdriverprototypegetwindowhandle) -* [webdriver.WebDriver.prototype.getAllWindowHandles](#webdriverwebdriverprototypegetallwindowhandles) -* [webdriver.WebDriver.prototype.getPageSource](#webdriverwebdriverprototypegetpagesource) -* [webdriver.WebDriver.prototype.close](#webdriverwebdriverprototypeclose) -* [webdriver.WebDriver.prototype.get](#webdriverwebdriverprototypeget) -* [webdriver.WebDriver.prototype.getCurrentUrl](#webdriverwebdriverprototypegetcurrenturl) -* [webdriver.WebDriver.prototype.getTitle](#webdriverwebdriverprototypegettitle) -* [webdriver.WebDriver.prototype.findElement](#webdriverwebdriverprototypefindelement) -* [webdriver.WebDriver.prototype.isElementPresent](#webdriverwebdriverprototypeiselementpresent) -* [webdriver.WebDriver.prototype.findElements](#webdriverwebdriverprototypefindelements) -* [webdriver.WebDriver.prototype.takeScreenshot](#webdriverwebdriverprototypetakescreenshot) -* [webdriver.WebDriver.prototype.manage](#webdriverwebdriverprototypemanage) -* [webdriver.WebDriver.prototype.navigate](#webdriverwebdriverprototypenavigate) -* [webdriver.WebDriver.prototype.switchTo](#webdriverwebdriverprototypeswitchto) -* [webdriver.WebDriver.Navigation](#webdriverwebdrivernavigation) -* [webdriver.WebDriver.Navigation.prototype.to](#webdriverwebdrivernavigationprototypeto) -* [webdriver.WebDriver.Navigation.prototype.back](#webdriverwebdrivernavigationprototypeback) -* [webdriver.WebDriver.Navigation.prototype.forward](#webdriverwebdrivernavigationprototypeforward) -* [webdriver.WebDriver.Navigation.prototype.refresh](#webdriverwebdrivernavigationprototyperefresh) -* [webdriver.WebDriver.Options](#webdriverwebdriveroptions) -* [webdriver.WebDriver.Options.prototype.addCookie](#webdriverwebdriveroptionsprototypeaddcookie) -* [webdriver.WebDriver.Options.prototype.deleteAllCookies](#webdriverwebdriveroptionsprototypedeleteallcookies) -* [webdriver.WebDriver.Options.prototype.deleteCookie](#webdriverwebdriveroptionsprototypedeletecookie) -* [webdriver.WebDriver.Options.prototype.getCookies](#webdriverwebdriveroptionsprototypegetcookies) -* [webdriver.WebDriver.Options.prototype.getCookie](#webdriverwebdriveroptionsprototypegetcookie) -* [webdriver.WebDriver.Options.prototype.logs](#webdriverwebdriveroptionsprototypelogs) -* [webdriver.WebDriver.Options.prototype.timeouts](#webdriverwebdriveroptionsprototypetimeouts) -* [webdriver.WebDriver.Options.prototype.window](#webdriverwebdriveroptionsprototypewindow) -* [webdriver.WebDriver.Timeouts](#webdriverwebdrivertimeouts) -* [webdriver.WebDriver.Timeouts.prototype.implicitlyWait](#webdriverwebdrivertimeoutsprototypeimplicitlywait) -* [webdriver.WebDriver.Timeouts.prototype.setScriptTimeout](#webdriverwebdrivertimeoutsprototypesetscripttimeout) -* [webdriver.WebDriver.Timeouts.prototype.pageLoadTimeout](#webdriverwebdrivertimeoutsprototypepageloadtimeout) -* [webdriver.WebDriver.Window](#webdriverwebdriverwindow) -* [webdriver.WebDriver.Window.prototype.getPosition](#webdriverwebdriverwindowprototypegetposition) -* [webdriver.WebDriver.Window.prototype.setPosition](#webdriverwebdriverwindowprototypesetposition) -* [webdriver.WebDriver.Window.prototype.getSize](#webdriverwebdriverwindowprototypegetsize) -* [webdriver.WebDriver.Window.prototype.setSize](#webdriverwebdriverwindowprototypesetsize) -* [webdriver.WebDriver.Window.prototype.maximize](#webdriverwebdriverwindowprototypemaximize) -* [webdriver.WebDriver.Logs](#webdriverwebdriverlogs) -* [webdriver.WebDriver.Logs.prototype.get](#webdriverwebdriverlogsprototypeget) -* [webdriver.WebDriver.Logs.prototype.getAvailableLogTypes](#webdriverwebdriverlogsprototypegetavailablelogtypes) -* [webdriver.WebDriver.TargetLocator](#webdriverwebdrivertargetlocator) -* [webdriver.WebDriver.TargetLocator.prototype.activeElement](#webdriverwebdrivertargetlocatorprototypeactiveelement) -* [webdriver.WebDriver.TargetLocator.prototype.defaultContent](#webdriverwebdrivertargetlocatorprototypedefaultcontent) -* [webdriver.WebDriver.TargetLocator.prototype.frame](#webdriverwebdrivertargetlocatorprototypeframe) -* [webdriver.WebDriver.TargetLocator.prototype.window](#webdriverwebdrivertargetlocatorprototypewindow) -* [webdriver.WebDriver.TargetLocator.prototype.alert](#webdriverwebdrivertargetlocatorprototypealert) -* [webdriver.Key.chord](#webdriverkeychord) -* [webdriver.WebElement](#webdriverwebelement) -* [webdriver.WebElement.equals](#webdriverwebelementequals) -* [webdriver.WebElement.prototype.getDriver](#webdriverwebelementprototypegetdriver) -* [webdriver.WebElement.prototype.toWireValue](#webdriverwebelementprototypetowirevalue) -* [webdriver.WebElement.prototype.findElement](#webdriverwebelementprototypefindelement) -* [webdriver.WebElement.prototype.isElementPresent](#webdriverwebelementprototypeiselementpresent) -* [webdriver.WebElement.prototype.findElements](#webdriverwebelementprototypefindelements) -* [webdriver.WebElement.prototype.click](#webdriverwebelementprototypeclick) -* [webdriver.WebElement.prototype.sendKeys](#webdriverwebelementprototypesendkeys) -* [webdriver.WebElement.prototype.getTagName](#webdriverwebelementprototypegettagname) -* [webdriver.WebElement.prototype.getCssValue](#webdriverwebelementprototypegetcssvalue) -* [webdriver.WebElement.prototype.getAttribute](#webdriverwebelementprototypegetattribute) -* [webdriver.WebElement.prototype.getText](#webdriverwebelementprototypegettext) -* [webdriver.WebElement.prototype.getSize](#webdriverwebelementprototypegetsize) -* [webdriver.WebElement.prototype.getLocation](#webdriverwebelementprototypegetlocation) -* [webdriver.WebElement.prototype.isEnabled](#webdriverwebelementprototypeisenabled) -* [webdriver.WebElement.prototype.isSelected](#webdriverwebelementprototypeisselected) -* [webdriver.WebElement.prototype.submit](#webdriverwebelementprototypesubmit) -* [webdriver.WebElement.prototype.clear](#webdriverwebelementprototypeclear) -* [webdriver.WebElement.prototype.isDisplayed](#webdriverwebelementprototypeisdisplayed) -* [webdriver.WebElement.prototype.getOuterHtml](#webdriverwebelementprototypegetouterhtml) -* [webdriver.WebElement.prototype.getInnerHtml](#webdriverwebelementprototypegetinnerhtml) -* [webdriver.Alert](#webdriveralert) -* [webdriver.Alert.prototype.getText](#webdriveralertprototypegettext) -* [webdriver.Alert.prototype.accept](#webdriveralertprototypeaccept) -* [webdriver.Alert.prototype.dismiss](#webdriveralertprototypedismiss) -* [webdriver.Alert.prototype.sendKeys](#webdriveralertprototypesendkeys) -* [webdriver.UnhandledAlertError](#webdriverunhandledalerterror) -* [webdriver.UnhandledAlertError.prototype.getAlert](#webdriverunhandledalerterrorprototypegetalert) - -##[element](https://github.com/angular/protractor/blob/master/lib/protractor.js#L74) -#### Use as: element(locator) -The element function returns an Element Finder. Element Finders do -not actually attempt to find the element until a method is called on them, -which means they can be set up in helper files before the page is -available. - - -###Example - -```html -{{person.name}} - - -``` - -```javascript -// Find element with {{scopeVar}} syntax. -element(by.binding('person.name')).getText().then(function(name) { - expect(name).toBe('Foo'); -}); - -// Find element with ng-bind="scopeVar" syntax. -expect(element(by.binding('person.email')).getText()).toBe('foo@bar.com'); - -// Find by model. -var input = element(by.model('person.name')); -input.sendKeys('123'); -expect(input.getAttribute('value')).toBe('Foo123'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | webdriver.Locator | An element locator. - - - - -###Returns - -Type | Description ---- | --- -ElementFinder | - - -##[elementFinder.find](https://github.com/angular/protractor/blob/master/lib/protractor.js#L128) -#### Use as: element(locator).find() -Returns the specified WebElement. Throws the WebDriver error if the -element doesn't exist. - - - - - - -###Returns - -Type | Description ---- | --- -[webdriver.WebElement](#webdriverwebelement) | - - -##[elementFinder.isPresent](https://github.com/angular/protractor/blob/master/lib/protractor.js#L139) -#### Use as: element(locator).isPresent() -Determine whether an element is present on the page. - - -###Example - -```html -{{person.name}} -``` - -```javascript -// Element exists. -expect(element(by.binding('person.name')).isPresent()).toBe(true); - -// Element not present. -expect(element(by.binding('notPresent')).isPresent()).toBe(false); -``` - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise which resolves to a boolean. - - -##[elementFinder.locator](https://github.com/angular/protractor/blob/master/lib/protractor.js#L161) - -Returns the originally specified locator. - - - - - - -###Returns - -Type | Description ---- | --- -webdriver.Locator | The element locator. - - -##[elementFinder.element](https://github.com/angular/protractor/blob/master/lib/protractor.js#L170) -#### Use as: element(locator).element(locator) -Calls to element may be chained to find elements within a parent. - - -###Example - -```html -
-
- Child text -
{{person.phone}}
-
-
-``` - -```javascript -// Chain 2 element calls. -var child = element(by.css('.parent')). - element(by.css('.child')); -expect(child.getText()).toBe('Child text\n555-123-4567'); - -// Chain 3 element calls. -var triple = element(by.css('.parent')). - element(by.css('.child')). - element(by.binding('person.phone')); -expect(triple.getText()).toBe('555-123-4567'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -ptor | [Protractor](#protractor) | -opt_usingChain | Array.<webdriver.Locator>= | - - - - -###Returns - -Type | Description ---- | --- -function(webdriver.Locator): ElementFinder | - - -##[elementFinder.$](https://github.com/angular/protractor/blob/master/lib/protractor.js#L201) -#### Use as: element(locator).$(cssSelector) -Shortcut for chaining css element finders. - - -###Example - -```html -
-
- Child text -
{{person.phone}}
-
-
-``` - -```javascript -// Chain 2 element calls. -var child = element(by.css('.parent')).$('.child'); -expect(child.getText()).toBe('Child text\n555-123-4567'); - -// Chain 3 element calls. -var triple = $('.parent').$('.child').$('.grandchild'); -expect(triple.getText()).toBe('555-123-4567'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -cssSelector | string | A css selector. - - - - -###Returns - -Type | Description ---- | --- -ElementFinder | - - -##[element.all](https://github.com/angular/protractor/blob/master/lib/protractor.js#L238) -#### Use as: element.all(locator) -element.all is used for operations on an array of elements (as opposed -to a single element). - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -element.all(by.css('.items li')).then(function(items) { - expect(items.length).toBe(3); - expect(items[0].getText()).toBe('First'); -}); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | webdriver.Locator | - - - - -###Returns - -Type | Description ---- | --- -ElementArrayFinder | - - -##[elementArrayFinder.count](https://github.com/angular/protractor/blob/master/lib/protractor.js#L262) -#### Use as: element.all(locator).count() -Count the number of elements found by the locator. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -var list = element.all(by.css('.items li')); -expect(list.count()).toBe(3); -``` - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise which resolves to the number of elements matching the locator. - - -##[elementArrayFinder.get](https://github.com/angular/protractor/blob/master/lib/protractor.js#L286) -#### Use as: element.all(locator).get(index) -Get an element found by the locator by index. The index starts at 0. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -var list = element.all(by.css('.items li')); -expect(list.get(0).getText()).toBe('First'); -expect(list.get(1).getText()).toBe('Second'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -index | number | Element index. - - - - -###Returns - -Type | Description ---- | --- -[webdriver.WebElement](#webdriverwebelement) | The element at the given index - - -##[elementArrayFinder.first](https://github.com/angular/protractor/blob/master/lib/protractor.js#L312) -#### Use as: element.all(locator).first() -Get the first element found using the locator. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -var list = element.all(by.css('.items li')); -expect(list.first().getText()).toBe('First'); -``` - - - - - -###Returns - -Type | Description ---- | --- -[webdriver.WebElement](#webdriverwebelement) | The first matching element - - -##[elementArrayFinder.last](https://github.com/angular/protractor/blob/master/lib/protractor.js#L339) -#### Use as: element.all(locator).last() -Get the last matching element for the locator. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -var list = element.all(by.css('.items li')); -expect(list.last().getText()).toBe('Third'); -``` - - - - - -###Returns - -Type | Description ---- | --- -[webdriver.WebElement](#webdriverwebelement) | the last matching element - - -##[elementArrayFinder.each](https://github.com/angular/protractor/blob/master/lib/protractor.js#L389) -#### Use as: element.all(locator).each(eachFunction) -Calls the input function on each WebElement found by the locator. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -element.all(by.css('.items li')).each(function(element) { - // Will print First, Second, Third. - element.getText().then(console.log); -}); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -fn | function([webdriver.WebElement](#webdriverwebelement)) | Input function - - - - - -##[elementArrayFinder.map](https://github.com/angular/protractor/blob/master/lib/protractor.js#L416) -#### Use as: element.all(locator).map(mapFunction) -Apply a map function to each element found using the locator. The -callback receives the web element as the first argument and the index as -a second arg. - - -###Example - -```html -
    -
  • First
    • -
  • Second
    • -
  • Third
    • -
-``` - -```javascript -var items = element.all(by.css('.items li')).map(function(elm, index) { - return { - index: index, - text: elm.getText(), - class: elm.getAttribute('class') - }; -}); -expect(items).toEqual([ - {index: 0, text: 'First', class: 'one'}, - {index: 1, text: 'Second', class: 'two'}, - {index: 2, text: 'Third', class: 'three'} -]); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -mapFn | function([webdriver.WebElement](#webdriverwebelement), number) | Map function that will be applied to each element. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that resolves to an array of values returned by the map function. - - -##[Protractor](https://github.com/angular/protractor/blob/master/lib/protractor.js#L494) - - - - - - -###Params - -Param | Type | Description ---- | --- | --- -webdriver | [webdriver.WebDriver](#webdriverwebdriver) | -opt_baseUrl | string= | A base URL to run get requests against. -opt_rootElement | string= | Selector element that has an ng-app in scope. - - - - - -##[Protractor.prototype.waitForAngular](https://github.com/angular/protractor/blob/master/lib/protractor.js#L589) - -Instruct webdriver to wait until Angular has finished rendering and has -no outstanding $http calls before continuing. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve to the scripts return value. - - -##[Protractor.prototype.wrapWebElement](https://github.com/angular/protractor/blob/master/lib/protractor.js#L630) - -Wrap a webdriver.WebElement with protractor specific functionality. - - - - -###Params - -Param | Type | Description ---- | --- | --- -element | [webdriver.WebElement](#webdriverwebelement) | - - - - -###Returns - -Type | Description ---- | --- -[webdriver.WebElement](#webdriverwebelement) | the wrapped web element. - - -##[element.$](https://github.com/angular/protractor/blob/master/lib/protractor.js#L655) -#### Use as: $(cssSelector) -Shortcut for querying the document directly with css. - - -###Example - -```html -
- First - Second -
-``` - -```javascript -var item = $('.count .two'); -expect(item.getText()).toBe('Second'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -selector | string | A css selector - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | - - -##[element.findElement](https://github.com/angular/protractor/blob/master/lib/protractor.js#L678) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | - - -##[element.$$](https://github.com/angular/protractor/blob/master/lib/protractor.js#L695) -#### Use as: $$(cssSelector) -Shortcut for querying the document directly with css. - - -###Example - -```html -
- First - Second -
-``` - -```javascript -// The following protractor expressions are equivalent. -var list = element.all(by.css('.count span')); -expect(list.count()).toBe(2); - -list = $$('.count span'); -expect(list.count()).toBe(2); -expect(list.get(0).getText()).toBe('First'); -expect(list.get(1).getText()).toBe('Second'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -selector | string | a css selector - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to an array of the located [webdriver.WebElement](#webdriverwebelement)s. - - -##[element.findElements](https://github.com/angular/protractor/blob/master/lib/protractor.js#L725) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to an array of the located [webdriver.WebElement](#webdriverwebelement)s. - - -##[element.isElementPresent](https://github.com/angular/protractor/blob/master/lib/protractor.js#L749) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with whether an element could be located on the page. - - -##[element.evaluate](https://github.com/angular/protractor/blob/master/lib/protractor.js#L765) - -Evaluates the input as if it were on the scope of the current element. - - - - -###Params - -Param | Type | Description ---- | --- | --- -expression | string | - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve to the evaluated expression. The result will be resolved as in {@link webdriver.WebDriver.executeScript}. In summary - primitives will be resolved as is, functions will be converted to string, and elements will be returned as a WebElement. - - -##[Protractor.prototype.findElement](https://github.com/angular/protractor/blob/master/lib/protractor.js#L784) - -Waits for Angular to finish rendering before searching for elements. - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | - - -##[Protractor.prototype.findElements](https://github.com/angular/protractor/blob/master/lib/protractor.js#L802) - -Waits for Angular to finish rendering before searching for elements. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to an array of the located [webdriver.WebElement](#webdriverwebelement)s. - - -##[Protractor.prototype.isElementPresent](https://github.com/angular/protractor/blob/master/lib/protractor.js#L827) - -Tests if an element is present on the page. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve to whether the element is present on the page. - - -##[Protractor.prototype.addMockModule](https://github.com/angular/protractor/blob/master/lib/protractor.js#L843) - -Add a module to load before Angular whenever Protractor.get is called. -Modules will be registered after existing modules already on the page, -so any module registered here will override preexisting modules with the same -name. - - - - -###Params - -Param | Type | Description ---- | --- | --- -name | !string | The name of the module to load or override. -script | !string|Function | The JavaScript to load the module. -varArgs | ...* | Any additional arguments will be provided to the script and may be referenced using the `arguments` object. - - - - - -##[Protractor.prototype.clearMockModules](https://github.com/angular/protractor/blob/master/lib/protractor.js#L861) - -Clear the list of registered mock modules. - - - - - - - -##[Protractor.prototype.removeMockModule](https://github.com/angular/protractor/blob/master/lib/protractor.js#L870) - -Remove a registered mock module. - - - - -###Params - -Param | Type | Description ---- | --- | --- -name | !string | The name of the module to remove. - - - - - -##[Protractor.prototype.get](https://github.com/angular/protractor/blob/master/lib/protractor.js#L881) - -See webdriver.WebDriver.get - -Navigate to the given destination and loads mock modules before -Angular. Assumes that the page being loaded uses Angular. -If you need to access a page which does not have Angular on load, use -the wrapped webdriver directly. - - - - -###Params - -Param | Type | Description ---- | --- | --- -destination | string | Destination URL. -opt_timeout | number= | Number of seconds to wait for Angular to start. - - - - - -##[Protractor.prototype.refresh](https://github.com/angular/protractor/blob/master/lib/protractor.js#L949) - -See webdriver.WebDriver.refresh - -Makes a full reload of the current page and loads mock modules before -Angular. Assumes that the page being loaded uses Angular. -If you need to access a page which does not have Angular on load, use -the wrapped webdriver directly. - - - - -###Params - -Param | Type | Description ---- | --- | --- -opt_timeout | number= | Number of seconds to wait for Angular to start. - - - - - -##[Protractor.prototype.navigate](https://github.com/angular/protractor/blob/master/lib/protractor.js#L972) - -Mixin navigation methods back into the navigation object so that -they are invoked as before, i.e. driver.navigate().refresh() - - - - - - - -##[Protractor.prototype.setLocation](https://github.com/angular/protractor/blob/master/lib/protractor.js#L982) - -Browse to another page using in-page navigation. - - - - -###Params - -Param | Type | Description ---- | --- | --- -url | string | In page URL using the same syntax as $location.url() - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve once page has been changed. - - -##[Protractor.prototype.getLocationAbsUrl](https://github.com/angular/protractor/blob/master/lib/protractor.js#L1000) - -Returns the current absolute url from AngularJS. - - - - - - - -##[Protractor.prototype.debugger](https://github.com/angular/protractor/blob/master/lib/protractor.js#L1008) - -Pauses the test and injects some helper functions into the browser, so that -debugging may be done in the browser console. - -This should be used under node in debug mode, i.e. with -protractor debug - -While in the debugger, commands can be scheduled through webdriver by -entering the repl: - debug> repl - Press Ctrl + C to leave rdebug repl - > ptor.findElement(protractor.By.input('user').sendKeys('Laura')); - > ptor.debugger(); - debug> c - -This will run the sendKeys command as the next task, then re-enter the -debugger. - - - - - - - -##[Protractor.prototype.pause](https://github.com/angular/protractor/blob/master/lib/protractor.js#L1043) - -Beta (unstable) pause function for debugging webdriver tests. Use -browser.pause() in your test to enter the protractor debugger from that -point in the control flow. -Does not require changes to the command line (no need to add 'debug'). - - - - - - - -##[ProtractorBy](https://github.com/angular/protractor/blob/master/lib/locators.js#L6) - -The Protractor Locators. These provide ways of finding elements in -Angular applications by binding, model, etc. - - - - - - - -##[WebdriverBy.prototype](https://github.com/angular/protractor/blob/master/lib/locators.js#L15) - -webdriver's By is an enum of locator functions, so we must set it to -a prototype before inheriting from it. - - - - - - - -##[ProtractorBy.prototype.addLocator](https://github.com/angular/protractor/blob/master/lib/locators.js#L22) -#### Use as: by.addLocator(locatorName, functionOrScript) -Add a locator to this instance of ProtractorBy. This locator can then be -used with element(by.locatorName(args)). - - -###Example - -```html - -``` - -```javascript -// Add the custom locator. -by.addLocator('buttonTextSimple', function(buttonText, opt_parentElement) { - // This function will be serialized as a string and will execute in the - // browser. The first argument is the text for the button. The second - // argument is the parent element, if any. - var using = opt_parentElement || document, - buttons = using.querySelectorAll('button'); - - // Return an array of buttons with the text. - return Array.prototype.filter.call(buttons, function(button) { - return button.textContent === buttonText; - }); -}); - -// Use the custom locator. -element(by.buttonTextSimple('Go!')).click(); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -name | string | The name of the new locator. -script | Function|string | A script to be run in the context of the browser. This script will be passed an array of arguments that contains any args passed into the locator followed by the element scoping the search. It should return an array of elements. - - - - - -##[ProtractorBy.prototype.binding](https://github.com/angular/protractor/blob/master/lib/locators.js#L73) -#### Use as: by.binding() -Find an element by binding. - - -###Example - -```html -{{person.name}} - -``` - -```javascript -var span1 = element(by.binding('person.name')); -expect(span1.getText()).toBe('Foo'); - -var span2 = element(by.binding('person.email')); -expect(span2.getText()).toBe('foo@bar.com'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -bindingDescriptor | string | - - - - -###Returns - -Type | Description ---- | --- -{findElementsOverride: findElementsOverride, message: string} | - - -##[ProtractorBy.prototype.exactBinding](https://github.com/angular/protractor/blob/master/lib/locators.js#L102) -#### Use as: by.exactBinding() -Same as by.binding() except this does not allow for partial matches -Find an element by exact binding. - - - - -###Params - -Param | Type | Description ---- | --- | --- -bindingDescriptor | string | - - - - -###Returns - -Type | Description ---- | --- -{findElementsOverride: findElementsOverride, message: string} | - - -##[ProtractorBy.prototype.select](https://github.com/angular/protractor/blob/master/lib/locators.js#L122) - -**DEPRECATED** Use 'model' instead. - - -###Example - -```html - -``` - -```javascript -element(by.select('user')); -``` - - - - - - -##[ProtractorBy.prototype.selectedOption](https://github.com/angular/protractor/blob/master/lib/locators.js#L141) - - - - -###Example - -```html - -``` - -```javascript -element(by.selectedOption("user")); -``` - - - - - - -##[ProtractorBy.prototype.input](https://github.com/angular/protractor/blob/master/lib/locators.js#L158) - -**DEPRECATED** Use 'model' instead. - - -###Example - -```html - -``` - -```javascript -element(by.input('user')); -``` - - - - - - -##[ProtractorBy.prototype.model](https://github.com/angular/protractor/blob/master/lib/locators.js#L176) -#### Use as: by.model(modelName) -Find an element by ng-model expression. - - -###Example - -```html - -``` - -```javascript -var input = element(by.model('person.name')); -input.sendKeys('123'); -expect(input.getAttribute('value')).toBe('Foo123'); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -model | string | ng-model expression. - - - - - -##[ProtractorBy.prototype.buttonText](https://github.com/angular/protractor/blob/master/lib/locators.js#L200) - -Find a button by text. - - -###Example - -```html - -``` - -```javascript -element(by.buttonText('Save')); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -searchText | string | - - - - -###Returns - -Type | Description ---- | --- -{findElementsOverride: findElementsOverride, message: string} | - - -##[ProtractorBy.prototype.partialButtonText](https://github.com/angular/protractor/blob/master/lib/locators.js#L223) - -Find a button by partial text. - - -###Example - -```html - -``` - -```javascript -element(by.partialButtonText('Save')); -``` - - - -###Params - -Param | Type | Description ---- | --- | --- -searchText | string | - - - - -###Returns - -Type | Description ---- | --- -{findElementsOverride: findElementsOverride, message: string} | - - -##[ProtractorBy.prototype.textarea](https://github.com/angular/protractor/blob/master/lib/locators.js#L247) - -**DEPRECATED** Use 'model' instead. - - -###Example - -```html - -``` - -```javascript -element(by.textarea('user')); -``` - - - - - - -##[ProtractorBy.prototype.repeater](https://github.com/angular/protractor/blob/master/lib/locators.js#L265) - -Find elements inside an ng-repeat. - - -###Example - -```html -
- {{cat.name}} - {{cat.age}} -
-``` - -```javascript -// Returns the DIV for the second cat. -var secondCat = element(by.repeater('cat in pets').row(1)); - -// Returns the SPAN for the first cat's name. -var firstCatName = element(by.repeater('cat in pets'). - row(0).column('{{cat.name}}')); - -// Returns a promise that resolves to an array of WebElements from a column -var ages = element.all( - by.repeater('cat in pets').column('{{cat.age}}')); - -// Returns a promise that resolves to an array of WebElements containing -// all rows of the repeater. -var rows = element.all(by.repeater('cat in pets')); -``` - - - - - - -##[ProtractorBy.prototype.cssContainingText](https://github.com/angular/protractor/blob/master/lib/locators.js#L344) - -Find elements by CSS which contain a certain string. - - -###Example - -```html -
    -
  • Dog
    • -
  • Cat
    • -
-``` - -```javascript -// Returns the DIV for the dog, but not cat. -var dog = element(by.cssContainingText('.pet', 'Dog')); -``` - - - - - - -##[webdriver.WebDriver](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#47) - -Creates a new WebDriver client, which provides control over a browser. - -Every WebDriver command returns a {@code webdriver.promise.Promise} that -represents the result of that command. Callbacks may be registered on this -object to manipulate the command result or catch an expected error. Any -commands scheduled with a callback are considered sub-commands and will -execute before the next command in the current frame. For example: -

-  var message = [];
-  driver.call(message.push, message, 'a').then(function() {
-    driver.call(message.push, message, 'b');
-  });
-  driver.call(message.push, message, 'c');
-  driver.call(function() {
-    alert('message is abc? ' + (message.join('') == 'abc'));
-  });
-
- - - - -###Params - -Param | Type | Description ---- | --- | --- -session | !(webdriver.Session|webdriver.promise.Promise) | Either a known session or a promise that will be resolved to a session. -executor | !webdriver.CommandExecutor | The executor to use when sending commands to the browser. -opt_flow | webdriver.promise.ControlFlow= | The flow to schedule commands through. Defaults to the active flow object. - - - - - -##[webdriver.WebDriver.attachToSession](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#87) - -Creates a new WebDriver client for an existing session. - - - - -###Params - -Param | Type | Description ---- | --- | --- -executor | !webdriver.CommandExecutor | Command executor to use when querying for session details. -sessionId | string | ID of the session to attach to. - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver](#webdriverwebdriver) | A new client for the specified session. - - -##[webdriver.WebDriver.createSession](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#102) - -Creates a new WebDriver session. - - - - -###Params - -Param | Type | Description ---- | --- | --- -executor | !webdriver.CommandExecutor | The executor to create the new session with. -desiredCapabilities | !webdriver.Capabilities | The desired capabilities for the new session. - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver](#webdriverwebdriver) | The driver for the newly created session. - - -##[webdriver.WebDriver.prototype.controlFlow](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#243) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.ControlFlow | The control flow used by this instance. - - -##[webdriver.WebDriver.prototype.schedule](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#252) - -Schedules a {@code webdriver.Command} to be executed by this driver's -{@code webdriver.CommandExecutor}. - - - - -###Params - -Param | Type | Description ---- | --- | --- -command | !webdriver.Command | The command to schedule. -description | string | A description of the command for debugging. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the command result. - - -##[webdriver.WebDriver.prototype.getSession](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#304) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise for this client's session. - - -##[webdriver.WebDriver.prototype.getCapabilities](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#312) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve with the this instance's capabilities. - - -##[webdriver.WebDriver.prototype.quit](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#323) - -Schedules a command to quit the current session. After calling quit, this -instance will be invalidated and may no longer be used to issue commands -against the browser. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the command has completed. - - -##[webdriver.WebDriver.prototype.actions](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#342) - -Creates a new action sequence using this driver. The sequence will not be -scheduled for execution until {@link webdriver.ActionSequence#perform} is -called. Example: -

-  driver.actions().
-      mouseDown(element1).
-      mouseMove(element2).
-      mouseUp().
-      perform();
-
- - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.ActionSequence | A new action sequence for this instance. - - -##[webdriver.WebDriver.prototype.executeScript](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#360) - -Schedules a command to execute JavaScript in the context of the currently -selected frame or window. The script fragment will be executed as the body -of an anonymous function. If the script is provided as a function object, -that function will be converted to a string for injection into the target -window. - -Any arguments provided in addition to the script will be included as script -arguments and may be referenced using the {@code arguments} object. -Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. -Arrays and objects may also be used as script arguments as long as each item -adheres to the types previously mentioned. - -The script may refer to any variables accessible from the current window. -Furthermore, the script will execute in the window's context, thus -{@code document} may be used to refer to the current document. Any local -variables will not be available once the script has finished executing, -though global variables will persist. - -If the script has a return value (i.e. if the script contains a return -statement), then the following steps will be taken for resolving this -functions return value: -
    -
  • For a HTML element, the value will resolve to a - {@code webdriver.WebElement}
    • -
  • Null and undefined return values will resolve to null
    • -
  • Booleans, numbers, and strings will resolve as is
    • -
  • Functions will resolve to their string representation
    • -
  • For arrays and objects, each member item will be converted according to - the rules above
    • -
- - - - -###Params - -Param | Type | Description ---- | --- | --- -script | !(string|Function) | The script to execute. -var_args | ...* | The arguments to pass to the script. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve to the scripts return value. - - -##[webdriver.WebDriver.prototype.executeAsyncScript](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#409) - -Schedules a command to execute asynchronous JavaScript in the context of the -currently selected frame or window. The script fragment will be executed as -the body of an anonymous function. If the script is provided as a function -object, that function will be converted to a string for injection into the -target window. - -Any arguments provided in addition to the script will be included as script -arguments and may be referenced using the {@code arguments} object. -Arguments may be a boolean, number, string, or {@code webdriver.WebElement}. -Arrays and objects may also be used as script arguments as long as each item -adheres to the types previously mentioned. - -Unlike executing synchronous JavaScript with -{@code webdriver.WebDriver.prototype.executeScript}, scripts executed with -this function must explicitly signal they are finished by invoking the -provided callback. This callback will always be injected into the -executed function as the last argument, and thus may be referenced with -{@code arguments[arguments.length - 1]}. The following steps will be taken -for resolving this functions return value against the first argument to the -script's callback function: -
    -
  • For a HTML element, the value will resolve to a - {@code webdriver.WebElement}
    • -
  • Null and undefined return values will resolve to null
    • -
  • Booleans, numbers, and strings will resolve as is
    • -
  • Functions will resolve to their string representation
    • -
  • For arrays and objects, each member item will be converted according to - the rules above
    • -
- -Example #1: Performing a sleep that is synchronized with the currently -selected window: -
-var start = new Date().getTime();
-driver.executeAsyncScript(
-    'window.setTimeout(arguments[arguments.length - 1], 500);').
-    then(function() {
-      console.log('Elapsed time: ' + (new Date().getTime() - start) + ' ms');
-    });
-
 - -Example #2: Synchronizing a test with an AJAX application: -
-var button = driver.findElement(By.id('compose-button'));
-button.click();
-driver.executeAsyncScript(
-    'var callback = arguments[arguments.length - 1];' +
-    'mailClient.getComposeWindowWidget().onload(callback);');
-driver.switchTo().frame('composeWidget');
-driver.findElement(By.id('to')).sendKEys('dog@example.com');
-
 - -Example #3: Injecting a XMLHttpRequest and waiting for the result. In this -example, the inject script is specified with a function literal. When using -this format, the function is converted to a string for injection, so it -should not reference any symbols not defined in the scope of the page under -test. -
-driver.executeAsyncScript(function() {
-  var callback = arguments[arguments.length - 1];
-  var xhr = new XMLHttpRequest();
-  xhr.open("GET", "/resource/data.json", true);
-  xhr.onreadystatechange = function() {
-    if (xhr.readyState == 4) {
-      callback(xhr.resposneText);
-    }
-  }
-  xhr.send('');
-}).then(function(str) {
-  console.log(JSON.parse(str)['food']);
-});
-
 - - - - -###Params - -Param | Type | Description ---- | --- | --- -script | !(string|Function) | The script to execute. -var_args | ...* | The arguments to pass to the script. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will resolve to the scripts return value. - - -##[webdriver.WebDriver.prototype.call](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#500) - -Schedules a command to execute a custom function. - - - - -###Params - -Param | Type | Description ---- | --- | --- -fn | !Function | The function to execute. -opt_scope | Object= | The object in whose scope to execute the function. -var_args | ...* | Any arguments to pass to the function. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the function's result. - - -##[webdriver.WebDriver.prototype.wait](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#519) - -Schedules a command to wait for a condition to hold, as defined by some -user supplied function. If any errors occur while evaluating the wait, they -will be allowed to propagate. - - - - -###Params - -Param | Type | Description ---- | --- | --- -fn | function():boolean | The function to evaluate as a wait condition. -timeout | number | How long to wait for the condition to be true. -opt_message | string= | An optional message to use if the wait times out. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the wait condition has been satisfied. - - -##[webdriver.WebDriver.prototype.sleep](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#535) - -Schedules a command to make the driver sleep for the given amount of time. - - - - -###Params - -Param | Type | Description ---- | --- | --- -ms | number | The amount of time, in milliseconds, to sleep. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the sleep has finished. - - -##[webdriver.WebDriver.prototype.getWindowHandle](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#546) - -Schedules a command to retrieve they current window handle. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the current window handle. - - -##[webdriver.WebDriver.prototype.getAllWindowHandles](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#558) - -Schedules a command to retrieve the current list of available window handles. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with an array of window handles. - - -##[webdriver.WebDriver.prototype.getPageSource](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#570) - -Schedules a command to retrieve the current page's source. The page source -returned is a representation of the underlying DOM: do not expect it to be -formatted or escaped in the same way as the response sent from the web -server. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the current page source. - - -##[webdriver.WebDriver.prototype.close](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#585) - -Schedules a command to close the current window. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when this command has completed. - - -##[webdriver.WebDriver.prototype.get](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#596) - -Schedules a command to navigate to the given URL. - - - - -###Params - -Param | Type | Description ---- | --- | --- -url | string | The fully qualified URL to open. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the document has finished loading. - - -##[webdriver.WebDriver.prototype.getCurrentUrl](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#607) - -Schedules a command to retrieve the URL of the current page. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the current URL. - - -##[webdriver.WebDriver.prototype.getTitle](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#619) - -Schedules a command to retrieve the current page's title. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the current page's title. - - -##[webdriver.WebDriver.prototype.findElement](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#630) - -Schedule a command to find an element on the page. If the element cannot be -found, a {@link bot.ErrorCode.NO_SUCH_ELEMENT} result will be returned -by the driver. Unlike other commands, this error cannot be suppressed. In -other words, scheduling a command to find an element doubles as an assert -that the element is present on the page. To test whether an element is -present on the page, use {@link #isElementPresent} instead. - -

The search criteria for an element may be defined using one of the -factories in the {@link webdriver.By} namespace, or as a short-hand -{@link webdriver.By.Hash} object. For example, the following two statements -are equivalent: -

-var e1 = driver.findElement(By.id('foo'));
-var e2 = driver.findElement({id:'foo'});
-
- -

You may also provide a custom locator function, which takes as input -this WebDriver instance and returns a {@link webdriver.WebElement}, or a -promise that will resolve to a WebElement. For example, to find the first -visible link on a page, you could write: -

-var link = driver.findElement(firstVisibleLink);
-
-function firstVisibleLink(driver) {
-  var links = driver.findElements(By.tagName('a'));
-  return webdriver.promise.filter(links, function(link) {
-    return links.isDisplayed();
-  }).then(function(visibleLinks) {
-    return visibleLinks[0];
-  });
-}
-
- -

When running in the browser, a WebDriver cannot manipulate DOM elements -directly; it may do so only through a {@link webdriver.WebElement} reference. -This function may be used to generate a WebElement from a DOM element. A -reference to the DOM element will be stored in a known location and this -driver will attempt to retrieve it through {@link #executeScript}. If the -element cannot be found (eg, it belongs to a different document than the -one this instance is currently focused on), a -{@link bot.ErrorCode.NO_SUCH_ELEMENT} error will be returned. - - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | !(webdriver.Locator|webdriver.By.Hash|Element|Function) | The locator to use. - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | A WebElement that can be used to issue commands against the located element. If the element is not found, the element will be invalidated and all scheduled commands aborted. - - -##[webdriver.WebDriver.prototype.isElementPresent](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#777) - -Schedules a command to test if an element is present on the page. - -

If given a DOM element, this function will check if it belongs to the -document the driver is currently focused on. Otherwise, the function will -test if at least one element can be found with the given search criteria. - - - - -###Params - -Param | Type | Description ---- | --- | --- -locatorOrElement | !(webdriver.Locator|webdriver.By.Hash|Element| - Function) | The locator to use, or the actual DOM element to be located by the server. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<boolean> | A promise that will resolve with whether the element is present on the page. - - -##[webdriver.WebDriver.prototype.findElements](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#801) - -Schedule a command to search for multiple elements on the page. - - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | !(webdriver.Locator|webdriver.By.Hash|Function) | The locator strategy to use when searching for the element. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<!Array.<!webdriver.WebElement>> | A promise that will resolve to an array of WebElements. - - -##[webdriver.WebDriver.prototype.takeScreenshot](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#848) - -Schedule a command to take a screenshot. The driver makes a best effort to -return a screenshot of the following, in order of preference: -

    -
  1. Entire page -
  2. Current window -
  3. Visible portion of the current frame -
  4. The screenshot of the entire display containing the browser -
- - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to the screenshot as a base-64 encoded PNG. - - -##[webdriver.WebDriver.prototype.manage](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#867) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.Options](#webdriverwebdriveroptions) | The options interface for this instance. - - -##[webdriver.WebDriver.prototype.navigate](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#876) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.Navigation](#webdriverwebdrivernavigation) | The navigation interface for this instance. - - -##[webdriver.WebDriver.prototype.switchTo](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#885) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.TargetLocator](#webdriverwebdrivertargetlocator) | The target locator interface for this instance. - - -##[webdriver.WebDriver.Navigation](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#895) - -Interface for navigating back and forth in the browser history. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.Navigation.prototype.to](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#907) - -Schedules a command to navigate to a new URL. - - - - -###Params - -Param | Type | Description ---- | --- | --- -url | string | The URL to navigate to. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the URL has been loaded. - - -##[webdriver.WebDriver.Navigation.prototype.back](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#921) - -Schedules a command to move backwards in the browser history. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the navigation event has completed. - - -##[webdriver.WebDriver.Navigation.prototype.forward](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#933) - -Schedules a command to move forwards in the browser history. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the navigation event has completed. - - -##[webdriver.WebDriver.Navigation.prototype.refresh](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#945) - -Schedules a command to refresh the current page. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the navigation event has completed. - - -##[webdriver.WebDriver.Options](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#958) - -Provides methods for managing browser and driver state. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.Options.prototype.addCookie](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#970) - -Schedules a command to add a cookie. - - - - -###Params - -Param | Type | Description ---- | --- | --- -name | string | The cookie name. -value | string | The cookie value. -opt_path | string= | The cookie path. -opt_domain | string= | The cookie domain. -opt_isSecure | boolean= | Whether the cookie is secure. -opt_expiry | (number|!Date)= | When the cookie expires. If specified as a number, should be in milliseconds since midnight, January 1, 1970 UTC. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the cookie has been added to the page. - - -##[webdriver.WebDriver.Options.prototype.deleteAllCookies](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1027) - -Schedules a command to delete all cookies visible to the current page. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when all cookies have been deleted. - - -##[webdriver.WebDriver.Options.prototype.deleteCookie](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1039) - -Schedules a command to delete the cookie with the given name. This command is -a no-op if there is no cookie with the given name visible to the current -page. - - - - -###Params - -Param | Type | Description ---- | --- | --- -name | string | The name of the cookie to delete. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the cookie has been deleted. - - -##[webdriver.WebDriver.Options.prototype.getCookies](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1055) - -Schedules a command to retrieve all cookies visible to the current page. -Each cookie will be returned as a JSON object as described by the WebDriver -wire protocol. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the cookies visible to the current page. - - -##[webdriver.WebDriver.Options.prototype.getCookie](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1070) - -Schedules a command to retrieve the cookie with the given name. Returns null -if there is no such cookie. The cookie will be returned as a JSON object as -described by the WebDriver wire protocol. - - - - -###Params - -Param | Type | Description ---- | --- | --- -name | string | The name of the cookie to retrieve. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the named cookie, or {@code null} if there is no such cookie. - - -##[webdriver.WebDriver.Options.prototype.logs](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1088) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.Logs](#webdriverwebdriverlogs) | The interface for managing driver logs. - - -##[webdriver.WebDriver.Options.prototype.timeouts](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1097) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.Timeouts](#webdriverwebdrivertimeouts) | The interface for managing driver timeouts. - - -##[webdriver.WebDriver.Options.prototype.window](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1106) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver.Window](#webdriverwebdriverwindow) | The interface for managing the current window. - - -##[webdriver.WebDriver.Timeouts](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1116) - -An interface for managing timeout behavior for WebDriver instances. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.Timeouts.prototype.implicitlyWait](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1128) - -Specifies the amount of time the driver should wait when searching for an -element if it is not immediately present. -

-When searching for a single element, the driver should poll the page -until the element has been found, or this timeout expires before failing -with a {@code bot.ErrorCode.NO_SUCH_ELEMENT} error. When searching -for multiple elements, the driver should poll the page until at least one -element has been found or this timeout has expired. -

-Setting the wait timeout to 0 (its default value), disables implicit -waiting. -

-Increasing the implicit wait timeout should be used judiciously as it -will have an adverse effect on test run time, especially when used with -slower location strategies like XPath. - - - - -###Params - -Param | Type | Description ---- | --- | --- -ms | number | The amount of time to wait, in milliseconds. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the implicit wait timeout has been set. - - -##[webdriver.WebDriver.Timeouts.prototype.setScriptTimeout](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1157) - -Sets the amount of time to wait, in milliseconds, for an asynchronous script -to finish execution before returning an error. If the timeout is less than or -equal to 0, the script will be allowed to run indefinitely. - - - - -###Params - -Param | Type | Description ---- | --- | --- -ms | number | The amount of time to wait, in milliseconds. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the script timeout has been set. - - -##[webdriver.WebDriver.Timeouts.prototype.pageLoadTimeout](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1174) - -Sets the amount of time to wait for a page load to complete before returning -an error. If the timeout is negative, page loads may be indefinite. - - - - -###Params - -Param | Type | Description ---- | --- | --- -ms | number | The amount of time to wait, in milliseconds. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the timeout has been set. - - -##[webdriver.WebDriver.Window](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1191) - -An interface for managing the current window. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.Window.prototype.getPosition](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1203) - -Retrieves the window's current position, relative to the top left corner of -the screen. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the window's position in the form of a {x:number, y:number} object literal. - - -##[webdriver.WebDriver.Window.prototype.setPosition](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1217) - -Repositions the current window. - - - - -###Params - -Param | Type | Description ---- | --- | --- -x | number | The desired horizontal position, relative to the left side of the screen. -y | number | The desired vertical position, relative to the top of the of the screen. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the command has completed. - - -##[webdriver.WebDriver.Window.prototype.getSize](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1236) - -Retrieves the window's current size. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the window's size in the form of a {width:number, height:number} object literal. - - -##[webdriver.WebDriver.Window.prototype.setSize](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1250) - -Resizes the current window. - - - - -###Params - -Param | Type | Description ---- | --- | --- -width | number | The desired window width. -height | number | The desired window height. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the command has completed. - - -##[webdriver.WebDriver.Window.prototype.maximize](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1267) - -Maximizes the current window. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the command has completed. - - -##[webdriver.WebDriver.Logs](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1280) - -Interface for managing WebDriver log records. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.Logs.prototype.get](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1292) - -Fetches available log entries for the given type. - -

Note that log buffers are reset after each call, meaning that -available log entries correspond to those entries not yet returned for a -given log type. In practice, this means that this call will return the -available log entries since the last call, or from the start of the -session. - - - - -###Params - -Param | Type | Description ---- | --- | --- -type | !webdriver.logging.Type | The desired log type. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<!Array.<!webdriver.logging.Entry>> | A promise that will resolve to a list of log entries for the specified type. - - -##[webdriver.WebDriver.Logs.prototype.getAvailableLogTypes](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1323) - -Retrieves the log types available to this driver. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<!Array.<!webdriver.logging.Type>> | A promise that will resolve to a list of available log types. - - -##[webdriver.WebDriver.TargetLocator](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1336) - -An interface for changing the focus of the driver to another frame or window. - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent driver. - - - - - -##[webdriver.WebDriver.TargetLocator.prototype.activeElement](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1348) - -Schedules a command retrieve the {@code document.activeElement} element on -the current document, or {@code document.body} if activeElement is not -available. - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | The active element. - - -##[webdriver.WebDriver.TargetLocator.prototype.defaultContent](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1362) - -Schedules a command to switch focus of all future commands to the first frame -on the page. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the driver has changed focus to the default content. - - -##[webdriver.WebDriver.TargetLocator.prototype.frame](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1376) - -Schedules a command to switch the focus of all future commands to another -frame on the page. -

-If the frame is specified by a number, the command will switch to the frame -by its (zero-based) index into the {@code window.frames} collection. -

-If the frame is specified by a string, the command will select the frame by -its name or ID. To select sub-frames, simply separate the frame names/IDs by -dots. As an example, "main.child" will select the frame with the name "main" -and then its child "child". -

-If the specified frame can not be found, the deferred result will errback -with a {@code bot.ErrorCode.NO_SUCH_FRAME} error. - - - - -###Params - -Param | Type | Description ---- | --- | --- -nameOrIndex | string|number | The frame locator. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the driver has changed focus to the specified frame. - - -##[webdriver.WebDriver.TargetLocator.prototype.window](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1402) - -Schedules a command to switch the focus of all future commands to another -window. Windows may be specified by their {@code window.name} attribute or -by its handle (as returned by {@code webdriver.WebDriver#getWindowHandles}). -

-If the specificed window can not be found, the deferred result will errback -with a {@code bot.ErrorCode.NO_SUCH_WINDOW} error. - - - - -###Params - -Param | Type | Description ---- | --- | --- -nameOrHandle | string | The name or window handle of the window to switch focus to. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the driver has changed focus to the specified window. - - -##[webdriver.WebDriver.TargetLocator.prototype.alert](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1422) - -Schedules a command to change focus to the active alert dialog. This command -will return a {@link bot.ErrorCode.NO_MODAL_DIALOG_OPEN} error if a modal -dialog is not currently open. - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.Alert](#webdriveralert) | The open alert. - - -##[webdriver.Key.chord](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1436) - -Simulate pressing many keys at once in a "chord". Takes a sequence of -{@link webdriver.Key}s or strings, appends each of the values to a string, -and adds the chord termination key ({@link webdriver.Key.NULL}) and returns -the resultant string. - -Note: when the low-level webdriver key handlers see Keys.NULL, active -modifier keys (CTRL/ALT/SHIFT/etc) release via a keyup event. - - - - -###Params - -Param | Type | Description ---- | --- | --- -var_args | ...string | The key sequence to concatenate. - - - - -###Returns - -Type | Description ---- | --- -string | The null-terminated key sequence. - - -##[webdriver.WebElement](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1468) - -Represents a DOM element. WebElements can be found by searching from the -document root using a {@code webdriver.WebDriver} instance, or by searching -under another {@code webdriver.WebElement}: -


-  driver.get('http://www.google.com');
-  var searchForm = driver.findElement(By.tagName('form'));
-  var searchBox = searchForm.findElement(By.name('q'));
-  searchBox.sendKeys('webdriver');
-
- -The WebElement is implemented as a promise for compatibility with the promise -API. It will always resolve itself when its internal state has been fully -resolved and commands may be issued against the element. This can be used to -catch errors when an element cannot be located on the page: -

-  driver.findElement(By.id('not-there')).then(function(element) {
-    alert('Found an element that was not expected to be there!');
-  }, function(error) {
-    alert('The element was not found, as expected');
-  });
-
- - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The parent WebDriver instance for this element. -id | !(string|webdriver.promise.Promise) | Either the opaque ID for the underlying DOM element assigned by the server, or a promise that will resolve to that ID or another WebElement. - - - - - -##[webdriver.WebElement.equals](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1550) - -Compares to WebElements for equality. - - - - -###Params - -Param | Type | Description ---- | --- | --- -a | ![webdriver.WebElement](#webdriverwebelement) | A WebElement. -b | ![webdriver.WebElement](#webdriverwebelement) | A WebElement. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to whether the two WebElements are equal. - - -##[webdriver.WebElement.prototype.getDriver](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1578) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebDriver](#webdriverwebdriver) | The parent driver for this instance. - - -##[webdriver.WebElement.prototype.toWireValue](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1586) - - - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that resolves to this element's JSON representation as defined by the WebDriver wire protocol. - - -##[webdriver.WebElement.prototype.findElement](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1613) - -Schedule a command to find a descendant of this element. If the element -cannot be found, a {@code bot.ErrorCode.NO_SUCH_ELEMENT} result will -be returned by the driver. Unlike other commands, this error cannot be -suppressed. In other words, scheduling a command to find an element doubles -as an assert that the element is present on the page. To test whether an -element is present on the page, use {@code #isElementPresent} instead. - -

The search criteria for an element may be defined using one of the -factories in the {@link webdriver.By} namespace, or as a short-hand -{@link webdriver.By.Hash} object. For example, the following two statements -are equivalent: -

-var e1 = element.findElement(By.id('foo'));
-var e2 = element.findElement({id:'foo'});
-
- -

You may also provide a custom locator function, which takes as input -this WebDriver instance and returns a {@link webdriver.WebElement}, or a -promise that will resolve to a WebElement. For example, to find the first -visible link on a page, you could write: -

-var link = element.findElement(firstVisibleLink);
-
-function firstVisibleLink(element) {
-  var links = element.findElements(By.tagName('a'));
-  return webdriver.promise.filter(links, function(link) {
-    return links.isDisplayed();
-  }).then(function(visibleLinks) {
-    return visibleLinks[0];
-  });
-}
-
- - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | !(webdriver.Locator|webdriver.By.Hash|Function) | The locator strategy to use when searching for the element. - - - - -###Returns - -Type | Description ---- | --- -![webdriver.WebElement](#webdriverwebelement) | A WebElement that can be used to issue commands against the located element. If the element is not found, the element will be invalidated and all scheduled commands aborted. - - -##[webdriver.WebElement.prototype.isElementPresent](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1669) - -Schedules a command to test if there is at least one descendant of this -element that matches the given search criteria. - - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | !(webdriver.Locator|webdriver.By.Hash|Function) | The locator strategy to use when searching for the element. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<boolean> | A promise that will be resolved with whether an element could be located on the page. - - -##[webdriver.WebElement.prototype.findElements](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1685) - -Schedules a command to find all of the descendants of this element that -match the given search criteria. - - - - -###Params - -Param | Type | Description ---- | --- | --- -locator | !(webdriver.Locator|webdriver.By.Hash|Function) | The locator strategy to use when searching for the elements. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise.<!Array.<!webdriver.WebElement>> | A promise that will resolve to an array of WebElements. - - -##[webdriver.WebElement.prototype.click](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1708) - -Schedules a command to click on this element. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the click command has completed. - - -##[webdriver.WebElement.prototype.sendKeys](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1720) - -Schedules a command to type a sequence on the DOM element represented by this -instance. -

-Modifier keys (SHIFT, CONTROL, ALT, META) are stateful; once a modifier is -processed in the keysequence, that key state is toggled until one of the -following occurs: -

    -
  • The modifier key is encountered again in the sequence. At this point the -state of the key is toggled (along with the appropriate keyup/down events). -
    • -
  • The {@code webdriver.Key.NULL} key is encountered in the sequence. When -this key is encountered, all modifier keys current in the down state are -released (with accompanying keyup events). The NULL key can be used to -simulate common keyboard shortcuts: -
    -    element.sendKeys("text was",
-                     webdriver.Key.CONTROL, "a", webdriver.Key.NULL,
-                     "now text is");
-    // Alternatively:
-    element.sendKeys("text was",
-                     webdriver.Key.chord(webdriver.Key.CONTROL, "a"),
-                     "now text is");
-
    • -
  • The end of the keysequence is encountered. When there are no more keys -to type, all depressed modifier keys are released (with accompanying keyup -events). -
    • -
-Note: On browsers where native keyboard events are not yet -supported (e.g. Firefox on OS X), key events will be synthesized. Special -punctionation keys will be synthesized according to a standard QWERTY en-us -keyboard layout. - - - - -###Params - -Param | Type | Description ---- | --- | --- -var_args | ...string | The sequence of keys to type. All arguments will be joined into a single sequence (var_args is permitted for convenience). - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when all keys have been typed. - - -##[webdriver.WebElement.prototype.getTagName](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1777) - -Schedules a command to query for the tag/node name of this element. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the element's tag name. - - -##[webdriver.WebElement.prototype.getCssValue](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1789) - -Schedules a command to query for the computed style of the element -represented by this instance. If the element inherits the named style from -its parent, the parent will be queried for its value. Where possible, color -values will be converted to their hex representation (e.g. #00ff00 instead of -rgb(0, 255, 0)). -

-Warning: the value returned will be as the browser interprets it, so -it may be tricky to form a proper assertion. - - - - -###Params - -Param | Type | Description ---- | --- | --- -cssStyleProperty | string | The name of the CSS style property to look up. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the requested CSS value. - - -##[webdriver.WebElement.prototype.getAttribute](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1813) - -Schedules a command to query for the value of the given attribute of the -element. Will return the current value, even if it has been modified after -the page has been loaded. More exactly, this method will return the value of -the given attribute, unless that attribute is not present, in which case the -value of the property with the same name is returned. If neither value is -set, null is returned (for example, the "value" property of a textarea -element). The "style" attribute is converted as best can be to a -text representation with a trailing semi-colon. The following are deemed to -be "boolean" attributes and will return either "true" or null: - -

async, autofocus, autoplay, checked, compact, complete, controls, declare, -defaultchecked, defaultselected, defer, disabled, draggable, ended, -formnovalidate, hidden, indeterminate, iscontenteditable, ismap, itemscope, -loop, multiple, muted, nohref, noresize, noshade, novalidate, nowrap, open, -paused, pubdate, readonly, required, reversed, scoped, seamless, seeking, -selected, spellcheck, truespeed, willvalidate - -

Finally, the following commonly mis-capitalized attribute/property names -are evaluated as expected: -

    -
  • "class" -
  • "readonly" -
- - - - -###Params - -Param | Type | Description ---- | --- | --- -attributeName | string | The name of the attribute to query. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the attribute's value. The returned value will always be either a string or null. - - -##[webdriver.WebElement.prototype.getText](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1850) - -Get the visible (i.e. not hidden by CSS) innerText of this element, including -sub-elements, without any leading or trailing whitespace. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the element's visible text. - - -##[webdriver.WebElement.prototype.getSize](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1863) - -Schedules a command to compute the size of this element's bounding box, in -pixels. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the element's size as a {@code {width:number, height:number}} object. - - -##[webdriver.WebElement.prototype.getLocation](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1876) - -Schedules a command to compute the location of this element in page space. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to the element's location as a {@code {x:number, y:number}} object. - - -##[webdriver.WebElement.prototype.isEnabled](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1888) - -Schedules a command to query whether the DOM element represented by this -instance is enabled, as dicted by the {@code disabled} attribute. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with whether this element is currently enabled. - - -##[webdriver.WebElement.prototype.isSelected](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1901) - -Schedules a command to query whether this element is selected. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with whether this element is currently selected. - - -##[webdriver.WebElement.prototype.submit](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1913) - -Schedules a command to submit the form containing this element (or this -element if it is a FORM element). This command is a no-op if the element is -not contained in a form. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the form has been submitted. - - -##[webdriver.WebElement.prototype.clear](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1927) - -Schedules a command to clear the {@code value} of this element. This command -has no effect if the underlying DOM element is neither a text INPUT element -nor a TEXTAREA element. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when the element has been cleared. - - -##[webdriver.WebElement.prototype.isDisplayed](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1941) - -Schedules a command to test whether this element is currently displayed. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with whether this element is currently visible on the page. - - -##[webdriver.WebElement.prototype.getOuterHtml](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1953) - -Schedules a command to retrieve the outer HTML of this element. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the element's outer HTML. - - -##[webdriver.WebElement.prototype.getInnerHtml](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1972) - -Schedules a command to retrieve the inner HTML of this element. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved with the element's inner HTML. - - -##[webdriver.Alert](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#1983) - -Represents a modal dialog such as {@code alert}, {@code confirm}, or -{@code prompt}. Provides functions to retrieve the message displayed with -the alert, accept or dismiss the alert, and set the response text (in the -case of {@code prompt}). - - - - -###Params - -Param | Type | Description ---- | --- | --- -driver | ![webdriver.WebDriver](#webdriverwebdriver) | The driver controlling the browser this alert is attached to. -text | !(string|webdriver.promise.Promise) | Either the message text displayed with this alert, or a promise that will be resolved to said text. - - - - - -##[webdriver.Alert.prototype.getText](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2019) - -Retrieves the message text displayed with this alert. For instance, if the -alert were opened with alert("hello"), then this would return "hello". - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved to the text displayed with this alert. - - -##[webdriver.Alert.prototype.accept](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2030) - -Accepts this alert. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when this command has completed. - - -##[webdriver.Alert.prototype.dismiss](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2042) - -Dismisses this alert. - - - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when this command has completed. - - -##[webdriver.Alert.prototype.sendKeys](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2054) - -Sets the response text on this alert. This command will return an error if -the underlying alert does not support response text (e.g. window.alert and -window.confirm). - - - - -###Params - -Param | Type | Description ---- | --- | --- -text | string | The text to set. - - - - -###Returns - -Type | Description ---- | --- -!webdriver.promise.Promise | A promise that will be resolved when this command has completed. - - -##[webdriver.UnhandledAlertError](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2071) - -An error returned to indicate that there is an unhandled modal dialog on the -current page. - - - - -###Params - -Param | Type | Description ---- | --- | --- -message | string | The error message. -alert | ![webdriver.Alert](#webdriveralert) | The alert handle. - - - - - -##[webdriver.UnhandledAlertError.prototype.getAlert](https://code.google.com/p/selenium/source/browse/javascript/webdriver/webdriver.js#2088) - - - - - - - - -###Returns - -Type | Description ---- | --- -![webdriver.Alert](#webdriveralert) | The open alert. - +The API documentation was moved to: http://angular.github.io/protractor/#/api diff --git a/docs/browser-setup.md b/docs/browser-setup.md index 9e8a8fd25..54f97fc7a 100644 --- a/docs/browser-setup.md +++ b/docs/browser-setup.md @@ -1,19 +1,35 @@ -Setting up your Browser +Setting Up the 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. +Protractor works with [Selenium WebDriver](http://docs.seleniumhq.org/docs/03_webdriver.jsp), a browser automation framework. Selenium WebDriver supports several browser implementations or [drivers](http://docs.seleniumhq.org/docs/03_webdriver.jsp#selenium-webdriver-s-drivers) which are discussed below. + +Browser Support +--------------- +Protractor supports the two latest major versions of Chrome, Firefox, Safari, and IE. + +Please see [Browser Support](/docs/browser-support.md) for a full list of +supported browsers and known issues. + 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. +In your Protractor config file (see [referenceConf.js](/docs/referenceConf.js)), all browser setup is done within the `capabilities` object. This object is passed directly to the WebDriver builder ([builder.js](https://code.google.com/p/selenium/source/browse/javascript/webdriver/builder.js)). + + +See [DesiredCapabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities) for full information on which properties are available. + + +Using Mobile Browsers +--------------------- -See [the DesiredCapabilities Docs](https://code.google.com/p/selenium/wiki/DesiredCapabilities) for full information on which properties are available. +Please see the [Mobile Setup](/docs/mobile-setup.md) documentation for information on mobile browsers. -Switching to a browser besides Chrome -------------------------------------- -Simply set a different browser name in the capabilites object +Using Browsers Other Than Chrome +-------------------------------- + +To use a browser other than Chrome, simply set a different browser name in the capabilities object. ```javascript capabilities: { @@ -21,11 +37,13 @@ capabilities: { } ``` -You may need to install a separate binary to run another browser, such as IE or Android. +You may need to install a separate binary to run another browser, such as IE or Android. For more information, see [SeleniumHQ Downloads](http://docs.seleniumhq.org/download/). + -### Adding chrome-specific options +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: +Chrome options are nested in the `chromeOptions` object. A full list of options is at the [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/capabilities) site. For example, to show an FPS counter in the upper right, your configuration would look like this: ```javascript capabilities: { @@ -35,12 +53,12 @@ capabilities: { } }, ``` -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 + +Testing Against Multiple Browsers --------------------------------- -If you would like to test against multiple browsers at once, use the multiCapabilities configuration option. +If you would like to test against multiple browsers, use the `multiCapabilities` configuration option. ```javascript multiCapabilities: [{ @@ -50,288 +68,59 @@ multiCapabilities: [{ }] ``` -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 |[#778](https://github.com/angular/protractor/issues/778), 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. +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. -iPhone: -```javascript -exports.config = { - seleniumAddress: 'http://localhost:4723/wd/hub', - specs: [ - 'basic/*_spec.js' - ], +Using Multiple Browsers in the Same Test +---------------------------------------- +If you are testing apps where two browsers need to interact with each other (e.g. chat systems), you can do that with protractor by dynamically creating browsers on the go in your test. Protractor exposes a function in the `browser` object to help you achieve this: `browser.forkNewDriverInstance(opt_useSameUrl, opt_copyMockModules)`. +Calling this will return a new independent browser object. The first parameter in the function denotes whether you want the new browser to start with the same url as the browser you forked from. The second parameter denotes whether you want the new browser to copy the mock modules from the browser you forked from. - 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', +browser.get('http://www.angularjs.org'); +browser.addMockModule('moduleA', "angular.module('moduleA', []).value('version', '3');"); - specs: [ - 'basic/*_spec.js' - ], +// To create a new browser. +var browser2 = browser.forkNewDriverInstance(); - chromeOnly: false, +// To create a new browser with url as 'http://www.angularjs.org': +var browser3 = browser.forkNewDriverInstance(true); - capabilities: { - browserName: '', - device: 'iPad', - app: 'safari', - deviceName: 'iPad Simulator' - }, +// To create a new browser with mock modules injected: +var browser4 = browser.forkNewDriverInstance(false, true); - 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 +// To create a new browser with url as 'http://www.angularjs.org' and mock modules injected: +var browser4 = browser.forkNewDriverInstance(true, true); ``` -###### 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. +Now you can interact with the browsers. However, note that the globals `element`, `$`, `$$` and `browser` are all associated with the original browser. In order to interact with the new browsers, you must specifically tell protractor to do so like the following: ```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} +var element2 = browser2.element; +var $2 = browser2.$; +var $$2 = browser2.$$; +element2(by.model(...)).click(); +$2('.css').click(); +$$2('.css').click(); ``` -* Configure protractor, i.e. +Protractor will ensure that commands will automatically run in sync. For example, in the following code, `element(by.model(...)).click()` will run before `browser2.$('.css').click()`: ```javascript -exports.config = { - seleniumAddress: 'http://localhost:4444/wd/hub', - - specs: [ - 'basic/*_spec.js' - ], +browser.get('http://www.angularjs.org'); +browser2.get('http://localhost:1234'); - chromeOnly: false, - - capabilities: { - 'browserName': 'android' - }, - - baseUrl: 'http://10.0.2.2:' + (process.env.HTTP_PORT || '8000') -}; +browser.sleep(5000); +element(by.model(...)).click(); +browser2.$('.css').click(); ``` -*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 +Setting up PhantomJS +-------------------- +_Note: We recommend against using PhantomJS for tests with Protractor. There are many reported issues with PhantomJS crashing and behaving differently from real browsers._ -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`. +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 local install run: `npm install phantomjs`. Add phantomjs to the driver capabilities, and include a path to the binary if using local installation: ```javascript @@ -342,25 +131,12 @@ capabilities: { * 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', + 'phantomjs.binary.path': require('phantomjs').path, /* - * 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 + * Command line args to pass to ghostdriver, phantomjs's browser driver. + * See https://github.com/detro/ghostdriver#faq */ - 'phantomjs.cli.args':['--logfile=PATH', '--loglevel=DEBUG'] + 'phantomjs.ghostdriver.cli.args': ['--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(); -``` diff --git a/docs/browser-support.md b/docs/browser-support.md new file mode 100644 index 000000000..61ce3c729 --- /dev/null +++ b/docs/browser-support.md @@ -0,0 +1,23 @@ +Browser Support +=============== +Protractor supports the two latest major versions of Chrome, Firefox, Safari, and IE. These are used in Protractor's own suite of tests. You can view the current status [on Travis](https://travis-ci.org/angular/protractor). + +Note that because Protractor uses WebDriver to drive browsers, any issues with WebDriver implementations (such as FireFoxDriver, ChromeDriver, and IEDriver) will show up in Protractor. The chart below links to major known issues. You can search through all WebDriver issues at [the Selenium issue tracker](https://code.google.com/p/selenium/issues/list). + + +| Driver | Support | Known Issues | +|------------------------|--------------|-----------------| +|ChromeDriver |Yes |[Link](https://github.com/angular/protractor/labels/browser%3A%20chrome) | +|FirefoxDriver |Yes |[Link](https://github.com/angular/protractor/labels/browser%3A%20firefox) | +|SafariDriver |Yes |[Link](https://github.com/angular/protractor/labels/browser%3A%20safari) | +|IEDriver |Yes |[Link](https://github.com/angular/protractor/labels/browser%3A%20IE) | +|OperaDriver |No | | +|ios-Driver |No | | +|Appium - iOS/Safari |Yes* |[Link](https://github.com/angular/protractor/labels/browser%3A%20iOS%20safari) | +|Appium - Android/Chrome |Yes* |[Link](https://github.com/angular/protractor/labels/browser%3A%20android%20chrome) | +|Selendroid |Yes* | | +|PhantomJS / GhostDriver |** |[Link](https://github.com/angular/protractor/labels/browser%3A%20phantomjs) | + +(*) These drivers are not yet in the Protractor smoke tests. + +(**) We recommend against using PhantomJS for tests with Protractor. There are many reported issues with PhantomJS crashing and behaving differently from real browsers. diff --git a/docs/components.png b/docs/components.png new file mode 100644 index 000000000..a8107f6d2 Binary files /dev/null and b/docs/components.png differ diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 9607d440b..000000000 --- a/docs/contributing.md +++ /dev/null @@ -1,29 +0,0 @@ -Contributing to Source Code -=========================== - -Loosely, follow the [Angular contribution rules](http://docs.angularjs.org/misc/contribute). - -Protractor specific rules -------------------------- - - * JavaScript style should generally follow the [Google JS style guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml). - * Wrap code at 80 chars. - * Document public methods with jsdoc. - * Be consistent with the code around you! - -Commit Messages ---------------- - -Protractor follows AngularJS's [commit message format](https://docs.google.com/a/google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#heading=h.z8a3t6ehl060). - -In summary, this style is - - (): - - - -