fluid-webdriver

fluid-webdriver

This package provides a series of Fluid components to assist in writing tests that use the WebDriver API to control a real browser and to examine the browser's state.

The main goals of this package are to:

• Make it possible to test complex keyboard navigation.
• Make it possible to test browser navigation (moving back and forward in the browser's history, and reloading the page).
• Provide the ability to write tests that need to be aware of both the server and browser state.
• Do all of the above across a range of browsers.

Keyboard Navigation

Many approaches to testing keyboard navigation send individual keystrokes directly to a single named component and examine the results. While this does confirm the behavior of the component, it does not provide a good means of testing navigation between components. Sending keys directly to a known component also assumes that the component can already be reached using keyboard navigation.

With this package, you can test sending keys directly to a component, navigation between components, and using keyboard navigation to focus on an element. This allows for much more realistic user-focused test scenarios like:

• Hitting "Tab" once to display a "Skip to Content" control.
• Hitting "Enter" to skip to the main content.
• Hitting "Tab" to focus on a search control in the content area.
• Typing search terms into the search control.
• Hitting "Enter" to perform a search.

Using this package, the above scenario can be tested even if javascript is completely disabled.

Browser Navigation

This package provides the ability to change the browser's state in exactly the same manner as would happen if a user hit the "back", "next", and "refresh" buttons or shortcut keys. You might use this to:

• Confirm that the parts of your page that should preserve their state on a refresh actually do so.
• Confirm that the parts of your page that should reset their state on a refresh actually do so.
• Confirm that a warning is displayed when a user attempts to refresh or navigate away after entering form data.

Passing Code between the Server and Browser

This package makes use of the IPC bridge built into WebDriverJS to send code to the browser, have that code be executed, and to receive the results of the code's execution. Among many other things, this allows you to:

• Inspect the current browser DOM.
• Check the value of a named element.
• Pass in scripts to be executed in the browser before the tests are run, for example, scripts to report test or code coverage information.

Running the Tests

To run the tests locally, you will need to install the drivers for each browser you want to test. Once you have done this, you can use the command npm test to run the tests.

You can also use the command vagrant up to provision a linux box and run the Chrome tests there.

Using this Package to Write Your Own Tests

To make use of this package in your own tests, you will typically need to add code like the following:

var fluid = require("infusion");
require("fluid-webdriver");
fluid.webdriver.loadTestingSupport();

Note that although the last line is not required to simply use the webdriver itself, you'll need it if you want to use the caseHolder, testEnvironment or cross-browser test runner including with this package.

Running Under Windows

Internet Explorer

There is a known problem with very slow text input when using the 64-bit IEDriverServer. If you are on a 64-bit Windows machine and seeing extreme slowness in tests that supply text input, you should:

• Download the 32-bit version of IEDriverServer.
• Unzip and launch the server.
• Set your SELENIUM_REMOTE_URL environment variable to http://localhost:5555.
• Set your BROWSERS environment to ie.

Note that once you do this, the BROWSERS and SELENIUM_BROWSER variables will no longer be meaningful, and tests will only run in Internet Explorer. The fourth step above simply avoids running the IE tests multiple times (once expecting to run using Chrome, once expecting to run using Internet Explorer, etc.).

Edge

Edge is currently not verified working with any combination of Selenium and the WebDriver server, but it should be possible to use it with instructions like the following:

• Download and install the Microsoft WebDriver package.
• Launch the server.
• Set your SELENIUM_REMOTE_URL environment to http://localhost:17556/.
• Set your BROWSERS environment variable to edge.

This will cause the tests to only be run in the Edge browser. See above for more details.

Firefox

Firefox 47 and below will work with older versions of this package. Firefox 48.0 and higher do not work for now. For more information, see fluid-1913.

More Information

For more information, check out the individual docs for:

• The driver component
• Accessibility Checks
• Other Helper Functions
• The browser-side QUnit harness
• The test fixtures included with this package
• The multi-browser test runner

Running Tests in "Headless" Mode

Several browsers now support a "headless" mode, in which no window is displayed onscreen as the tests are run. This tends to run faster and require less resources. If you set the HEADLESS environment variable to a non-empty value, this package will attempt to run supported browser (as of this writing, only Chrome) in "headless" mode.