angular_webdriver 0.0.7 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 773f24595c7f7a746b7dac72ca67b1bb3169172e
-  data.tar.gz: 24cc4556436a5b24331643c1eac49e6dac68539a
+  metadata.gz: 36f37457d0ef4a33d6270ff82c314b816287f340
+  data.tar.gz: f322210de5d4c17b9cc69c544399f793f0e5f901
 SHA512:
-  metadata.gz: a3452bf11123a4c95bf9fc5debabd8b1f7c8168ec1cde4ef29fd2cb039d63f9e597028c66073cff16f8392eb6b66467af646108d9bb4486cc857e2cea0f217d2
-  data.tar.gz: e1357c868b83a4c9318d8c06e0e2d6b5b22669a88153bff792851abba9de032527d6748c1879f8647bb96adf618d1070e0a055e76cf7e6295c3d5eaa2d7e8c6c
+  metadata.gz: b26d552ec0240432af01e600c4936e5ecce7e014275168df066e3fb99d3b51e9db6b74b1c283730f29fe3d1ac393a29f8df42a5402349a0e6757410f1790c94f
+  data.tar.gz: 6322971ae12c782a76058ba8355e8ac1a526ff9dfbf4fab50180080eb5017faa4537ef4bb217bf7db883a0311616b43a1c8dcc91bd0336f98bc859e087f87225

data/.gitignore

@@ -35,3 +35,6 @@ build/
 
 # unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
 .rvmrc
+
+chromedriver
+*.zip

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "protractor"]
+	path = protractor
+	url = https://github.com/angular/protractor.git

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,32 @@
+language: node_js
+node_js:
+  - stable
+sudo: false
+cache: 
+  bundler: true
+  directories:
+    - protractor/node_modules
+before_install: 
+  - rvm install 2.2.2
+  - rvm --default use 2.2.2
+  - gem update --remote bundler
+install:
+  - bundle install --retry=3
+before_script:
+  - export DISPLAY=:99.0
+  - sh -e /etc/init.d/xvfb start
+  - ruby -v
+  - cd protractor
+  - npm install
+  - cd testapp
+  - npm start & # must background the webserver
+  - cd ..; cd .. # return to project root
+  - sleep 5 # wait for servers to start
+script:
+  - bundle exec thor gen     # regenerate every time before testing
+  - bundle exec thor compare # ensure ported protractor tests stay up to date 
+  - bundle exec thor spec
+notifications:
+  email:
+    on_success: never
+    on_failure: never

data/Gemfile

@@ -1,3 +1,5 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem 'thor' # enable: bundle exec thor spec

data/Thorfile

@@ -1,6 +1,38 @@
+require 'rubygems'
 require 'appium_thor'
 
 Appium::Thor::Config.set do
   gem_name 'angular_webdriver'
   github_owner 'bootstraponline'
-end
+end
+
+# Must use '::' otherwise Default will point to Thor::Sandbox::Default
+# Debug by calling Thor::Base.subclass_files via Pry
+#
+# https://github.com/erikhuda/thor/issues/484
+#
+class ::Default < Thor
+  desc 'spec', 'Run RSpec tests'
+  def spec
+    exec 'rspec spec'
+  end
+
+  desc 'gen', 'Generate client_side_scripts.rb'
+  def gen
+    commands = [
+      'node ./gen/scripts_to_json.js',
+      'ruby ./gen/json_to_rb.rb'
+    ].join ';'
+    exec commands
+
+    # only the first exec will work so we can't use two of them.
+  end
+
+  desc 'compare', 'Compare protractor JS specs to ruby specs'
+  def compare
+    commands = [
+      'rspec ./gen/compare_specs.rb'
+    ].join ';'
+    exec commands
+  end
+end

data/angular_webdriver.gemspec

@@ -14,12 +14,19 @@ Gem::Specification.new do |s|
   s.homepage      = 'https://github.com/bootstraponline/angular_webdriver'
   s.require_paths = ['lib']
 
-  s.add_runtime_dependency 'selenium-webdriver', '>= 2.45.0'
+  # The selenium-webdriver and watir-webdriver patches may require updating
+  # as the gems change. To ensure angular_webdriver continues to work
+  # exact versions of both are used.
+  s.add_runtime_dependency 'selenium-webdriver', '= 2.46.2'
+  s.add_runtime_dependency 'watir-webdriver', '= 0.7.0'
+  s.add_runtime_dependency 'webdriver_utils', '>= 0.0.5'
 
   s.add_development_dependency 'rspec', '>= 3.2.0'
   s.add_development_dependency 'appium_thor', '>= 0.0.7'
   s.add_development_dependency 'pry', '>= 0.10.1'
-  s.add_development_dependency 'webdriver_utils', '>= 0.0.3'
+  s.add_development_dependency 'trace_files', '~> 0.0.2'
 
-  s.files = `git ls-files`.split "\n"
+  s.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(gen|test|spec|features|protractor)/})
+  end
 end

data/docs/overview.md

@@ -0,0 +1,101 @@
+# Overview
+
+angular_webdriver is a Ruby wrapper for Protractor's client side JavaScript.
+
+Features supported:
+
+- **Auto synchronization feature** - Protractor automatically 
+  runs the waitForAngular command before selected WebDriver actions.
+  See [sync](sync.md) for details.
+- **Protractor.root_element** -  The css selector for an element on which to find Angular.
+- **Protractor.ignore_sync** - If true, Protractor will not attempt to synchronize with
+  the page before performing actions.
+- **Protractor.base_url** - When set driver.get will resolve relative urls
+  against the base_url
+- **Protractor.client_side_scripts** - All of protractor's client side scripts
+  are available as strings
+- **Protractor.reset_url** - driver.get will use an appropriate reset url when 
+  synchronizing with the page
+- **Protractor.get** - Navigate to the given destination. Assumes that the page
+  being loaded uses Angular. driver.get uses protractor.get. Uses base_url,
+  reset_url, and waits for angular to load.
+- **Protractor.refresh** - Makes a full reload of the current page. Assumes
+  that the page being loaded uses Angular.
+- **Protractor.setLocation** - Browse to another page using in-page navigation.
+  Assumes that the page being loaded uses Angular.
+- **Protractor.getLocationAbsUrl** - Returns the current absolute url from
+  AngularJS. Waits for angular.
+- **Protractor.waitForAngular** - Waits for angular to finish loading.
+- **Protractor.executeAsyncScript_** - Same as driver.execute_async_script
+  but with comment for debugging.
+- **Protractor.executeScript_** - Same as driver.execute_script but with
+  comment for debugging.
+- **Protractor.debugger** - Injects client side scripts into 
+  window.clientSideScripts for debugging.
+- **Protractor.allowAnimations** - Control if animation is allowed on
+  the current underlying elements.
+- **element.evaluate** - Evaluate an Angular expression as if it were on the scope
+  of the given element.
+
+## Protractor semantics
+  
+The `by` syntax, such as `by.binding`, lazily finds elements.
+ 
+- `element(by.binding('slowHttpStatus'))` - This will not locate the element until
+the element is used (such as calling .value or explicitly invoking .locate)
+- `element.all(by.partialButtonText('text'))` - This will not locate the elements
+until `.to_a` is invoked.
+
+In addition to lazy locating, elements are always rediscovered. element.value
+will always first find the element and then get the value. The reason elements
+are rediscovered each time instead of cached is that Protrator relies on running
+waitForAngular before certain webdriver commands. For elements, the sync behavior
+is triggered when we find an element. If we didn't always rediscover elements then
+the element.value method wouldn't trigger a waitForAngular call and the page 
+could still be processing angular logic.
+  
+## Supported Protractor Locators
+ 
+Note these work the same as standard locators.
+You can find a single element (find_element), multiple elements (find_elements),
+and the finders are chainable (finding elements from a parent element). The protractor syntax
+(element/element.all) is also available as an alternative to find_element/find_elements.
+
+Client side script          | Protractor                                       | WebDriver
+                        --- |                                              --- | ---
+**binding**                 | `element(by.binding('slowHttpStatus')).locate`   | `driver.find_element(:binding, 'slowHttpStatus')`  
+**findByPartialButtonText** | `element.all(by.partialButtonText('text')).to_a` | `driver.find_elements(:findByPartialButtonText, 'slowHttpStatus')`
+**findByButtonText**        | `element.all(by.buttonText('Exact text')).to_a`  | `driver.find_elements(:buttonText, 'Exact text')`
+**findByModel**             | `element(by.model('username'))`                  | `driver.find_element(:model, 'username')`
+**findByOptions**           | `element.all(by.options('fruit')).to_a`          | `driver.find_elements(:options, 'fruit')`
+**findByCssContainingText** | `element.all(by.cssContainingText('#animals ul .pet', 'dog')).to_a` | `driver.find_elements(:cssContainingText, { cssSelector: '#animals ul .pet', searchText: 'dog' }.to_json)`
+**findRepeaterRows**        | `element(by.repeater('baz in days').row(0))`     | -
+**findAllRepeaterRows**     | `element(by.repeater('baz in days'));`           | -
+**findRepeaterElement**     | `element(by.repeater('baz in days').row(0).column('b'))` | -
+**findRepeaterColumn**      | `element(by.repeater('baz in days').column('b'))`        | -
+
+## By locators
+
+All the [Protractor by locators](http://angular.github.io/protractor/#/api?view=ProtractorBy) are supported.
+Camel case (by.deepCss) and snake case (by.deep_css) are both supported.
+
+- by.binding
+- by.exactBinding
+- by.partialButtonText
+- by.buttonText
+- by.model
+- by.options
+- by.cssContainingText
+- by.repeater
+- by.exactRepeater
+- by.deepCss
+
+## Waiting
+
+Implicit waits are [unreliable](http://stackoverflow.com/questions/15164742/combining-implicit-wait-and-explicit-wait-together-results-in-unexpected-wait-ti#answer-15174978)
+due to being baked into the remote driver. Waiting in angular_webdriver has been
+reimplemented client side to avoid flakiness.
+ 
+**driver.set_max_wait(5)** - wait up to 5 seconds for an exception to not be raised
+                             when finding an element.
+**driver.max_wait_seconds** - The max wait amount (default 0) in seconds.

data/docs/sync.md

@@ -0,0 +1,53 @@
+# Sync
+
+Protractor provides two methods to synchronize with AngularJS. The first is
+`testForAngular`. `testForAngular` is exclusively used for protractor's custom
+get method for pausing the angular bootstrap before injecting mocks then resuming
+the bootstrap.
+
+There are better ways to mock angular apps than injecting them via selenium tests.
+The mock feature of Protractor is not planned to be implemented in angular_webdriver
+unless a compelling use case is found. The `testForAngular` client side script
+remains available however it's not recommended for use.
+
+## waitForAngular
+
+`waitForAngular` is protractor's second method for syncing with Angular.
+`waitForAngular` is automatically invoked before selected webdriver commands
+to eliminate the need for waits. Any command that interacts with an element,
+such as element.value, will cause that element to be located again. When an
+element is requested to be located, the `waitForAngular` command is 
+run before locating the element.
+
+The following webdriver commands execute `waitForAngular` before running.
+The single exception is `get`, in that case `waitForAngular` executes after
+the `get` command completes.
+
+Internal Command     | Driver command
+                 --- | ---
+`:getCurrentUrl`     | driver.current_url
+`:get`               | driver.get 'http://www.angularjs.org'
+`:refresh`           | driver.navigate.refresh
+`:getPageSource`     | driver.page_source
+`:getTitle`          | driver.title
+`:findElement`       | driver.find_element(:tag_name, 'html')
+`:findElements`      | driver.find_elements(:tag_name, 'html')
+`:findChildElement`  | driver.find_element(:tag_name, 'html').find_element(:xpath, '//html') 
+`:findChildElements` | driver.find_element(:tag_name, 'html').find_elements(:xpath, '//html')
+ 
+The following custom Protractor commands also automatically execute `waitForAngular`
+ 
+Protractor Command             | Note
+                           --- | ---
+`Protractor.get 'url'`         | driver.get redirects to protractor.get  
+`Protractor.setLocation 'url'` | Note this is unrelated to the selenium setLocation for geographic position
+`Protractor.getLocationAbsUrl` |
+
+Sync can be toggled by running:
+
+- `protractor.ignore_sync = true` Don't run waitForAngular
+- `protractor.ignore_sync = false` Run waitForAngular
+
+To get always get a url without syncing use:
+
+`protractor.driver_get 'url'`

data/lib/angular_webdriver/protractor/by.rb

@@ -0,0 +1,331 @@
+module AngularWebdriver
+  class By
+    class << self
+
+      #
+      # Selenium locators
+      #
+
+      def class what
+        { class: what }
+      end
+
+      def class_name what
+        { class_name: what }
+      end
+
+      def css what
+        { css: what }
+      end
+
+      def id what
+        { id: what }
+      end
+
+      def link what
+        { link: what }
+      end
+
+      def link_text what
+        { link_text: what }
+      end
+
+      def name what
+        { name: what }
+      end
+
+      def partial_link_text what
+        { partial_link_text: what }
+      end
+
+      def tag_name what
+        { tag_name: what }
+      end
+
+      def xpath what
+        { xpath: what }
+      end
+
+      #
+      # Protractor locators
+      # See protractor/lib/locators.js
+      #
+
+      #  Find an element by binding. Does a partial match, so any elements bound to
+      #  variables containing the input string will be returned.
+      #
+      #  Note: For AngularJS version 1.2, the interpolation brackets, usually {{}},
+      #  are allowed in the binding description string. For Angular version 1.3, they
+      #  are not allowed, and no elements will be found if they are used.
+      #
+      #  @view
+      #  <span>{{person.name}}</span>
+      #  <span ng-bind="person.email"></span>
+      #
+      #  @example
+      #  span1 = element(by.binding('person.name'))
+      #  expect(span1.text).to eq('Foo')
+      #
+      #  span2 = element(by.binding('person.email'))
+      #  expect(span2.text.to eq('foo@bar.com')
+      #
+      #  # You can also use a substring for a partial match
+      #  span1alt = element(by.binding('name'))
+      #  expect(span1alt.text).to eq('Foo')
+      #
+      #  # This works for sites using Angular 1.2 but NOT 1.3
+      #  deprecatedSyntax = element(by.binding('{{person.name}}'))
+      #
+      #  @param binding_descriptor <String>
+      #  @return { binding: binding_descriptor }
+      def binding binding_descriptor
+        { binding: binding_descriptor }
+      end
+
+      # Find an element by exact binding.
+      #
+      # @view
+      # <span>{{ person.name }}</span>
+      # <span ng-bind="person-email"></span>
+      # <span>{{person_phone|uppercase}}</span>
+      #
+      # @example
+      # expect(element(by.exactBinding('person.name')).present?).to eq(true);
+      # expect(element(by.exactBinding('person-email')).present?).to eq(true);
+      # expect(element(by.exactBinding('person')).present?).to eq(false);
+      # expect(element(by.exactBinding('person_phone')).present?).to eq(true);
+      # expect(element(by.exactBinding('person_phone|uppercase')).present?).to eq(true);
+      # expect(element(by.exactBinding('phone')).present?).to eq(false);
+      #
+      #  @param binding_descriptor <String>
+      #  @return { exactBinding: binding_descriptor }
+      def exactBinding binding_descriptor
+        { exactBinding: binding_descriptor }
+      end
+
+      # Find a button by partial text.
+      #
+      # @view
+      # <button>Save my file</button>
+      #
+      # @example
+      # element(by.partialButtonText('Save'))
+      #
+      # @param search_text <String>
+      # @return { partialButtonText: search_text }
+      def partialButtonText search_text
+        { partialButtonText: search_text }
+      end
+
+      # Find a button by text.
+      #
+      # @view
+      # <button>Save</button>
+      #
+      # @example
+      # element(by.buttonText('Save'))
+      #
+      # @param search_text <String>
+      # @return {buttonText: search_text }
+      def buttonText search_text
+        { buttonText: search_text }
+      end
+
+      # Find an element by ng-model expression.
+      #
+      # @alias by.model(modelName)
+      # @view
+      # <input type="text" ng-model="person.name">
+      #
+      # @example
+      # input = element(by.model('person.name'))
+      # input.send_keys('123')
+      # expect(input.value).to eq('Foo123')
+      #
+      # @param model_expression <String>  ng-model expression.
+      # @return { model: model_expression }
+      def model model_expression
+        { model: model_expression }
+      end
+
+      #  Find an element by ng-options expression.
+      #
+      #  @alias by.options(optionsDescriptor)
+      #  @view
+      #  <select ng-model="color" ng-options="c for c in colors">
+      #    <option value="0" selected="selected">red</option>
+      #    <option value="1">green</option>
+      #  </select>
+      #
+      #  @example
+      #  allOptions = element.all(by.options('c for c in colors')).to_a
+      #  expect(allOptions.length).to eq(2);
+      #  firstOption = allOptions.first
+      #  expect(firstOption.text).to eq('red')
+      #
+      #  @param options_descriptor <String> ng-options expression.
+      #  @return { options: options_descriptor }
+      def options options_descriptor
+        { options: options_descriptor }
+      end
+
+      #  Find elements by CSS which contain a certain string.
+      #
+      #  @view
+      #  <ul>
+      #    <li class="pet">Dog</li>
+      #    <li class="pet">Cat</li>
+      #  </ul>
+      #
+      #  @example
+      #  # Returns the li for the dog, but not cat.
+      #  dog = element(by.cssContainingText('.pet', 'Dog'))
+      # @return { cssContainingText: { cssSelector: css_selector, searchText: search_text } }
+      def cssContainingText css_selector, search_text
+        # the "what" must be a string or watir will complain it's not a valid what.
+        # even if watir is patched to accept hashes, the what will be converted
+        # to a string by the time it's seen by selenium webdriver.
+        { cssContainingText: { cssSelector: css_selector, searchText: search_text }.to_json }
+      end
+
+      #  Find elements inside an ng-repeat.
+      #
+      #  @view
+      #  <div ng-repeat="cat in pets">
+      #    <span>{{cat.name}}</span>
+      #    <span>{{cat.age}}</span>
+      #  </div>
+      #
+      #  <div class="book-img" ng-repeat-start="book in library">
+      #    <span>{{$index}}</span>
+      #  </div>
+      #  <div class="book-info" ng-repeat-end>
+      #    <h4>{{book.name}}</h4>
+      #    <p>{{book.blurb}}</p>
+      #  </div>
+      #
+      #  @example
+      #  // Returns the DIV for the second cat.
+      #  secondCat = element(by.repeater('cat in pets').row(1));
+      #
+      #  // Returns the SPAN for the first cat's name.
+      #  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
+      #  ages = element.all(
+      #      by.repeater('cat in pets').column('cat.age'));
+      #
+      #  // Returns a promise that resolves to an array of WebElements containing
+      #  // all top level elements repeated by the repeater. For 2 pets rows resolves
+      #  // to an array of 2 elements.
+      #  rows = element.all(by.repeater('cat in pets'));
+      #
+      #  // Returns a promise that resolves to an array of WebElements containing all
+      #  // the elements with a binding to the book's name.
+      #  divs = element.all(by.repeater('book in library').column('book.name'));
+      #
+      #  // Returns a promise that resolves to an array of WebElements containing
+      #  // the DIVs for the second book.
+      #  bookInfo = element.all(by.repeater('book in library').row(1));
+      #
+      #  // Returns the H4 for the first book's name.
+      #  firstBookName = element(by.repeater('book in library').
+      #      row(0).column('book.name'));
+      #
+      #  // Returns a promise that resolves to an array of WebElements containing
+      #  // all top level elements repeated by the repeater. For 2 books divs
+      #  // resolves to an array of 4 elements.
+      #  divs = element.all(by.repeater('book in library'));
+      #
+      #  @param {string} repeatDescriptor
+      #  @return {{findElementsOverride: findElementsOverride, toString: Function|string}}
+      #
+      def repeater repeat_descriptor
+        ByRepeaterInner.new exact: false, repeat_descriptor: repeat_descriptor
+      end
+
+      # Find an element by exact repeater.
+      #
+      #  @view
+      #  <li ng-repeat="person in peopleWithRedHair"></li>
+      #  <li ng-repeat="car in cars | orderBy:year"></li>
+      #
+      #  @example
+      #  expect(element(by.exactRepeater('person in peopleWithRedHair')).present?)
+      #      .to eq(true);
+      #  expect(element(by.exactRepeater('person in people')).present?).to eq(false);
+      #  expect(element(by.exactRepeater('car in cars')).present?).to eq(true);
+      #
+      #  @param {string} repeatDescriptor
+      #  @return {{findElementsOverride: findElementsOverride, toString: Function|string}}
+      #
+      def exactRepeater repeat_descriptor
+        ByRepeaterInner.new exact: true, repeat_descriptor: repeat_descriptor
+      end
+
+      # Find an element by css selector within the Shadow DOM.
+      #
+      # @alias by.deepCss(selector)
+      # @view
+      # <div>
+      #   <span id="outerspan">
+      #   <"shadow tree">
+      #     <span id="span1"></span>
+      #     <"shadow tree">
+      #       <span id="span2"></span>
+      #     </>
+      #   </>
+      # </div>
+      # @example
+      # spans = element.all(by.deepCss('span'));
+      # expect(spans.count()).to eq(3);
+      def deepCss selector
+        # TODO: syntax will change from /deep/ to >>> at some point.
+        { css: '* /deep/ ' + selector }
+      end
+    end # class << self
+  end # class By
+end # module AngularWebdriver
+
+# Support camel and snake case for protractor compatibility
+# deepCss & deep_css
+AngularWebdriver::By.singleton_methods.each do |method_symbol|
+  by = AngularWebdriver::By
+  next if method_symbol == :yaml_tag # skip ruby core psych
+
+  method_name   = method_symbol.to_s
+  is_snake_case = method_name.include? '_'
+  is_camel_case = !!method_name.match(/[a-z][A-Z]/)
+
+  if is_snake_case # deep_css -> deepCss
+    camel_case = method_name.gsub(/([a-z\d])_([a-z])/) do
+      full, one, two = Regexp.last_match.to_a
+      "#{one}#{two.upcase}"
+    end
+    next if by.respond_to? camel_case
+    by.define_singleton_method camel_case do |*args|
+      by.method(method_symbol).call *args
+    end
+  elsif is_camel_case # deepCss -> deep_css
+    snake_case = method_name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+    next if by.respond_to? snake_case
+    by.define_singleton_method snake_case do |*args|
+      by.method(method_symbol).call *args
+    end
+  end
+end
+
+=begin
+> Selenium::WebDriver::SearchContext::FINDERS
+=> {:class=>"class name",
+ :class_name=>"class name",
+ :css=>"css selector",
+ :id=>"id",
+ :link=>"link text",
+ :link_text=>"link text",
+ :name=>"name",
+ :partial_link_text=>"partial link text",
+ :tag_name=>"tag name",
+ :xpath=>"xpath"}
+=end