============ PhantomRobot

PhantomRobot is a Robot Framework_ test library that uses the popular PhantomJS_-browser, the headless WebKit-browser, for running acceptance tests in the background. PhantomRobot is written in and is easily expandable with CoffeeScript_.

.. image:: https://secure.travis-ci.org/datakurre/phantomrobot.png :target: http://travis-ci.org/datakurre/phantomrobot

.. _Robot Framework: http://code.google.com/p/robotframework/ .. _PhantomJS: http://www.phantomjs.org/ .. _CoffeeScript: http://coffeescript.org/

.. note::

If you can use Selenium, please, see the GhostDriver_-project, which has already been integrated into Selenium-library for running PhantomJS. It just works, while this is mostly proof-of-concept.

.. _GhostDriver: https://github.com/detro/ghostdriver

Try it out

Checkout the code::

git clone git://github.com/datakurre/phantomrobot.git

Go to the checkout directory and run the buildout_ for installing all the dependencies (buildout keeps everything within the checkout directory)::

cd phantomrobot
python bootstrap.py

.. _buildout: http://www.buildout.org/

Next:

a) On a 32-bit Linux, continue with::

bin/buildout -c buildout-linux-x86.cfg

b) On a 64-bit Linux, continue with::

bin/buildout -c buildout-linux-x86_64.cfg

c) On an OSX, continue with::

bin/buildout

After the buildout has compiled node.js_ and installed required node.js-packages using npm_, you should be able to activate the environment and compile PhantomRobot::

source bin/activate
make

Then launch it (as a blocking foreground process)::

node phantomrobot.js

Finally, to run some Robot Framework tests using PhantomRobot, just open a new console, change to the checkout/buildout-directory of PhantomRobot, and::

source bin/activate
pybot tests

.. _node.js: http://nodejs.org/ .. _npm: http://npmjs.org/

.. note:: PhantomRobot requires phantomjs-binary, which is provided by PhantomJS_' developers for 32-bit Linux, 64-bit Linux, OSX and Windows. If the binary distribution doesn't work for you, PhantomJS could be compiled manually__, at least in theory.

I've done the compiling once on Cent OS 5 / RHEL 5. I needed to build a more recent version of GNU Tar >= 1.2.6 to make npm installing modules successfully. Yet, because websockets-support was broken in all existing QtWebKit-RPMs (thanks to a known bug__), I had to build my own WebKit to be able to compile working PhantomJS and get PhantomRobot running.

.. __: http://code.google.com/p/phantomjs/wiki/BuildInstructions .. __: https://bugs.webkit.org/show_bug.cgi?id=47284

Custom keywords

Developing and including your own custom Robot Framework keyword definitions is easily done in just two steps:

1. Create a .coffee-ending file with your custom keywords as follows::

   keyword "Is defined", (name) -> if not eval("typeof #{name} === 'undefined'") status: "PASS" else status: "FAIL",
   error: "Variable '#{name}' was not defined."

2. Run make with environment variable MY_KEYWORDS containing a relative path to your custom keyword files, e.g.::

   MY_KEYWORDS=*.coffee make

This should result a new phantomrobot.js including your new keywords.

Advanced custom keywords

PhantomRobot support simple and advanced keyword definitions. Simple keyword definitions begin with keyword and are somewhat magical: the defined test function is eventually executed directly within the currently open browser context and have all the pros and cons of that.

Advanced keyword definitions begin with advanced_keyword and are executed outside the currently open browser context. They are not bound to the restrictions of browser context and can take advantage of PhantomJS' API__ (e.g. send real click-events).

On the other hand, advanced keywords must take are of evaluating code within the browser context manually and end their execution by calling the given callback to pass the results back to the Robot Framework test runner::

advanced_keyword "Is defined", ([name], callback) ->

    isDefined = (name) ->
        not eval("typeof #{name} === 'undefined'")

    if @browser.eval isDefined, name
        callback status: "PASS"
    else
        callback status: "FAIL",\
                 error: "Variable '#{name}' was not defined."

.. __: http://code.google.com/p/phantomjs/wiki/Interface

.. note:: @browser.eval is a thin wrapper around PhantomJS_' WebPage.evaluate. It can accept parameters any number of parameters. Besides that, it defines a special function queryAll to be usable to make DOM queries with CSS-selector, XPATH-expression or DOM element id. For more examples, please, see built-in keyword definitions.

Selenium keywords

My secret goal was to provide full and fully tested set of keywords available in Robot Framework SeleniumLibrary_. Unfortunately, it would have taken too much time for me to get that completed.

.. _SeleniumLibrary: http://code.google.com/p/robotframework-seleniumlibrary/

You are free to either help or implement your own custom keywords, e.g. for testing your custom JavaScript-dependent features directly.

Implemented SeleniumLibrary-keywords:

Assign Id To Element (locator=, id=) Assigns a temporary identifier to element specified by locator.This is mainly useful if the locator is complicated/slow XPath expression. Identifier expires when the page is reloaded.

Capture Page Screenshot (filename=, css=) Takes a screenshot of the current page and embeds it into the log. filename argument specifies the name of the file to write the screenshot into. It works the same was as with Capture Screenshot. css can be used to modify how the screenshot is taken. By default the bakground color is changed to avoid possible problems with background leaking when the page layout is somehow broken. Note: css has no effect on phantomrobot.

Click Button (locator=, dont_wait=) n/a

Click Element (locator=, dont_wait=) n/a

Click Link (locator=) n/a

Close All Browsers () Closes all open browsers and empties the connection cache.After this keyword new indexes get from Open Browser keyword are reset to 1.This keyword should be used in test or suite teardown to make sure all browsers are closed.

Close Browser () Closes the current browser.

Element Should Be Visible (locator=, message=) Verifies that the element identified by locator is visible.Herein, visible means that the element is logically visible, not optically visible in the current browser viewport. For example, an element that carries display:none is not logically visible, so using this keyword on that element would fail. message can be used to override the default error message.Key attributes for arbitrary elements are id name

Element Should Contain (locator=, expected=, message=) Verifies element identified by locator contains text expected.If you wish to assert an exact (not a substring) match on the text of the element, use Element text should be message can be used to override the default error message.Key attributes for arbitrary elements are id name

Element Should Not Be Visible (locator=, message=) Verifies that the element identified by locator is NOT visible.This is the opposite of Element should be visible message can be used to override the default error message.Key attributes for arbitrary elements are id name

Element Text Should Be (locator=, expected=, message=) Verifies element identified by locator exactly contains text expected.In contrast to Element Should Contain, this keyword does not try a substring match but an exact match on the element identified by locator. message can be used to override the default error message.Key attributes for arbitrary elements are id name

Get Element Attribute (attribute_locator=) Return value of element attribute. attribute_locator consists of element locator followed by an @ sign and attribute name, for example "element_id@class".

Get Horizontal Position (locator=) Returns horizontal position of element identified by locator The position is returned in pixels off the left side of the page, as an integer. Fails if a matching element is not found.

Get Matching XPath Count (xpath=) Returns number of elements matching xpath If you wish to assert the number of matching elements, use Xpath should match X times

Get Vertical Position (locator=) Returns vertical position of element identified by locator The position is returned in pixels off the top of the page, as an integer. Fails if a matching element is not found.

Go To (url=) Navigates the active browser instance to the provided URL.

Input Text (locator=, text=) Types the given text into text field identified by locator.

Maximize Browser Window () Maximizes current browser window. Note: Just resizes to larger, not maximizes, the browser on phantomrobot.

Mouse Down (locator=) n/a

Mouse Up (locator=) n/a

Open Browser (url=, browser=, alias=) Opens a new browser instance to given URL.Returns the index of this browser instance which can be used later to switch back to it. Index starts from 1 and is reset back to it when Close All Browsers keyword is used. See Switch Browser for example. url is an optional url to open. browser is an optional parameter that exists to support SeleniumLibarary and is just ignored. alias is an optional alias for the browser instance and it can be used for switching between browsers similarly as the index. See Switch Browser for more details about that.

Page Should Contain (text=, loglevel=) Verifies that current page contains text.If this keyword fails, it automatica