howitzer 1.1.1 → 2.0.0

data/GETTING_STARTED.md

@@ -1,774 +0,0 @@
-Getting Started 
-===============
-
-Available Drivers
-------
-
-**Driver** is a universal interface for test runners against various web browsers. All driver implementations can be divided into 2 categories:
-
-* **Headless testing** – a browser emulation without a GUI (very useful on CI servers, e.g. Bamboo, TeamCity, Jenkins, etc.).
-* **Real browser testing** - an integration with real browsers through extensions, plugins, ActiveX, etc., (for local and cloud based testing, like SauceLabs, Testingbot, BrowserStack).
-
-Howitzer uses [Capybara](http://jnicklas.github.io/capybara/) for the driver management and configuration. All you need to do is to:
-
-  - specify the **driver** settings in the _config/default.yml_
-  - Specify a few extra settings for the selected driver.
-
-The table below gives an important information on the driver settings in Howitzer:
-
-<table>
-<thead>
-  <tr>
-    <th>Driver</th>
-    <th align="center">Category</th>
-    <th align="center">Setting name</th>
-    <th align="center">Setting type</th>
-    <th align="center">Description</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td>
-      <a href="http://phantomjs.org/">phantomjs</a>(<strong>default</strong>)<br/><br/>
-      <a href="https://github.com/teampoltergeist/poltergeist">poltergeist</a>
-    </td>
-    <td align="center">Headless</td>
-    <td align="center">
-      <strong>pjs_ignore_js_errors</strong><br/><br/>
-      <strong>pjs_ignore_ssl_errors</strong>
-    </td>
-    <td align="center">
-      Boolean <br/><br/>
-      Boolean
-    </td>
-    <td align="center">
-      if false, then raises exception on js error in app<br/>
-      if false, then ignores ssl warnings<br/>
-    </td>
-  </tr>
-  
-  <tr>
-    <td><a href="https://github.com/thoughtbot/capybara-webkit">webkit</a></td>
-    <td align="center">Headless</td>
-    <td align="center">-</td>
-    <td align="center">-</td>
-    <td align="center">Uncomment `gem 'capybara-webkit'` in Gemfile</td>
-  </tr>
-  <tr>
-    <td><a href="https://code.google.com/p/selenium/wiki/RubyBindings">selenium</a></td>
-    <td align="center">Real</td>
-    <td align="center"><strong>sel_browser</strong></td>
-    <td align="center">String</td>
-    <td align="center">Indicate one of the following browsers: iexplore (ie), firefox (ff), chrome, opera, safari.</td>
-  </tr>
-  <tr>
-      <td><a href="http://docs.seleniumhq.org/docs/07_selenium_grid.jsp">selenium_grid</a></td>
-      <td align="center">Real</td>
-      <td align="center"><strong>sel_hub_url<br/>sel_browser<br/><br/><br/></strong></td>
-      <td align="center">String<br/>String<br/><br/><br/></td>
-      <td align="center">Hub url<br/>Indicate one of the following browsers: iexplore (ie), firefox (ff), chrome, opera, safari.</td>
-    </tr>
-  <tr>
-    <td>selenium_dev</td>
-    <td align="center">Real</td>
-    <td align="center"><strong>-</strong></td>
-    <td align="center">-</td>
-    <td align="center">Execute tests against FireFox (with Firebug and FirePath extensions).</td>
-  </tr>
-  <tr>
-    <td><a href="https://saucelabs.com">sauce</a></td>
-    <td align="center">Real</td>
-    <td align="center">
-    <strong>sl_user<strong><br/>
-    <strong>sl_api_key</strong><br/>
-    <strong>sl_url</strong><br/>
-    <strong>sl_platform</strong><br/>
-    <strong>sl_browser_name</strong><br/>
-    <strong>sl_selenium_version</strong><br/>
-    <strong>sl_max_duration</strong><br/>
-    <strong>sl_idle_timeout</strong></td>
-    <td align="center">
-    String<br/>
-    String<br/>
-    String<br/>
-    Symbol<br/>
-    String<br/>
-    String<br/>
-    String<br/>
-    String</td>
-    <td align="center">See details <a href="https://saucelabs.com/docs/additional-config">here</a></td>
-  </tr>
-  <tr>
-    <td><a href="http://testingbot.com">testingbot</a></td>
-    <td align="center">Real</td>
-    <td align="center">
-      <strong>tb_api_key<strong><br/>
-      <strong>tb_api_secret<strong><br/>
-      <strong>tb_url<strong><br/>
-      <strong>tb_platform<strong><br/>
-      <strong>tb_browser_name<strong><br/>
-      <strong>tb_browser_version<strong><br/>
-      <strong>tb_selenium_version<strong><br/>
-      <strong>tb_max_duration<strong><br/>
-      <strong>tb_idle_timeout<strong><br/>
-      <strong>tb_record_screenshot<strong>
-    </td>
-    <td align="center">
-    String<br/>
-    String<br/>
-    String<br/>
-    Symbol<br/>
-    String<br/>
-    Numberic<br/>
-    String<br/>
-    String<br/>
-    String<br/>
-    Boolean</td>
-    <td align="center">See details <a href="http://testingbot.com/support/other/test-options">here</a></td>
-  </tr>
-</tbody>
-</table>
-
-Pages
-------
-
-Pages are classes describing real web pages. For example, 'Home page' can be described as:
-
-```ruby
-class HomePage < WebPage
-end
-```
-
-It means that each page is inherited from a parent class 'Web Page' which contains common methods for all pages.
-
-Every page contains a required constant URL (the relative URL of the page):
-
-**Example:**
-
-```ruby
-# put the class to ./pages/home_page.rb file
-
-class HomePage < WebPage
-  URL = '/'
-end
-```
-
-### Validations
-
-The Page Object pattern is not expected to use any validations on the UI driver level. But at the same time every page must have some anchor to identify a page exclusively.
-
-```ruby
-validates <type>, options
-```
-
-Howitzer provides 3 different validation types:
-
-<table>
-<thead>
-  <tr>
-    <th align="center">Validation Type</th>
-    <th align="center">Options</th>
-    <th align="center">Value Type</th>
-    <th align="center">Description</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td>:url</td>
-    <td>pattern</td>
-    <td>Regexp</td>
-    <td>matches current url to pattern</td>
-  </tr>
-  <tr>
-    <td>:title</td>
-    <td>pattern</td>
-    <td>Regexp</td>
-    <td>matches current pate title to pattern</td>
-  </tr>
-  <tr>
-    <td>:element_presence</td>
-    <td>locator</td>
-    <td>String/Symbol</td>
-    <td>find element by locator on current page</td>
-  </tr>
-</tbody>
-</table>
-
-**Example 1:**
-
-```ruby
-class HomePage < WebPage
-  URL = '/'
-  validates :url, pattern: /\A(?:.*?:\/\/)?[^\/]*\/?\z/
-end
-```
-
-**Example 2:**
-
-```ruby
-class LoginPage < WebPage
-  URL = '/users/sign_in'
-  validates :title, pattern: /Sign In\z/
-end
-```
-
-**Example 3:**
-
-```ruby
-class LoginPage < WebPage
-  URL = '/users/sign_in'
-
-  validates :element_presence, locator: :sign_in_btn
-
-  add_locator :sign_in_btn, '#sign_in'
-end
-```
-
-Howitzer allows using all 3 validations, but only 1 is really required. If any validation fails, the exception will appear.
-
-**CAUTION:** Page validation is triggered in 2 cases only:
-
-1. < Web Page Class >.open(url)
-2. < Web Page Class >.given
-
-
-### Locators ###
-
-Locator is a search item (selector) of one or more elements on a 'Web page'.
-
-The table below lists the types of locators, the possible methods of searching and Capybara methods, which may be called.
-
-<table>
-<thead>
-  <tr>
-    <th align="center">Locator Type</th>
-    <th align="center">Search Methods</th>
-    <th align="center">Capybara Methods</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td>:locator</td>
-    <td>css(by default), xpath</td>
-    <td>find, all, first</td>
-  </tr>
-  <tr>
-    <td>:link_locator</td>
-    <td>id, text </td>
-    <td>click_link, find_link</td>
-  </tr>
-  <tr>
-    <td>:field_locator</td>
-    <td>id, name, text</td>
-    <td>find_field, fill_in</td>
-  </tr>
-  <tr>
-    <td>:button_locator</td>
-    <td>id, name, text</td>
-    <td>click_button, find_button</td>
-  </tr>
-</tbody>
-</table>
-
-Each page contains a description of all elements by adding the appropriate locators that are preceded by the prefix **add\_**
-
-**Example:**
-
-```ruby
-class HomePage < WebPage
-  URL = '/'
-  validates :url, pattern: /\A(?:.*?:\/\/)?[^\/]*\/?\z/
-
-  add_locator :test_locator_name1,  '.foo'                         #css locator, default
-  add_locator :test_locator_name2,  css: '.foo'                    #css locator
-  add_locator :test_locator_name3,  xpath: '//div[@value="bar"]'   #css locator
-
-  add_link_locator :test_link_locator1, 'Foo'                      #link locator by 'Foo' text
-  add_link_locator :test_link_locator1, 'bar'                      #link locator by 'bar' id
-
-  add_field_locator :test_field_locator1, 'Foo'                    #field locator by 'Foo' text
-  add_field_locator :test_field_locator2, 'bar'                    #field locator by 'bar' id
-  add_field_locator :test_field_locator3, 'bas'                    #field locator by 'baz' name
-end
-```
-
-Sometimes it needs to have universal locators, for instance for many items from menu. Another case, when it's unknown text in locator in advance. For such cases, Howitzer suggests to use _lambda_ locators.
-
-**Example:**
-
-```ruby
- add_locator   :menu_item, ->(name) { { xpath: ".//*[@id='main_menu']//li[.='#{ name }']/a" } }
-
- #and then usage
- def choose_menu(text)
-    find(apply(locator(:menu_item), text)).click
- end
-```
-
-### Pages with static information ###
-
-If static information is repeated on several different pages, it can be a good idea to move these methods into a separate module.
-
-**Example:**
-
-```ruby
-module TopMenu
-  def self.included(base)
-    base.class_eval do
-      add_link_locator :test_link_locator1, 'Foo'
-    end
-  end
-
-  def open_menu
-    log.info "Open menu"
-    click_link locator(:test_link_locator1)
-  end
-end
-```
-
-### Redefining of the *open* method #####
-
-It is used when you need to open a page with additional parameters.
-
-**Example:**
-
-```ruby
-class MyPage < WebPage
-  def self.open(url="#{app_url}#{self::URL}+'?no_popup=true'")
-    super
-  end
-end
-```
-
-### Good Practices Rules ###
-
-Good Practice Rules
-
-**Rule One:** Do not get tied to the interface. This means that you should use common phrases in the name and description of the methods.
-
-**Example:**
-
-```ruby
-class MyPage < WebPage
-  def submit_form
-    # ...
-  end
-
-  def fill_form(value)
-    # ...
-  end
-end
-```
-
-**Rule Two:** Any ACTION method should return an instance of the page. This allows you to do the following:
-
-```ruby
-MyPage.open.fill_form.submit_form
-```
-
-**Example:**
-
-```ruby
-class MyPage < WebPage
-  def fill_form
-    # ...
-    MyPage.given
-  end
-end
-```
-
-**Rule Three:** Coding of checks in the class pages methods are __prohibited.__
-
-**Example:**
-
-```ruby
-class MyPage < WebPage
-  def submit_form
-    # ...
-  end
-
-  def get_all_prices
-   # ...
-   prices
-  end
-end
-```
-
-my_page_spec.rb
-```ruby
-require 'spec_helper'
-
-describe “some feature” do
-  context “when...” do
-    it { expect(MyPage.get_all_prices).to include(400) }
-  end
-end
-```
-
-**Rule Four:** All ACTION methods should create log entries.
-
-**Example:**
-
-```ruby
-class MyPage < WebPage
-  def submit_form
-    log.info { "[ACTION] Submit form" }
-    # ...
-  end
-
-  def fill_form
-    log.info { "[ACTION] Fill form" }
-    # ...
-  end
-end
-```
-
-Emails
-------
-
-Howitzer uses an outstanding service called [Mailgun](http://mailgun.com) that allows to catch all emails of a sandbox domain and store them in its own data storage within 3 days.
-It is extremely useful during web application testing when a new user with email confirmation is created.
-
-You can use a **free** account. Follow the below steps to create an account:
-
-1.	Sign up [here](https://mailgun.com/signup).
-2.	Login and copy your API Key.
-3.	Open the `config/default.yml` file of your project, find the **mailgun_key** setting and paste the API key there.
-4.	Browse to the MailGun web page again and copy the mailgun domain, i.e. 'sandboxbaf443d4c81b43d0b64a413805dc6f68.mailgun.org'
-5.	Open the `config/default.yml` file of your project again, find the **mailgun_domain** setting and paste the mailgun domain there.
-6.	Open the MailGun web page again and navigate to the **Routes** menu.
-7.	Create a new route with the following parameters:
-
-<table>
-<thead>
-  <tr>
-    <th align="center">Priority</th>
-    <th align="center">Filter Expression</th>
-    <th align="center">Action</th>
-    <th align="center">Description</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td>0</td>
-    <td>match_recipient(".*")</td>
-    <td>store()</td>
-    <td>Store all messages</td>
-  </tr>
-</tbody>
-</table>
-
-_**Email**_ Class corresponds to one letter. Used to test the notifications.
-
-* **.find_by_recipient (recipient)** - searches for the letter recipient. The parameter receives email recipient.
-* **.find (recipient, subject)** - same as the **self.find_by_recipient** (recipient), but only when we do not know in advance what kind of __subject__ has an email.
-* **\#plain_text_body** - receiving the body of messages in a plain text.
-* **\#html_body** - receiving the body of messages in html.
-* **\#text_body** - receiving the body of messages as a stripped text.
-* **\#mail_from** - returns the sender’s email data in the format: User Name <user@email>
-* **\#recipients** - returns the array of recipients who received the current email.
-* **\#received_time** - returns the time when an email was received.
-* **\#sender_email** - returns an email of a sender.
-* **\#get_mime_part** - allows you receiving an email attachment.
-
-**Example:**
-
-```ruby
-class MyEmail < Email
-  SUBJECT = 'TEST SUBJECT' # specify the subject of an email
-end
-```
-
-This is how a custom class might look like:
-
-```ruby
- #put the class to ./emails/my_email.rb file
-
- class MyEmail <Email
-   SUBJECT = "Test email" # specify the subject of an email
-
-   def addressed_to? (new_user) # check that the letter were sent to proper recipient
-     / Hi # { new_user } / === plain_text_body
-   end
- end
-```
-
-Logging
--------
-
-*Howitzer* allows logging to the text file, HTML and output to the console.
-
-### BUILT-IN logging ###
-
-*Howitzer* uses the resources of Cucumber and RSpec to generate HTML and JUnit logging. HTML provides the possibility to view the log in HTML while JUnit uses the logs in CI, correspondingly.
-
-Running of built-in HTML generators for RSpec and Cucumber logging is available if you run the tests using the `rake` tasks.
-
-**Example:**
-
-Running **_RSpec_** tests with the `rake` tasks.
-
-```bash
-rake rspec: all
-```
-
-**Example:**
-
-Running **_Cucumber_** tests with the `rake` tasks.
-
-```bash
-rake cucumber: all
-```
-
-It is also possible to manually run the tests with automatic logging.
-
-**Example:**
-
-To manually start a specific RSpec test:
-
-```bash
-rspec spec/my_spec.rb -format html -out =./log/log.html
-```
-
-To manually run an RSpec test:
-
-```bash
-rspec -format html -out =./log/log.html
-```
-
-To manually start a certain _feature_:
-
-```bash
-cucumber features/first.feature -format html -out =./log/log.html
-```
-
-To manually start all _features_:
-
-```bash
-cucumber -format html -out =./log/log.html
-```
-
-### Extended Logging ###
-
-The Extended logging in a text file and in the console is also available.
-It uses the _log manager_ provided by the **_log_** method.
-
-_Howitzer_ supports 4 levels of logging: _**FATAL, WARN, INFO, DEBUG.**_
-
-FATAL <WARN <INFO <DEBUG
-
-**Example:**
-
-```bash
-log.info "info message"
-```
-
-To create a record with a different level, use the appropriate method.
-
-**Example:**
-
-```bash
-log.warn "warning message"
-log.fatal "fatal message"
-```
-
-If the option `settings.debug_mode` = true, the logger will record messages with **DEBUG** status.
-
-Logs are generated and saved in the **log** _directory_.
-
-```bash
- / log
-     log.txt
-     log.html
-     TEST-(your-feature-name). Xml
-```
-
-Examples of logs usage in **Pages** and **Email**.
-
-**Example:** with **Page.**
-
-```ruby
-class MyPage < WebPage
-  def submit_form
-    log.info  "[ACTION] Submit form"
-    …
-  end
-
-  def fill_form
-    log.info  "[ACTION] Fill form"
-    …
-  end
-end
-```
-
-**Example:** with **Email.**
-
-```ruby
-class TestEmail < Email
-  SUBJECT = "Test email"
-
-  def addressed_to?(new_user)
-    if /Hi #{ new_user }/ === plain_text_body
-      log.info "some message"
-    else
-      log.warn "some mesage"
-    end
-  end
-end
-```
-
-## Data Generators ##
-
-The Data generator allows generating data structures (e.g. User) and store the data in its own Memory storage.
-
-### Data Storage ##
-
-The Data Storage is a simple key value storage that uses namespaces (e.g. :user, :sauce, etc.).
-
-This module has next methods:
-The module supports the following methods:
-
-<table>
-<thead>
-  <tr>
-    <th align="center">Method</th>
-    <th align="center">Description</th>
-  </tr>
-</thead>
-<tbody>
-  <tr>
-    <td>DataStorage.store(ns,key,value) </td>
-    <td>Adds data to the storage, where ns is a unique namespace name.</td>
-  </tr>
-  <tr>
-    <td>DataStorage::extract(ns, key=nil)</td>
-    <td>Gets data from the storage by a namespace and a key. If a key is not specified, it will return all data from the namespace.</td>
-  </tr>
-  <tr>
-    <td>DataStorage::clear_ns(ns)</td>
-    <td>Removes a namespace with the data.</td>
-  </tr>
-  <tr>
-    <td>DataStorage::clear_all_ns(exception_list=SPECIAL_NS_LIST)</td>
-    <td>Removes all namespaces except special namespaces provided as an array.</td>
-  </tr>
-</tbody>
-</table>
-
-**Example:**
-
-```ruby
-DataStorage.store(:user, 1, User.new('Peter'))
-DataStorage.store(:user, 2, User.new('Dan'))
-DataStorage.store(:post, "post1", Post.new("Amazing post"))
-```
-
-In memory it looks like:
-
-```ruby
-{
-  user: {
-    1 => User.new('Peter'),
-    2 => User.new('Dan')
-  },
-  post: {
-    "post1" => Post.new("Amazing post")
-  }
-}
-```
-
-### Generator ####
-
-This module uses standard methods for generating test data. 
-It has one standard data object for generation, because it is applicable to almost all tests:
-
-_DataGenerator::Gen::User._
-
-_DataGenerator::Gen::User_ has the params:
-
-:login, :domain, :email, :password, :mailbox, :first_name, :last_name, :full_name
-
-Use _Gen::user(params={})_ method to generate this object.
-
-Also you can reopen _Gen_ module to add your own objects for generation. You can use this module to generate some other data specific for your tests.
-When using Cucumber, create a Gen.rb file in the **/features/support** directory. When using Rspec, create a _Gen.rb_ file in the **/spec/support** directory.
-
-### Cucumber Transformers ###
-
-In **/features/support/tranformers.rb** file are described Cucumber transformers (to see more info visit this one:
-You will find the description of the Cucumber transformers in the **/features/support/tranformers.rb** file. To get more information, refer to this site: 
-[https://github.com/cucumber/cucumber/wiki/Step-Argument-Transforms](https://github.com/cucumber/cucumber/wiki/Step-Argument-Transforms)).
-We use transformers for generating data objects in tests. Let’s imagine, for example, that you need to write a _sign_up.feature:_
-
-```ruby
-Feature: Sign Up
-
-In order to use all functionality of the system
-As unregistered user
-I want to register to the system
-
-Scenario: correct credentials
-Given Register page
-And new UNIQ_USER user      # it’s generate User object with generated test data that are transformed in hash in _transformers.rb_ file.
-When I put next register data and apply it
-
-|username            |email              |password            |
-|UNIQ_USER[:username]|UNIQ_USER[:email]  |UNIQ_USER[:password]|
-```
-
-The last line will automatically replace `UNIQ_USER[:username]` for generated data which you can use.
-
-You can write your own transformers for other generated objects (that you will create in the DataGenerator::Gen module).
-
-
-## Structure of RSpec Folder ##
-
-The **/spec** folder contains all supporting .rspec code and tests. 
-All .rspec settings are located in the **spec_helper.rb** file. You can edit the .rspec settings as you want.
-
-The **/spec/support** file contains a help code, e.g. the code that generates test data.
-It’s better to you modules here in every created files. Methods from this folder will be accessible in every **_spec.rb** file
-and every **_page.rb** file.
-
-It is important to keep all **_spec.rb** files in the folder that contains tests priority meaning in its name.
-You must create folders in the **/spec** in order to add the tests with the required priority level, then edit the constant **TEST_TYPES** in the **/tasks/rspec.rake** file to add a name of the  folder you created as a symbol in the list.
-
-To run tests by a priority level, use the **Rake** tasks in the **/tasks/rspec.rake** file.
-The **TEST_TYPES = [:all, :health, :bvt, :p1]** constant has a list of all available test priorities as standard settings.
-To run all tests in the **/spec** folder, type in:
-
-```bash
-   rake rspec:all
-```
-
-(:all will run all tests in the **/spec** folder). For example, to run :bvt tests you need to create a **/spec/bvt** folder and add some **_spec.rb** files there, then run a Rake task by:
-
-```bash
-rake rspec:bvt
-```
-
-To run tests with less priority level, use _:p1_:
-
-```bash
-rake rspec:p1
-```
-
-Also there is a standard option to run _Smoke_ tests:
-
-```bash
-rake rspec:health
-```
-
-In every directory that is in **/spec** folder, the name of is represents priority of tests that are in it,
-you can create subfolders that represents the business areas of tests. There is a constant in the **/tasks/rspec.rake**:
-
-**TEST_AREAS  = []**
-
-Here you can add business areas of the created tests that are in subfolders. The names should be equal, e.g.:
-If *TEST_AREAS = [:accounts]*. There is a folder with the specs: **/spec/bvt/accounts.**
-You can run all tests from this folder using the command:
-
-```bash
-rake rspec:bvt:accounts
-```
-