GPII-1889: Initial review of gpii-webdriver...

.eslintrc.json

@@ -0,0 +1,81 @@
+{
+  "env": {
+    "browser": true,
+    "node": false
+  },
+  "globals": {
+    "fluid_2_0_0": true
+  },
+  "rules": {
+    "block-scoped-var": "error",
+    "comma-style": [
+      "error",
+      "last"
+    ],
+    "curly": [
+      "error",
+      "all"
+    ],
+    "dot-notation": [
+      "error",
+      {
+        "allowKeywords": false
+      }
+    ],
+    "eol-last": "error",
+    "eqeqeq": [
+      "error",
+      "allow-null"
+    ],
+    "indent": ["error", 4],
+    "new-cap": ["error", { "properties": false }],
+    "no-caller": "error",
+    "no-cond-assign": [
+      "error",
+      "except-parens"
+    ],
+    "no-debugger": "error",
+    "no-empty": ["error", {"allowEmptyCatch": true}],
+    "no-eval": "error",
+    "no-extend-native": "error",
+    "no-extra-parens": "off",
+    "no-irregular-whitespace": "error",
+    "no-iterator": "error",
+    "no-loop-func": "error",
+    "no-multi-str": "error",
+    "no-new": "error",
+    "no-plusplus": 0,
+    "no-proto": "error",
+    "no-script-url": "error",
+    "no-sequences": "error",
+    "no-trailing-spaces": "error",
+    "no-undef": "error",
+    "no-unused-vars": "error",
+    "no-with": "error",
+    "quotes": [
+      "error",
+      "double"
+    ],
+    "semi": [
+      0,
+      "always"
+    ],
+    "space-before-blocks": ["error", "always"],
+    "space-before-function-paren": ["error", {"anonymous": "always", "named": "never"}],
+    "space-infix-ops": "error",
+    "space-unary-ops": [
+      "error", {
+        "words": true,
+        "nonwords": false,
+        "overrides": {
+            "typeof": false
+        }
+    }],
+    "strict": ["error", "safe"],
+    "valid-typeof": "error",
+    "wrap-iife": [
+      "error",
+      "inside"
+    ]
+  }
+}

.gitignore

@@ -0,0 +1,38 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules
+jspm_packages
+
+# Optional npm cache directory
+.npm
+
+# Optional REPL history
+.node_repl_history
+.vagrant

.qi.yml

@@ -0,0 +1,24 @@
+# A configuration file for our Quality Infrastructure builds: https://wiki.gpii.net/w/Quality_Infrastructure
+
+email: tony@raisingthefloor.org
+env_runtime: linux-desktop
+
+apps:
+  - app_name: gpii-webdriver
+    app_start_service: false
+    git_repository: https://github.com/the-t-in-rtf/gpii-webdriver.git
+    git_branch: GPII-1889
+    software_stack: nodejs
+    software_stack_version: lts
+    folder:
+      dest: /app/gpii-express
+    run_in: fedora
+    deploy: false
+    setup:
+      - sudo dnf -y install java-1.8.0-openjdk-devel.x86_64
+      - npm install
+    test_cmds:
+      - export PATH=$PATH:/home/vagrant/sync/node_modules/chromedriver/bin/chromedriver/
+      - xhost +
+      - export DISPLAY=:0
+      - BROWSERS=chrome npm test

Gruntfile.js

@@ -0,0 +1,18 @@
+/* eslint-env node */
+"use strict";
+
+module.exports = function (grunt) {
+    grunt.initConfig({
+        eslint: {
+            src: ["./src/**/*.js", "./tests/**/*.js", "./*.js"]
+        },
+        jsonlint: {
+            src: ["./src/**/*.json", "./tests/**/*.json"]
+        }
+    });
+
+    grunt.loadNpmTasks("fluid-grunt-eslint");
+    grunt.loadNpmTasks("grunt-jsonlint");
+
+    grunt.registerTask("lint", "Apply jshint and jsonlint", ["eslint", "jsonlint"]);
+};

README.md

@@ -0,0 +1,113 @@
+# gpii-webdriver
+
+This package provides a series of [Fluid components](http://docs.fluidproject.org/infusion/development/UnderstandingInfusionComponents.html)
+to assist in writing tests that use the [WebDriver API](https://www.w3.org/TR/2013/WD-webdriver-20130117/) to control a
+real browser and to examine the browser's state.
+
+The main goals of this package are to:
+
+1. Make it possible to test complex keyboard navigation.
+2. Make it possible to test browser navigation (moving back and forward in the browser's history, and reloading the page).
+3. Provide the ability to write tests that need to be aware of both the server and browser state.
+4. 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:
+
+1. Hitting "Tab" once to display a "Skip to Content" control.
+2. Hitting "Enter" to skip to the main content.
+3. Hitting "Tab" to focus on a search control in the content area.
+4. Typing search terms into the search control.
+5. 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:
+
+1. Confirm that the parts of your page that should preserve their state on a refresh actually do so.
+2. Confirm that the parts of your page that should reset their state on a refresh actually do so.
+3. 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:
+
+1. Inspect the current browser DOM.
+2. Check the value of a named element.
+3. 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](http://www.seleniumhq.org/download/)
+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 and Firefox 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
+
+# Internet Explorer
+
+There is a known problem with [very slow text input](https://github.com/seleniumhq/selenium-google-code-issue-archive/issues/5116)
+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:
+
+1. [Download the 32-bit version of IEDriverServer](http://www.seleniumhq.org/download/).
+2. Unzip and launch the server.
+3. Set your `SELENIUM_REMOTE_URL` environment variable to `http://localhost:5555`.
+4. 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:
+
+1. [Download and install the Microsoft WebDriver package](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/).
+2. Launch the server.
+3. Set your `SELENIUM_REMOTE_URL` environment to `http://localhost:17556/`.
+4. 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 this package.  Firefox 48.0 and higher do not work for now.  For more information,
+see [GPII-1913](https://issues.gpii.net/browse/GPII-1913).
+
+# More Information
+
+For more information, check out the individual docs for:
+
+* [The driver component](./docs/webdriver.md)
+* [The helper functions](./docs/helper-functions.md)
+* [The browser-side QUnit harness](./docs/qunit-harness.md)
+* [The test fixtures included with this package](./docs/fixtures.md)
+* [The multi-browser test runner](./docs/allBrowsers.md)

Vagrantfile

@@ -0,0 +1,15 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# This file loads a generic Vagrantfile that will build the environment
+# specified in the .qi.yml file.
+#
+# DO NOT MODIFY THIS FILE
+#
+# if you want to change the VMs specifications go to README.md
+
+VAGRANT_VMENV_PATH = `node -e "require('vagrant-vmenv')"`.delete!("\n")
+puts "\nCan not find the vagrant-vmenv module, please install it:\n" +
+  "npm install -g https://github.com/amatas/vagrant-vmenv.git" if $?.to_i != 0
+
+require_relative( VAGRANT_VMENV_PATH + '/Vagrantfile.rb')

docs/allBrowsers.md

@@ -0,0 +1,71 @@
+# `gpii.test.webdriver.allBrowsers`
+
+This grade helps you run your tests against a range of browsers.  The defaults are designed for use with
+[Fluid IoC tests](http://docs.fluidproject.org/infusion/development/IoCTestingFramework.html#how-to-use-the-ioc-testing-framework).
+By default, a new test environment is generated for each browser, and then queued up using `fluid.test.runTests`.
+
+## Component options
+
+| Option                    | Type       | Description |
+| ------------------------- | ---------- | ----------- |
+| `baseTestEnvironment`     | `{String}` | The base testEnvironment that we will extend and configure to use a particular browser. |
+| `browsers`                | `{Array}`  | The list of browsers to run the tests against (see below for the order of precedence). |
+
+## Component Invokers
+
+### `{that}.runTestsInSingleBrowser(browser)`
+
+An invoker which runs the tests in a single `browser`.  By default, this generates a test environment for each browser,
+based on `baseTestEnvironment` (see above), and then runs the tests using `fluid.tests.runTests`.  See below for details
+on using this grade with non-IoC tests.
+
+## Configuring the List of Browsers
+
+This grade will run tests against a list of browsers, which is defined based on whichever of the following is found
+first:
+
+1. The `BROWSERS` environment variable (see below).
+2. `that.options.browsers` (see above)
+3. `gpii.test.webdriver.allBrowsers.defaultPlatformBrowsers`, the platform-specific list of "verified working" browsers (see below).
+
+The `BROWSERS` environment variable should be a space or comma-delimited list of browsers, as in the following example
+for a unix-like system:
+
+```
+export BROWSERS="firefox chrome"
+```
+
+If you're working with Windows PowerShell, the syntax is something like:
+
+```
+$env:BROWSERS = "chrome"
+```
+
+Note that you can run the tests for a single browser by setting `BROWSERS` to a single value, as in the previous example.
+
+## Using this Grade with IoC Tests
+
+To use this grade with IoC tests, you must define a base `testEnvironment`, and then instantiate this grade as in the
+following example:
+
+```
+fluid.defaults("my.tests.testRunner", {
+    gradeNames: ["gpii.test.webdriver.allBrowsers"],
+    baseTestEnvironment: "gpii.tests.webdriver.executeScript.args.environment"
+});
+
+my.tests.testRunner();
+```
+
+## Using this Grade with Non-IoC Tests
+
+If you want to use this grade to run tests that do not use the Fluid IoC test framework, override the
+`runTestsInSingleBrowser` invoker (see above) with your own function that runs the tests for a single browser.  See
+the "syncInit" and "dumpLogs" tests in this package for examples.
+
+# `gpii.test.webdriver.allBrowsers.defaultPlatformBrowsers`
+
+A static list of the default (confirmed working) browsers, by platform.  Only OS X, Windows, and Linux have any browsers
+at all, as the other platforms [are not supported by Selenium itself](http://www.seleniumhq.org/about/platforms.jsp).
+The "firefox" and "edge" browsers are not yet confirmed working on Windows.  See the README for details on running
+tests with "ie", which works, but cannot currently be run in combination with any other browser.

docs/fixtures.md

@@ -0,0 +1,25 @@
+# `gpii.test.webdriver.caseHolder`
+
+This caseHolder does three key things:
+
+1. It tells the test environment to create a driver, and waits for the driver to be ready before starting the tests.
+2. It automatically prepends the current browser to the `name` of each test module and test sequence.
+3. It tells the test environment to clean up the driver after each test sequence is complete.
+
+Note that the wiring that creates and cleans up the driver assumes that your caseholder will be loaded from an
+instance of `gpii.test.webdriver.testEnvironment` (see below).
+
+## Component Options
+
+| Option          | Type     | Description |
+| --------------- | -------- | ----------- |
+| `browser`       | `{String}` | A [browser supported by the WebDriver API](http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/lib/capabilities_exports_Browser.html), in lower case.|
+| `sequenceStart` | `Object`   | A series of test sequence steps to execute at the beginning of each test sequence. |
+| `sequenceEnd`   | `Object`   | A series of test sequence steps to execute at the end of each test sequence. |
+| `rawModules`    | `Object`   | The raw test modules to "evolve" as outlined above. |
+
+
+# `gpii.test.webdriver.testEnvironment`
+
+A Fluid IoC test environment that creates a webdriver instance when its `constructFixtures` event is fired.  Provides
+all of the required events and listeners to work with a `gpii.test.webdriver.caseHolder` instance (see above).