web4cucumber 0.0.2

data/README.md

@@ -0,0 +1,250 @@
+The main filosophy behind this project is:
+Separate the data from the logic as much as you possibly can. Have you had to
+go through a tremendous ruby module with hundreds of methods which click
+buttons, input text in form fields, randomly wait (probably, till the page is
+loaded) and randomly take screenshots? Have you dreamed to have a way to store
+test data in a separate simple text files and feed them to the cucumber? 
+Or maybe you have hundreds of scenarios looking like this: 
+``` 
+ When I click the element ":id=>'click_me'"
+ And I write "hello" in the form with ":id=>'topic'"
+ And I write "Blahblahblah" in the form with ":id=>'body'"
+ And I click the element ":id=>'submit'"
+ Then the page shuold contain "Success"
+```
+And you sometimes ask yourselves "Is it a cucumber way to write scenarios like
+this?" Well the answer is no. Probably, all you need is to write a couple of
+steps instead:
+```
+ When I create a blogpost with:
+  |title|body|
+  |hello|Blahblahblah|
+ Then the step should succeed
+```
+And have a simple yaml file describing the corresponding webpage, that would
+look like this:
+```
+blogpost_create:
+  pages:
+    - 'blogpost_create_page'
+blogpost_create_page:
+  url: '/blogposts/new'
+  expected_fields:
+    title:
+      type: 'textfield'
+      selector:
+        id: 'topic'
+    body:
+      type: 'textfield'
+      selector:
+        id: 'body'
+  commit:
+    selector:
+      id: 'commit'
+```
+This library implements an abstraction layer between cucumber logic and Watir
+webdriver. Using this library you no longer need to write the Watir-aware Ruby
+code for low-level browser interaction. Instead you describe your pages and
+actions to be performed in Web UI of your product in simple yaml-formatted
+files. This approach allows you to separate the application data (html
+properties of page elements) from test logic. 
+
+How to use this? 
+
+- Add `gem 'Web4Cucumber'` to you Gemfile and run `bundle install`
+- In your project in one of your lib/*.rb files add `require "Web4Cucumber"` and inherit your own class from Web4Cucumber one, like this:
+```
+class Web < Web4Cucumber
+  def initialize(options)
+  super(options)
+  # Add here some code specific to your project, like 
+  # @@logged_in = false
+end
+```
+
+- In your features/support/env.rb in Before hook instatiate your beautiful class:
+```
+  options = {
+    :base_url => "http://base_url_of_your_project",
+    :browser => :firefox, # or :chrome. Other browsers are not supported yet
+    :rules_path => "path_to_the_folder_with_your_yaml_files",
+    :logger => @logger 
+    # You need to pass an object that will do the logging for you. I believe you have it implemented.
+    # If not, please take a look in the examples/testproject folder.
+  }
+  @web = Web.new(options)
+
+```
+From now on you will have @web, an instance of Web4Cucumber class with a bunch of convenient methods for high-level interactions with the browser, and, a browser running by default in the headless mode. For development and debugging purposes, however I recommend setting DEBUG_WEB environmental variable to *true* so that you will be presented with a visible browser window.
+
+- Once this preparation is done, let's try to understand how to write yaml files. The key concept Web4Cucumber is built around is an *action*. 
+Action is any set of user actions you want to automate, it could be web search, form submissions, data upload etc. An action is described in a yaml file with the following structure:
+
+```
+our_test_action:
+  pages:
+    - 'first_page'
+    - 'second_page'
+  final_checkpoints:
+    alert_success:
+      selector:
+        text: 'You have successfully performed whatever you intended'
+
+first_page:
+  url: '/some_relative_path/testme'
+  expected_fields:
+     field_one_on_page_one:
+       type: textfield
+       selector:
+         id: 'i-am-field-1'
+     field_two_on_page_one:
+       type: textfield
+       selector:
+         class: 'generic-field-2-class'
+  checkpoints:
+    sometext:
+      selector:
+        text: 'I am text one on page one'
+    someothertext:
+      selector:
+        text: 'I am text two on page one'
+  commit:
+    selector:
+      text: 'Click me'
+
+second_page:
+  sleep 2 # wait 2 seconds till the page is loaded
+  expected_fields:
+    field_one_on_page_two:
+      type: filefield
+      selector:
+        id: 'upload-something'
+    field_two_on_page_two:
+      type: textfield
+      selector:
+        xpath '//*[@id="fancy_something"]/span'
+      def_value: 'If you dont pass :field_two_on_page_two value, this text will go there'
+  checkpoints:
+    sometext:
+      selector:
+        text: 'I am text one on page two'
+    someothertext:
+      selector:
+        text: 'I am text two on page two'
+  negative_checkpoints:
+    error_message:
+      selector:
+        text: 'I am a critical error message! Wish you never see me on this page!'
+  commit:
+    scroll: true 
+    # sometimes the element you need is outside the area of the virtual viewport
+    # so webdriver is unable to interact with it. Use this keyword to execute a simple 
+    # javascript *scroll_into_view* function
+    selector:
+      text: 'Click me too'
+``` 
+If you take a closer look at this yaml structure, you'll notice that it describes describes two web pages pages. The first one is accessed through relative url "/some_relative_path/testme" that is being appended to your project's base_url (used during Web initialization).
+The second page is accessed by clicking the "Click me" button on the first page. The yaml file describes 2 textfields on first page and one textfield and one filefield on the second page. It also describes checkpoints - elements whose presence will be asserted during the action execution. We can provide default values for textfields right inside the yaml with the *def_value* keyword. Now the most interesting question: how do we use that?
+
+- The whole workflow would look like this. You would create your step:
+
+```
+When I run my beautiful action with:
+  |option                |value           |
+  |field_one_on_page_one |some text       |
+  |field_two_on_page_one | some other text|
+  |field_one_on_page_two | lib/files/myfile| 
+  # We remember that field_one_on_page_two is a filefield
+  # And we leave default value for second field on the page two.
+```
+Then you would write your step definition:
+```
+When /^I run my beautiful action with:$/ do |table|
+  options = {}
+  table.rows.each do |row|
+    options[row[0].to_sym] = row[1]
+  end
+  @result = @web.run_action(:our_test_action, options)
+end
+```
+As you can see, field_names declared in the yaml files, like *field_one_on_page_one* are used as keys in the hash, passed to the *@web.run_action* method as the second parameter. First parameter being the name of the action also declared in the yaml file.
+If you then inspect the @result object then ideally you would get something like this:
+```
+pp @result
+{:result=>true,
+ :failed_positive_checkpoints=>[],
+ :failed_negative_checkpoints=>[],
+ :errors=>[]}
+
+```
+If something went wrong and the webdriver was unable to find some checkpoints or other fields described in the yaml file, then the @result[:result] would be changed to *false* and @result[:failed_positive_checkpoints] array will be populated with the elements that were not found, @result[:failed_negative_checkpoints] - with elements you described in *negative_checkpoints* and @result[:errors] - with exception messages. Also, a *screenshots* folder will be created in your working directory, containing browser screenshot of the page that caught an error.
+
+Now we have to master yaml file creation in details.
+The structure of yaml files supported by Web4Cucumber library is quite flexible. You could store page descriptions separately from action descriptions, or you could store all your actions in one files, only make sure each action has a precide list of corresponding pages in exactly the same order that they appear during action execution. Besides list of pages only one keyword is supported under an action:
+*final_checkpoints*. This is a list of elements whose presence we expect once the action is finished.
+
+The key part of an *action* is a *page*. The following keywords can be used under the page description:
+1. expected_fields 
+2. checkpoints
+3. negative_checkpoints
+4. links
+5. base_url
+6. url
+7. sleep
+8. commit
+
+- *expected_fields* is a section where field descriptions go. Field structure will be discussed in more details later.
+- *checkpoints*, as was mentioned above, is a list of named web elements you expect to be present on a web page.
+- *negative_checkpoints*  similarly a list of named elements you do not expect on a page.
+- *links* Is a list of links on a page that need to be checked in a web crawler kind of way. For each link you specify the selector by which the link can be accessed and a number of checkpoints (web elements) you wish to check on a page accesible via that particular link. A typycal link section of a page would look like this:
+```
+  :links:
+    :getstarted:
+      :selector:
+        :text: "Get Started"
+      :checkpoints:
+        :getstarted:
+          :selector:
+            :text: "Getting Started"
+    :securitypolicy:
+      :selector:
+        :text: "Security Policy"
+      :checkpoints:
+        :securityinformation:
+          :selector:
+            :text: "Security Information"
+```
+In this example webdriver would click first on a link with test "Get Started", check that the page has an element with text "Get Started", then get back, click on the link with text "Security Policy", check that the page has an element with text "Security Information", then again get back.  
+- *base_url* - needed when you need to perform some action on a third-party software (for integration cases for example)
+- *url* - a relative url path of the page (base_url for your project is passed to the Web4Cucumber class during instance initialization)
+You can have a variable part of relative url, embraced between angle brackets. For example, if you have "/blog/<blogtype>/new" url in your yaml file and then pass {:blogtype=>'public'} in your options to the @web.run_action method, the webdriver will access the /blog/public/new relative url. 
+- *sleep* - a sleep interval in seconds, how long to wait before doing anything on this page: useful for slow loading pages
+- *commit* - well this is a commit button - the one you normally click to submit a form. The only tricky part about commit comes when the page presents you with a javascript popup. In this case the commit section would look like this:
+```
+commit:
+  type: alert
+```
+that's it!
+
+The last thing needed to be mentioned is the structure of the *field* itself. The *field* is mapped to a key in *options* passed to the @web.run_action method through it's name. That means, you pass a text to the particular textfield in the following way:
+1. Describe the field in the yaml file
+```
+expected_fields:
+  login:
+    type: 'textfield'
+    selector:
+      id: 'user-login'
+```
+2. pass the value:
+
+```@web.run_action(:some_action_name, {:login=>'username@example.com', <...other_options_go_here...>})```
+That's it.
+Different elemet types get treated differently by webdriver, textfields can not be clicked the way buttons do, so you need to provide element type. The following types are supported:
+- select - a dropdown list. You need to pass the element value
+- checkbox - self-explanatory
+- radio - same here
+- textfield - you can provide a text that will be inputted in this textfield
+- textarea - self-explanatory
+- filefield - provide a full path to the file you would upload here
+- a  -link
+- element any element that can be simply clicked. No need to provide the type in this case, it will be implied by default.

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/examples/testproject/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+gem 'json'
+gem 'cucumber'
+gem 'watir-webdriver'
+gem 'web4cucumber'
+gem 'rspec-expectations'
+gem 'debugger'
+gem 'byebug'
+gem 'headless'
+gem 'pry'

data/examples/testproject/Gemfile.lock

@@ -0,0 +1,59 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    builder (3.2.2)
+    childprocess (0.5.5)
+      ffi (~> 1.0, >= 1.0.11)
+    coderay (1.1.0)
+    columnize (0.8.9)
+    cucumber (1.3.19)
+      builder (>= 2.1.2)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 2.12)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.2)
+    debugger (1.6.8)
+      columnize (>= 0.3.1)
+      debugger-linecache (~> 1.2.0)
+      debugger-ruby_core_source (~> 1.3.5)
+    debugger-linecache (1.2.0)
+    debugger-ruby_core_source (1.3.5)
+    diff-lcs (1.2.5)
+    ffi (1.9.6)
+    gherkin (2.12.2)
+      multi_json (~> 1.3)
+    headless (1.0.2)
+    json (1.8.2)
+    method_source (0.8.2)
+    multi_json (1.10.1)
+    multi_test (0.1.2)
+    pry (0.9.12.6)
+      coderay (~> 1.0)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    rspec-expectations (2.14.4)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rubyzip (1.1.7)
+    selenium-webdriver (2.44.0)
+      childprocess (~> 0.5)
+      multi_json (~> 1.0)
+      rubyzip (~> 1.0)
+      websocket (~> 1.0)
+    slop (3.5.0)
+    watir-webdriver (0.6.11)
+      selenium-webdriver (>= 2.18.0)
+    web4cuke (0.0.1)
+    websocket (1.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cucumber
+  debugger
+  headless
+  json
+  pry
+  rspec-expectations
+  watir-webdriver
+  web4cuke

data/examples/testproject/features/example.feature

@@ -0,0 +1,12 @@
+Feature: example.feature
+  # We expect that you have an account at https://www.openshift.com/
+  # And that you have two environmental variables containing your 
+  # Openshift login and password: $OPENSHIFT_LOGIN and $OPENSHIFT_PASSWORD
+  Scenario: Login to Openshift web console
+    Given I am logged in to OpenShift web console
+    Then the url should contain "app/account"
+    When I run my beautiful action with:
+      |option                |value            |
+      |field_one_on_page_one |some text          |
+      |field_two_on_page_one | some other text|
+      |field_one_on_page_two| lib/files/myfile      |

data/examples/testproject/features/step_definitions/web.rb

@@ -0,0 +1,23 @@
+Given /^I am logged in to OpenShift web console$/ do
+  options = {}
+  options[:login] = ENV["OPENSHIFT_USER"]
+  options[:password] = ENV["OPENSHIFT_PASSWORD"]
+  @result = @web.login(options)
+  expect(@result[:result]).to be_true, "Failed to log in"
+end
+
+Then /^the url should contain "(.*?)"$/ do |urlpart|
+  url = @web.get_url
+  expect(url.include?(urlpart)).to be_true, "Failed to find #{urlpart} in page url"
+  
+end
+
+When /^I run my beautiful action with:$/ do |table|
+  options = {}
+  table.rows.each do |row|
+    options[row[0].to_sym] = row[1]
+  end
+  @result = @web.run_action(:our_test_action, options)
+end
+
+

data/examples/testproject/features/support/env.rb

@@ -0,0 +1,20 @@
+#!/usr/bin/env ruby
+require 'rspec/expectations'
+LIB_PATH = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
+$LOAD_PATH.unshift(LIB_PATH)
+require "web"
+require "log"
+
+Before do |scenario|
+  options = {
+    :base_url => "https://openshift.com",
+    :browser => :firefox,
+    :rules_path => File.expand_path(File.join(File.dirname(__FILE__), '..', '..', 'lib', 'web')),
+    :logger => Log.new
+  }
+  @web = Web.new(options)
+end
+
+After do |scenario|
+  @web.finalize
+end

data/examples/testproject/lib/log.rb

@@ -0,0 +1,17 @@
+class Log
+  def initialize
+  end
+
+  def info(text)
+    puts text
+  end
+
+  def warn(text)
+    puts text
+  end
+
+  def error(text)
+    puts text
+  end
+
+end

data/examples/testproject/lib/web.rb

@@ -0,0 +1,19 @@
+require "web4cucumber"
+
+class Web < Web4Cucumber
+  def initialize(options)
+    super(options)
+    @@logged_in = false
+  end
+
+  def login(options)
+    unless options.keys == [:login, :password]
+      raise "Please povide both :login and :password options"
+    end
+    result = run_action(:login, options)
+    if result[:result] == true
+      @@logged_in = true
+    end
+    return result
+  end
+end

data/examples/testproject/lib/web/check_community_header.yaml

@@ -0,0 +1,117 @@
+:check_community_header:
+  :pages:
+    - "check_community_header_page"
+:check_community_header_page:
+  :url: '/community'
+
+  :checkpoints:
+    :products:
+      :selector:
+        :text: "Products"
+    :getinvolved:
+      :selector:
+        :text: "Get Involved"
+    :devcenter:
+      :selector:
+        :text: "Developer Center"
+    :support:
+      :selector:
+        :text: "Support"
+    :partners:
+      :selector:
+        :text: "Partners"
+    :community:
+      :selector:
+        :text: "Community"
+    :connect:
+      :selector:
+        :text: "Connect"
+    :about:
+      :selector:
+        :text: "About"
+    :getstarted:
+      :selector:
+        :text: "Get Started"
+    :status:
+      :selector:
+        :text: "Status"
+    :stackoverflow:
+      :selector:
+        :text: "Stack Overflow"
+    :premiumplans:
+      :selector:
+        :text: "Premium Plans"
+    :events:
+      :selector:
+        :text: "Events"
+    :blog:
+      :selector:
+        :text: "Blog"
+    :securitypolicy:
+      :selector:
+        :text: "Security Policy"
+    :openshiftonirc:
+      :selector:
+        :text: "#openshift on IRC"
+    :newslettersignup:
+      :selector:
+        :text: "Join our Newsletter"
+    :careers:
+      :selector:
+        :text: "Careers"
+    :aboutredhat:
+      :selector:
+        :text: "About Red Hat"
+    :partnerprograms:
+      :selector:
+        :text: "Partner Programs"
+    :contactus:
+      :selector:
+        :text: "Contact Us"
+    :enterprisesalesinfo:
+      :selector:
+        :text: "Enterprise Sales Info"
+  :links:
+    :getstarted:
+      :selector:
+        :text: "Get Started"
+      :checkpoints:
+        :getstartedwithopenshift:
+          :selector:
+            :text: "Getting Started with OpenShift"
+    :securitypolicy:
+      :selector:
+        :text: "Security Policy"
+      :checkpoints:
+        :securityinformation:
+          :selector:
+            :text: "Security Information"
+    :blog:
+      :selector:
+        :text: "Blog"
+      :checkpoints:
+        :blog:
+          :selector:
+            :text: "Blog"
+    :newslettersignup:
+      :selector:
+        :text: "Join our Newsletter"
+      :checkpoints:
+        :blogupdates:
+          :selector:
+            :text: "Blog Updates"
+    :enterprisesalesinfo:
+      :selector:
+        :text: "Enterprise Sales Info"
+      :checkpoints:
+        :tryopenshiftenterprise:
+          :selector:
+            :text: "Try OpenShift Enterprise"
+    :partnerprograms:
+      :selector:
+        :text: "Partner Programs"
+      :checkpoints:
+        :findapartner:
+          :selector:
+            :text: "Find a Partner"
+