Merge pull request #22 from Telefonica/release/1.0.0

Release/1.0.0

CHANGELOG.rst

@@ -4,20 +4,21 @@ Toolium Changelog
 v1.0.0
 ------
 
-*In development*
+*Release date: 2016-04-12*
 
 - Refactor to rename assertScreenshot to assert_screenshot and assertFullScreenshot to assert_full_screenshot
-- Add a config property *appium_app_strings* in [Common] section to request app strings before each Appium test
+- Refactor to move config property 'browser' in [Browser] section to 'type' property in [Driver] section
+- Add a config property 'appium_app_strings' in [Common] section to request app strings before each Appium test
 - Upload the error screenshot to Jira if the test fails
 - Allow to modify Toolium properties from behave userdata configuration, e.g.:
 
 .. code:: console
 
-    $ behave -D Browser_browser=chrome
+    $ behave -D Driver_type=chrome
 
 - Save WebElement in PageElement to avoid searching the same element multiple times
 - Refactor to rename get_element to get_web_element in Utils class and element to web_element in PageElement class
-- Allow to run API tests with behave: browser property must be empty
+- Allow to run API tests with behave: driver type property must be empty
 - Baseline name property can contain *{PlatformVersion}* or *{RemoteNode}* to add actual platform version or remote
   node name to the baseline name
 - Add force parameter to *assert_screenshot* methods to compare the screenshot even if visual testing is disabled by
@@ -26,6 +27,13 @@ v1.0.0
    New config section [FirefoxExtensions] with extensions file paths, e.g. 'firebug = firebug-3.0.0-beta.3.xpi'
 - Allow to use a predefined firefox profile
    New config property 'profile' in [Firefox] section to configure the profile directory
+- Allow to set chrome arguments from properties file
+   | New config section [ChromeArguments] with chrome arguments, e.g. 'lang = es'
+- New config properties 'window_width' and 'window_height' in [Driver] section to configure browser window size
+- Add *wait_until_first_element_is_found* method to Utils class to search a list of elements and wait until one of them
+  is found
+- Refactor to rename 'driver_path' config properties to 'chrome_driver_path', 'explorer_driver_path',
+  'edge_driver_path', 'opera_driver_path' and 'phantomjs_driver_path'
 
 v0.12.1
 -------

README.rst

@@ -72,6 +72,7 @@ Main Features
 
 - `Choosing driver through a configuration file </docs/driver_configuration.rst>`_
 - `Page Object pattern </docs/page_objects.rst>`_
+- `BDD integration </docs/bdd_integration.rst>`_
 - `Visual testing solution </docs/visual_testing.rst>`_
 - Make a screenshot in the happenning of an error
 

VERSION

@@ -1 +1 @@
-v1.0.0.dev0
+v1.0.0

docs/bdd_integration.rst

@@ -0,0 +1,88 @@
+.. _bdd_integration:
+
+BDD Integration
+===============
+
+Toolium can be also used with behave and lettuce tests.
+
+Behave
+------
+
+Behave tests should be developed as usual, only *environment.py* file should be modified to initialize driver and the
+rest of Toolium configuration.
+
+Environment methods should call to the corresponding Toolium environment methods, as can be seen in the following
+example:
+
+.. code-block:: python
+
+    from toolium.behave.environment import (before_all as toolium_before_all, before_scenario as toolium_before_scenario,
+                                            after_scenario as toolium_after_scenario, after_all as toolium_after_all)
+
+
+    def before_all(context):
+        toolium_before_all(context)
+
+
+    def before_scenario(context, scenario):
+        toolium_before_scenario(context, scenario)
+
+
+    def after_scenario(context, scenario):
+        toolium_after_scenario(context, scenario)
+
+
+    def after_all(context):
+        toolium_after_all(context)
+
+
+After initialization, the following attributes will be available in behave context:
+
+- context.toolium_config: dictionary with Toolium configuration, readed from properties.cfg
+- context.driver_wrapper: :ref:`DriverWrapper <driver_wrapper>` instance
+- context.driver: Selenium or Appium driver instance
+- context.utils: :ref:`Utils <utils>` instance
+
+Toolium properties can be modified from behave userdata configuration. For example, to select the driver type from
+command line instead of using the driver type defined in properties.cfg:
+
+.. code:: console
+
+    $ behave -D Driver_type=chrome
+
+Lettuce
+-------
+
+Lettuce tests should be developed as usual, only *terrain.py* file should be modified to initialize driver and the rest
+of Toolium configuration.
+
+Terrain methods should call to the corresponding Toolium terrain methods, as can be seen in the following example:
+
+.. code-block:: python
+
+    from lettuce import after, before
+    from toolium.lettuce.terrain import (setup_driver as toolium_setup_driver, teardown_driver as toolium_teardown_driver,
+                                         teardown_driver_all as toolium_teardown_driver_all)
+
+
+    @before.each_scenario
+    def setup_driver(scenario):
+        toolium_setup_driver(scenario)
+
+
+    @after.each_scenario
+    def teardown_driver(scenario):
+        toolium_teardown_driver(scenario)
+
+
+    @after.all
+    def teardown_driver_all(total):
+        toolium_teardown_driver_all(total)
+
+
+After initialization, the following attributes will be available in world object:
+
+- world.toolium_config: dictionary with Toolium configuration, readed from properties.cfg
+- world.driver_wrapper: :ref:`DriverWrapper <driver_wrapper>` instance
+- world.driver: Selenium or Appium driver instance
+- world.utils: :ref:`Utils <utils>` instance

docs/browser_configuration.rst

@@ -6,13 +6,20 @@ Browser Configuration
 Common Configuration
 --------------------
 
-To choose the browser in which Selenium will execute the tests, configure *browser* property in *[Browser]* section in
+To choose the browser in which Selenium will execute the tests, configure *type* property in *[Driver]* section in
 properties.cfg file with one of these values: firefox, chrome, iexplore, edge, safari, opera or phantomjs.
 
 The following example shows how to choose Firefox::
 
-    [Browser]
-    browser: firefox
+    [Driver]
+    type: firefox
+
+By default, the browser is maximized. To define a different window size, configure *window_width* and *window_height*
+properties in *[Driver]* section::
+
+    [Driver]
+    window_width: 1024
+    window_height: 768
 
 Mandatory Configuration
 -----------------------
@@ -24,73 +31,73 @@ Firefox
 
 - No extra configuration is needed ::
 
-    [Browser]
-    browser: firefox
+    [Driver]
+    type: firefox
 
 Chrome
 ~~~~~~
 
 - Download `chromedriver_*.zip <http://chromedriver.storage.googleapis.com/index.html>`_
 - Unzip file and save the executable in a local folder
-- Configure driver path in *[Browser]* section in properties.cfg file ::
+- Configure driver path in *[Driver]* section in properties.cfg file ::
 
-    [Browser]
-    browser: chrome
-    chromedriver_path: C:\Drivers\chromedriver.exe
+    [Driver]
+    type: chrome
+    chrome_driver_path: C:\Drivers\chromedriver.exe
 
 Internet Explorer
 ~~~~~~~~~~~~~~~~~
 
 - Download `IEDriverServer_Win32_*.zip <http://selenium-release.storage.googleapis.com/index.html>`_
 - It's recommended to use Win32 version, because x64 version is very slow
 - Unzip file and save the executable in a local folder
-- Configure driver path in *[Browser]* section in properties.cfg file ::
+- Configure driver path in *[Driver]* section in properties.cfg file ::
 
-    [Browser]
-    browser: iexplore
-    explorerdriver_path: C:\Drivers\IEDriverServer.exe
+    [Driver]
+    type: iexplore
+    explorer_driver_path: C:\Drivers\IEDriverServer.exe
 
 Edge
 ~~~~
 
 - Download `MicrosoftWebDriver.msi <https://www.microsoft.com/en-us/download/details.aspx?id=48212>`_
 - Install MicrosoftWebDriver.msi
-- Configure driver path in *[Browser]* section in properties.cfg file ::
+- Configure driver path in *[Driver]* section in properties.cfg file ::
 
-    [Browser]
-    browser: edge
-    edgedriver_path: C:\Drivers\MicrosoftWebDriver.exe
+    [Driver]
+    type: edge
+    edge_driver_path: C:\Drivers\MicrosoftWebDriver.exe
 
 Safari
 ~~~~~~
 
 - Download `SafariDriver.safariextz <http://selenium-release.storage.googleapis.com/index.html>`_
 - Open file in Safari and install it ::
 
-    [Browser]
-    browser: safari
+    [Driver]
+    type: safari
 
 Opera
 ~~~~~
 
 - Download `operadriver_*.zip <https://github.com/operasoftware/operachromiumdriver/releases>`_
 - Unzip file and save the executable in a local folder
-- Configure driver path in *[Browser]* section in properties.cfg file ::
+- Configure driver path in *[Driver]* section in properties.cfg file ::
 
-    [Browser]
-    browser: opera
-    operadriver_path: C:\Drivers\operadriver.exe
+    [Driver]
+    type: opera
+    opera_driver_path: C:\Drivers\operadriver.exe
 
 PhantomJS
 ~~~~~~~~~
 
 - Download `phantomjs-*.zip <http://phantomjs.org/download.html>`_
 - Unzip file and save the executable in a local folder
-- Configure driver path in *[Browser]* section in properties.cfg file ::
+- Configure driver path in *[Driver]* section in properties.cfg file ::
 
-    [Browser]
-    browser: phantomjs
-    phantomdriver_path: C:\Drivers\phantomjs.exe
+    [Driver]
+    type: phantomjs
+    phantomjs_driver_path: C:\Drivers\phantomjs.exe
 
 Additional Configuration
 ------------------------
@@ -103,8 +110,8 @@ you want to configure with its value.
 
 For example, the following configuration allows to download files without asking user::
 
-    [Browser]
-    browser: firefox
+    [Driver]
+    type: firefox
 
     [FirefoxPreferences]
     browser.download.folderList: 2
@@ -116,8 +123,8 @@ Firefox plugins can also be installed adding their file paths to *[FirefoxExtens
 
 For example, the following configuration exports network information to har files::
 
-    [Browser]
-    browser: firefox
+    [Driver]
+    type: firefox
 
     [FirefoxPreferences]
     devtools.netmonitor.har.enableAutoExportToFile: True
@@ -133,6 +140,9 @@ For example, the following configuration exports network information to har file
 
 To use a predefined firefox profile, configure the profile directory in *[Firefox]* configuration section::
 
+    [Driver]
+    type: firefox
+
     [Firefox]
     profile: resources/firefox-profile.default
 
@@ -145,24 +155,35 @@ you want to configure with its value.
 
 For example, the following configuration allows to download files without asking user::
 
-    [Browser]
-    browser: chrome
+    [Driver]
+    type: chrome
 
     [ChromePreferences]
     download.default_directory: C:\tmp
 
+To configure Chrome arguments, create a *[ChromeArguments]* configuration section and add every argument that you want
+to configure with its value.
+
+For example, to change the browser language::
+
+    [Driver]
+    type: chrome
+
+    [ChromeArguments]
+    lang: es
+
 Another examples showing how to use Chrome Device Mode in two different ways::
 
-    [Browser]
-    browser: chrome
+    [Driver]
+    type: chrome
 
     [ChromeMobileEmulation]
     deviceName: Google Nexus 5
 
 ::
 
-    [Browser]
-    browser: chrome
+    [Driver]
+    type: chrome
 
     [ChromeMobileEmulation]
     deviceMetrics: { "width": 360, "height": 640, "pixelRatio": 3.0 }

docs/driver_configuration.rst

@@ -4,13 +4,13 @@ Driver Configuration
 ====================
 
 Toolium allows to run tests on web browsers (using Selenium) or on mobile devices (using Appium). To choose the browser
-or the mobile OS, configure *browser* property in *[Browser]* section in properties.cfg file with one of these values:
+or the mobile OS, configure *type* property in *[Driver]* section in properties.cfg file with one of these values:
 firefox, chrome, iexplore, edge, safari, opera, phantomjs, ios or android.
 
 The following example shows how to choose Firefox::
 
-    [Browser]
-    browser: firefox
+    [Driver]
+    type: firefox
 
 - :ref:`Browser Configuration <browser_configuration>`
 - :ref:`Mobile Configuration <mobile_configuration>`

docs/index.rst

@@ -11,6 +11,7 @@ Main Features
 
 - :ref:`Choosing driver through a configuration file <driver_configuration>`
 - :ref:`Page Object pattern <page_objects>`
+- :ref:`BDD integration <bdd_integration>`
 - :ref:`Visual testing solution <visual_testing>`
 - Make a screenshot in the happenning of an error
 
@@ -22,6 +23,7 @@ Library Reference
 
    driver_configuration.rst
    page_objects.rst
+   bdd_integration.rst
    visual_testing.rst
    Changelog <changelog.rst>
 

docs/mobile_configuration.rst

@@ -3,20 +3,20 @@
 Mobile Configuration
 ====================
 
-To choose mobile operating system in which Appium will execute the tests, configure *browser* property in *[Browser]*
+To choose mobile operating system in which Appium will execute the tests, configure *type* property in *[Driver]*
 section in properties.cfg file with one of these values: ios or android.
 
 The following example shows how to choose Android::
 
-    [Browser]
-    browser: android
+    [Driver]
+    type: android
 
 
 Moreover, configure Appium properties in *[AppiumCapabilities]* section in properties.cfg file. The following example
 shows how to configure Appium to run tests over TestApp app on an iPhone 6 with iOS 8.3::
 
-    [Browser]
-    browser: ios
+    [Driver]
+    type: ios
 
     [AppiumCapabilities]
     automationName: Appium