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.
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.
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"); var gpii = fluid.registerNamespace("gpii"); require("gpii-webdriver"); gpii.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
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_URLenvironment variable to
- Set your
Note that once you do this, the
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 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
- Set your
BROWSERSenvironment variable to
This will cause the tests to only be run in the Edge browser. See above for more details.
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 GPII-1913.
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.