New generation Selenium WebDriver module.

1. Download Selenium Server
2. Launch the daemon: java -jar selenium-server-standalone-2.xx.xxx.jar
3. Configure this module (in acceptance.suite.yml) by setting url and browser:

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: 'http://localhost/'
         browser: firefox

{% endhighlight %}

PhantomJS is a headless alternative to Selenium Server that implements the WebDriver protocol. It allows you to run Selenium tests on a server without a GUI installed.

1. Download PhantomJS
2. Run PhantomJS in WebDriver mode: phantomjs --webdriver=4444
3. Configure this module (in acceptance.suite.yml) by setting url and phantomjs as browser:

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: 'http://localhost/'
         browser: phantomjs

{% endhighlight %}

Cloud Testing services can run your WebDriver tests in the cloud. In case you want to test a local site or site behind a firewall you should use a tunnel application provided by a service.

1. Create an account at SauceLabs.com to get your username and access key
2. In the module configuration use the format username:access_key@ondemand.saucelabs.com' for host
3. Configure platform under capabilities to define the Operating System
4. run a tunnel app if your site can't be accessed from Internet

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: http://mysite.com
         host: '<username>:<access key>@ondemand.saucelabs.com'
         port: 80
         browser: chrome
         capabilities:
             platform: 'Windows 10'

{% endhighlight %}

1. Create an account at BrowserStack to get your username and access key
2. In the module configuration use the format username:access_key@hub.browserstack.com' for host
3. Configure os and os_version under capabilities to define the operating System
4. If your site is available only locally or via VPN you should use a tunnel app. In this case add browserstack.local capability and set it to true.

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: http://mysite.com
         host: '<username>:<access key>@hub.browserstack.com'
         port: 80
         browser: chrome
         capabilities:
             os: Windows
             os_version: 10
             browserstack.local: true # for local testing

{% endhighlight %}

1. Create an account at TestingBot to get your key and secret
2. In the module configuration use the format key:secret@hub.testingbot.com' for host
3. Configure platform under capabilities to define the Operating System
4. Run TestingBot Tunnel if your site can't be accessed from Internet

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: http://mysite.com
         host: '<key>:<secret>@hub.testingbot.com'
         port: 80
         browser: chrome
         capabilities:
             platform: Windows 10

{% endhighlight %}

• url required - Starting URL for your app.
• browser required - Browser to launch.
• host - Selenium server host (127.0.0.1 by default).
• port - Selenium server port (4444 by default).
• restart - Set to false (default) to share browser session between tests, or set to true to create a separate session for each test.
• window_size - Initial window size. Set to maximize or a dimension in the format 640x480.
• clear_cookies - Set to false to keep cookies, or set to true (default) to delete all cookies between tests.
• wait - Implicit wait (default 0 seconds).
• capabilities - Sets Selenium2 desired capabilities. Should be a key-value array.
• connection_timeout - timeout for opening a connection to remote selenium server (30 seconds by default).
• request_timeout - timeout for a request to return something from remote selenium server (30 seconds by default).
• http_proxy - sets http proxy server url for testing a remote server.
• http_proxy_port - sets http proxy server port
• debug_log_entries - how many selenium entries to print with debugWebDriverLogs or on fail (15 by default).

Example (acceptance.suite.yml)

{% highlight yaml %}

modules:
   enabled:
      - WebDriver:
         url: 'http://localhost/'
         browser: firefox
         window_size: 1024x768
         capabilities:
             unexpectedAlertBehaviour: 'accept'
             firefox_profile: '~/firefox-profiles/codeception-profile.zip.b64'

{% endhighlight %}

Stability: stable Based on facebook php-webdriver

Most methods in this module that operate on a DOM element (e.g. click) accept a locator as the first argument, which can be either a string or an array.

If the locator is an array, it should have a single element, with the key signifying the locator type (id, name, css, xpath, link, or class) and the value being the locator itself. This is called a "strict" locator. Examples:

• ['id' => 'foo'] matches <div id="foo">
• ['name' => 'foo'] matches <div name="foo">
• ['css' => 'input[type=input][value=foo]'] matches <input type="input" value="foo">
• ['xpath' => "//input[@type='submit'][contains(@value, 'foo')]"] matches <input type="submit" value="foobar">
• ['link' => 'Click here'] matches <a href="google.com">Click here</a>
• ['class' => 'foo'] matches <div class="foo">

Writing good locators can be tricky. The Mozilla team has written an excellent guide titled Writing reliable locators for Selenium and WebDriver tests.

If you prefer, you may also pass a string for the locator. This is called a "fuzzy" locator. In this case, Codeception uses a a variety of heuristics (depending on the exact method called) to determine what element you're referring to. For example, here's the heuristic used for the submitForm method:

1. Does the locator look like an ID selector (e.g. "#foo")? If so, try to find a form matching that ID.
2. If nothing found, check if locator looks like a CSS selector. If so, run it.
3. If nothing found, check if locator looks like an XPath expression. If so, run it.
4. Throw an ElementNotFound exception.

Be warned that fuzzy locators can be significantly slower than strict locators. If speed is a concern, it's recommended you stick with explicitly specifying the locator type via the array syntax.

• webDriver - instance of \Facebook\WebDriver\Remote\RemoteWebDriver. Can be accessed from Helper classes for complex WebDriver interactions.

{% highlight php %}

// inside Helper class $this->getModule('WebDriver')->webDriver->getKeyboard()->sendKeys('hello, webdriver');

{% endhighlight %}

hidden API method, expected to be used from Helper classes

Locates element using available Codeception locator types:

• XPath
• CSS
• Strict Locator

Use it in Helpers or GroupObject or Extension classes:

{% highlight php %}

{% endhighlight %}

• param $subdomain

Open web page at the given absolute URL and sets its hostname as the base host.

{% highlight php %}

{% endhighlight %}

Append the given text to the given element. Can also add a selection to a select box.

{% highlight php %}

{% endhighlight %}

• param string $field
• param string $value
• throws \Codeception\Exception\ElementNotFound

Attaches a file relative to the Codeception data directory to the given file upload field.

{% highlight php %}

{% endhighlight %}

• param $field
• param $filename

Dismisses the active JavaScript popup, as created by window.alert|window.confirm|window.prompt.

Ticks a checkbox. For radio buttons, use the selectOption method instead.

{% highlight php %}

{% endhighlight %}

• param $option

Perform a click on a link or a button, given by a locator. If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string. For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched. For images, the "alt" attribute and inner text of any parent links are searched.

The second parameter is a context (CSS or XPath locator) to narrow the search.

Note that if the locator matches a button of type submit, the form will be submitted.

{% highlight php %}

{% endhighlight %}

• param $link
• param $context

Performs contextual click with the right mouse button on an element.

• param $cssOrXPath
• throws \Codeception\Exception\ElementNotFound

Print out latest Selenium Logs in debug mode

Checks that the current page doesn't contain the text specified (case insensitive). Give a locator as the second parameter to match a specific region.

{% highlight php %}

I am Stronger than thou