From 6ad504fcb173503f530296bf54330b7fb841f1a5 Mon Sep 17 00:00:00 2001 From: Benjamin Jones Date: Mon, 11 Feb 2013 17:26:19 -0800 Subject: adding headless documentation, work in progress.. --- bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar | Bin 0 -> 29292235 bytes bin/runHeadless.sh | 8 +++ doc/manual_src/headlessFiveUI.md | 90 ++++++++++++++++++++++++++ exampleData/headlessRuns/runExample.sh | 8 --- exampleData/headlessRuns/runHeadless.sh | 8 +++ 5 files changed, 106 insertions(+), 8 deletions(-) create mode 100644 bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar create mode 100755 bin/runHeadless.sh create mode 100644 doc/manual_src/headlessFiveUI.md delete mode 100755 exampleData/headlessRuns/runExample.sh create mode 100755 exampleData/headlessRuns/runHeadless.sh diff --git a/bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar b/bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar new file mode 100644 index 0000000..e9cc6dc Binary files /dev/null and b/bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar differ diff --git a/bin/runHeadless.sh b/bin/runHeadless.sh new file mode 100755 index 0000000..6cc925a --- /dev/null +++ b/bin/runHeadless.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +export FIVEUI_ROOT_PATH=$HOME/galois/FiveUI +export FIREFOX_BIN_PATH=$HOME/myapps/Firefox17/Contents/MacOS/firefox + +java -DFIVEUI_ROOT_PATH=$FIVEUI_ROOT_PATH \ + -DFIREFOX_BIN_PATH=$FIREFOX_BIN_PATH \ + -jar $FIVEUI_ROOT_PATH/bin/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar \ + $* diff --git a/doc/manual_src/headlessFiveUI.md b/doc/manual_src/headlessFiveUI.md new file mode 100644 index 0000000..11ee1b9 --- /dev/null +++ b/doc/manual_src/headlessFiveUI.md @@ -0,0 +1,90 @@ +% Automated testing with FiveUI + +# Introducing "headless" + +The FiveUI distribution comes with a Java application called `headless` that is +desiged to make automated testing with FiveUI easy. + +The headless tool can take a collection of FiveUI rule sets and a target (a +single web page, an entire website, or a filtered part of one) and automate the +running of FiveUI rules. Headless can output a text or HTML based report +summarizing the run. + +In what follows, `` refers to the directory where you have installed the +FiveUI distribution. + +## Quickstart + +A "batteries included" jar file and helper script for using `headless` are +included in the `/bin` directory. To start using headless, first +make sure you have Firefox 17 (the E.S.R. release, see step 3 below) installed. + +0. Go to the `/bin` directory + + $ cd + +1. Edit variables at the start of `runHeadless.sh` to reflect your Firefox + installation and FiveUI installation directory. + + $ cat runHeadless.sh + export FIVEUI_ROOT_PATH=$HOME/galois/FiveUI + export FIREFOX_BIN_PATH=$HOME/myapps/Firefox17/Contents/MacOS/firefox + ... + +2. Invoke `runHeadless.sh` from the command line: + + $ runExample.sh -h + usage: headless [ ...] + -h print this help message + -o write output to file + -r write HTML reports to given directory + -v verbose output + -vv VERY verbose output + +3. Run `runHeadless.sh` one of the included run description files + +## Installation + +1. Install maven + +Headless is a [maven](http://maven.apache.org/) managed Java project. The +projects top-level directory is `/headless`, where `` refers to +where you've installed FiveUI. You'll need maven installed on your system to +continue. + + * On debian based linux systems: `sudo apt-get install maven` + * On Mac OS X: Maven 3.x comes pre-installed on OS X 10.7+ + +2. Compile the headless project + +Once you have maven install you can try compiling the project which will trigger +the dependencies to be downloaded and installed in your local maven repository +(for a quick intro to using maven, see [Maven in Five +Minutes](http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). + + $ mvn compile + +In order to use headless you also need a copy of Firefox 17 (the current +extended support release). More recent versions of Firefox may also work, but +they are not supported for use with FiveUI. Download and install Firefox 17 +[here](http://www.mozilla.org/en-US/firefox/organizations/all.html). Note that +Firefox 17 can be installed along side existing alternate versions of firefox on +your system or isolated to your user directory by simply moving it's +installation directory. + +Now that you've installed Firefox 17, it's time to tell headless where the +binary lives. For example, when I install Firefox 17 to `~/myapps/Firefox17` on a +Mac OS X system, the firefox binary lives at + + ~/myapps/Firefox17/Contents/MacOS/firefox + +Locate your firefox binary and remember it for the next step. + +In the top-level `headless` directory, copy the configuration file +`programs.properties.example` to `programs.properties` + + $ cp programs.properties.example programs.properties + +Now, modify the first entry in `programs.properties` +to point to the location of your Firefox binary. + diff --git a/exampleData/headlessRuns/runExample.sh b/exampleData/headlessRuns/runExample.sh deleted file mode 100755 index 9f4af7a..0000000 --- a/exampleData/headlessRuns/runExample.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/usr/bin/env bash -export FIVEUI_ROOT_PATH=../../ -export FIREFOX_BIN_PATH=$HOME/myapps/Firefox\ 17\ esr.app/Contents/MacOS/firefox - -java -DFIVEUI_ROOT_PATH=$FIVEUI_ROOT_PATH \ - -DFIREFOX_BIN_PATH="$FIREFOX_BIN_PATH" \ - -jar $FIVEUI_ROOT_PATH/headless/target/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar \ - $* diff --git a/exampleData/headlessRuns/runHeadless.sh b/exampleData/headlessRuns/runHeadless.sh new file mode 100755 index 0000000..9f4af7a --- /dev/null +++ b/exampleData/headlessRuns/runHeadless.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +export FIVEUI_ROOT_PATH=../../ +export FIREFOX_BIN_PATH=$HOME/myapps/Firefox\ 17\ esr.app/Contents/MacOS/firefox + +java -DFIVEUI_ROOT_PATH=$FIVEUI_ROOT_PATH \ + -DFIREFOX_BIN_PATH="$FIREFOX_BIN_PATH" \ + -jar $FIVEUI_ROOT_PATH/headless/target/HeadlessRunner-0.0.1-SNAPSHOT.one-jar.jar \ + $* -- cgit v1.2.3