Updated documentation

6 files changed, 122 insertions, 65 deletions

diff --git a/BUILDINSTRUCTIONS b/BUILDINSTRUCTIONS
index 3997a05..6993370 100644
--- a/BUILDINSTRUCTIONS
+++ b/BUILDINSTRUCTIONS
@@ -9,12 +9,14 @@ Development platform is Linux.
 To build all applications, it's required to use Qt 5.1 (or later).
 See http://qt-project.org/downloads#qt-lib for download.
 
-For the browser application and the demoUI application Qt 5.0 would be sufficient.
-The testapp application requires Qt 5.1, because of the use of Qt Quick Controls 
+For the browser application and the demoUI application Qt 5.0 would be
+sufficient.  The testapp application requires Qt 5.1, because of the use of Qt
+Quick Controls
 (http://qt-project.org/doc/qt-5.1/qtquickcontrols/qtquickcontrols-index.html).
 
-If building Qt from source, all Qt Essential modules and the Qt Declarative module are necessary
-(see http://qt-project.org/doc/qt-5.1/qtdoc/qtmodules.html).
+If building Qt from source, all Qt Essential modules and the Qt Declarative
+module are necessary (see
+http://qt-project.org/doc/qt-5.1/qtdoc/qtmodules.html).
 
 
 Build
@@ -34,8 +36,67 @@ To build the separate applications on its own, run
 Run
 ---
 
-Always start the browser application first, then start the demoUI or test application. 
+Always start the browser application first, then start the demoUI or test
+application.
 
-For more detailed information about usage and overview, see documentation on the Genivi wiki.
+For more detailed information about usage and overview, see documentation on
+the Genivi wiki.
 
+Testing
+-------
 
+There are automated tests in browser/unit-tests/. In order to build these,
+enter the subdirecory of the respective test you'd like to build and issue
+<path_to_qt_installation>/bin/qmake.
+
+Each test will produce a binary of its test suite, which is run using
+./<name of test>.
+
+browserdbus requires the browser to be running, and also requires the
+xdotool[1] to be installed in $PATH.
+
+browserview has no external requirements.
+
+cachemanagerdbus requires the browser to be running.
+
+errorloggerdbus requires the browser to NOT be running
+
+Installing Qt 5 on Ubuntu 12.04
+-------------------------------
+
+If your target is to build GENIVI's Browser Proof-of-Concept on Ubuntu
+12.04 LTS, then these instructions may help you through the build
+process. The build process is slightly different if you're using
+Ubuntu's version of Qt 5.
+
+System requirements
+-------------------
+
+Ubuntu 12.04 LTS
+
+To get a later version of Qt on Ubuntu 12.04, which was released
+nearly two years ago, you can use the Ubuntu provided SDK for Qt
+available as a PPA.[2] The easiest way to do this is to add to
+/etc/apt/sources.list these two lines;
+
+ deb http://ppa.launchpad.net/ubuntu-sdk-team/ppa/ubuntu precise main
+ deb-src http://ppa.launchpad.net/ubuntu-sdk-team/ppa/ubuntu precise main
+
+Alternatively Ubuntu puts PPAs in the sources.list.d directory so you
+can put those two lines in a file called
+/etc/apt/sources.list.d/ubuntu-sdk-team-ppa-precise.list
+and then run;
+
+$ sudo apt-get update
+$ sudo apt-get install qtdeclarative5-dev
+
+The above commands install the headers / libraries necessary for
+development with Qt and QML.
+
+See also: http://askubuntu.com/questions/279421/how-can-i-install-qt-5-x-on-12-04-lts
+
+References
+----------
+
+[1] http://www.semicomplete.com/projects/xdotool/
+[2] https://launchpad.net/~ubuntu-sdk-team/+archive/ppa
diff --git a/Build.instructions.Ubuntu.txt b/Build.instructions.Ubuntu.txt
deleted file mode 100644
index 623327a..0000000
--- a/Build.instructions.Ubuntu.txt
+++ /dev/null
@@ -1,37 +0,0 @@
-Build Instructions for installation of Browser-PoC on Ubuntu 12.04
-==================================================================
-
-If your target is to build GENIVI's Browser Proof-of-Concept on Ubuntu
-12.04 LTS, then these instructions may help you through the build
-process. The build process is slightly different if you're using
-Ubuntu's version of Qt 5.
-
-System requirements
--------------------
-
-Ubuntu 12.04 LTS
-
-To get a later version of Qt on Ubuntu 12.04, which was released
-nearly two years ago, you can use the Ubuntu provided SDK for Qt
-available as a PPA.[1] The easiest way to do this is to add to 
-/etc/apt/sources.list these two lines;
-
- deb http://ppa.launchpad.net/ubuntu-sdk-team/ppa/ubuntu precise main 
- deb-src http://ppa.launchpad.net/ubuntu-sdk-team/ppa/ubuntu precise main 
-
-Alternatively Ubuntu puts PPAs in the sources.list.d directory so you
-can put those two lines in a file called
-/etc/apt/sources.list.d/ubuntu-sdk-team-ppa-precise.list
-and then run;
-
-$ sudo apt-get update
-$ sudo apt-get install qtdeclarative5-dev
-
-The above commands install the headers / libraries necessary for
-development with Qt and QML.
-
-Resources
----------
-
-0. http://askubuntu.com/questions/279421/how-can-i-install-qt-5-x-on-12-04-lts
-1. https://launchpad.net/~ubuntu-sdk-team/+archive/ppa
diff --git a/documentation/designdocument/browser.pdf b/documentation/designdocument/browser.pdf
deleted file mode 100644
index 90aacdd..0000000
--- a/documentation/designdocument/browser.pdf
+++ /dev/null
diff --git a/documentation/designdocument/browser.tex b/documentation/designdocument/browser.tex
index 2e5181e..b610f39 100644
--- a/documentation/designdocument/browser.tex
+++ b/documentation/designdocument/browser.tex
@@ -20,6 +20,8 @@
 \maketitle
 \tableofcontents \clearpage
 
+\hyphenation{Webkit}
+
 \section{Introduction and project background}
 The GENIVI Networking Expert Group (NW-EG) would like to exercise a D-Bus-based
 software component to test the usability and quality of a web browser that uses
@@ -109,15 +111,13 @@ The NW-EG defined the following requirements:
 The following D-Bus interfaces files were provided as input to the project:
 
 \begin{enumerate}
-    \item IBrowser.xml
-    \item IWebPageWindow.xml
-    \item IUserInput.xml
     \item IBookmarkManager.xml
-    \item IUserInput.xml
-    \item INetworkManager.xml
+    \item IBrowser.xml
+    \item ICacheManager.xml
     \item IErrorLogger.xml
+    \item INetworkManager.xml
+    \item IUserInput.xml
     \item IWebPageWindow.xml
-    \item ICacheManager.xml
 \end{enumerate}
 
 These interfaces represent a subset of the GENIVI APIs defined by NW-EG and
@@ -153,8 +153,7 @@ a look at the group's wiki page
 (\url{https://collab.genivi.org/wiki/display/genivi/Networking+Expert+Group}).
 
 For instructions, how to build all applications or only a single application,
-refer to the file {\tt BUILDINSTRUCTIONS}, or {\tt
-Build.instructions.Ubuntu.txt}  in the repository.
+refer to the file {\tt BUILDINSTRUCTIONS}.
 
 \section {Common part}
 here is a common part in the project, which contains files, which are shared by
@@ -163,9 +162,9 @@ folder {\tt /common}:
 
 \begin{itemize}
     \item The XML files describing the interfaces
-    \item A class defining a bookmark object (bookmark.h|cpp)
+    \item A class defining a bookmark object (bookmark.h and bookmark.cpp)
     \item A class defining the D-Bus interfaces on client side (demoUI and test
-          application) (browserdbus.h|cpp)
+          application) (browserdbus.h and browserdbus.cpp)
     \item A header file defining common types and structures (browserdefs.h)
 \end{itemize}
 
@@ -200,8 +199,7 @@ The source code of the browser application can to be found in the {\tt
 \end{tabular}
 
 \subsection{Implementation}
-The browser application is implemented using Qt Quick 1 and Qt Webkit 1. Qt
-Quick 1 needed to be used, because of the requirement to use Qt Webkit 1.
+The browser application is implemented using QGraphicsWebView and Qt Webkit 1.
 
 There is one class available for each defined interface group (XML file)
 implementing the functions for the defined interfaces on server side. These
@@ -220,12 +218,16 @@ bookmark interface class with the D-Bus connection under an object path
 webpagewindow and userinput will be registered, when a new page is actually
 created.
 
-bookmarkmanager.h|cpp implements the IBookmarkManager interfaces and manages
+Each class is implemented in one header file and one cpp file, with the
+extensions .h and .cpp respectively. Each .cpp file mentioned below also has an
+associated .h file containing the class definition.
+
+bookmarkmanager.cpp implements the IBookmarkManager interfaces and manages
 persistent storage of bookmarks.
 
-userinput.h|cpp implements the IUserInput interfaces.
+userinput.cpp implements the IUserInput interfaces.
 
-browser.h|cpp implements the IBrowser interfaces, creates and set up a
+browser.cpp implements the IBrowser interfaces, creates and set up a
 declarative view with the main QML file (the webview) and registers
 webpagewindow and userinput objects under a unique object path
 (/Browser/IWebPageWindow + window handle resp. \\/Browser/IWebPageWindow + window
@@ -233,19 +235,25 @@ handle/IUserInput). This is needed to control different webpages or tabs
 (created by the createPageWindow interface) with the testUI application. That
 means e.g. routing a reload command to the right webpage window.
 
-browserconfig.h|cpp handles persistant storage of configuration values and
+browserconfig.cpp handles persistant storage of configuration values and
 provides a singleton for any part of the browser to access and set these
 values.
 
-browserpage.h|cpp is a subclass of QWebPage allowing BrowserView to intercept
+browserpage.cpp is a subclass of QWebPage allowing BrowserView to intercept
 dialog boxes and prompts.
 
-cachemanager.h|cpp handles caching policies using {\tt
+cachemanager.cpp handles caching policies using {\tt
 QNetworkConnectionManager}.
 
-errorlogger.h|cpp handles error logging to an in-memory storage, and allows
+errorlogger.cpp handles error logging to an in-memory storage, and allows
 D-Bus clients to query the error log.
 
+browser/unit-tests/ contains the following: {\tt browserdbus} for D-Bus tests
+of the browser and sub-components (webpageview, browserview, browserpage, etc),
+{\tt browserview} for non-D-Bus tests of the broweserview, {\tt
+cachemanagerdbus} and {\tt errorloggerdbus} for D-bus tests of {\tt
+cachemanager} and {\tt errorloggerdbus} respectively.
+
 \section{Test Application}
 \subsection{Introduction}
 With the test user-interface application, you are able to test all implemented
@@ -271,7 +279,7 @@ correct instance id and press the connect button. The instance id is defined
 with the browser application start, either 1 as default or the number given as
 parameter at browser start.
 
-The testUI application shows tabs representing the four interface groups
+The testUI application shows tabs representing the six interface groups
 ({\tt IBook\-mark\-Manager}, {\tt IBrowser}, {\tt IUserInput}, {\tt
 IWebPageWindow}, {\tt ICacheManager} and {\tt IErrorLogger}). To navigate
 between the groups, just press on the tab header.
@@ -298,7 +306,7 @@ The source code of the test user-interface application can to be found in the
 \begin{tabularx}{0.9\textwidth}{l X}
     main.cpp            & mainsource file \\
     testapp.pro         & Qt project file \\
-    {\tt QML/testapp/*} & QML files for user interface \\
+    {\tt qml/testapp/*} & QML files for user interface \\
     {\tt images/*}      & Images used in implementation (icons taken from KDE
                           oxygen theme 4.10.3)
 \end{tabularx}
@@ -320,6 +328,31 @@ and defines and calls all D-Bus interfaces and handles the return values. The
 output of all return values, resulting from D-Bus remote object calls, is logged
 onto the console.
 
+\section{Automated tests}
+The projects ships with an automated test suite, located under {\tt
+browser/unit-tests}. The tests are divided into different sub-groups, each
+placed in its own directory. The test directories ending with "dbus"
+communicate with the browser over D-Bus.
+
+The {\tt browserdbus} directry contains tests for the {\tt browser} component
+and sub-components. These tests will interact with a Webkit surface using mouse
+and keyboard input over D-Bus. For mouse input, the {\tt
+xdotool}\footnote{http://www.semicomplete.com/projects/xdotool/} is used, and
+this tool is required to be installed in {\tt \$PATH} run these tests. These
+tests also require the actual browser to be running.
+
+The {\tt browserview} directory contains tests of the {\tt browserview}
+component, these tests do not run over D-Bus.
+
+The {\tt cachemanagerdbus} directory contains D-Bus tests for the {\tt
+cachemanager}. These tests require the browser to be running.
+
+The {\tt errorloggerdbus} directory contains D-Bus tests for the error logger
+component. The tests will launch the neccessary browser components itself, and
+does not require the browser to be running. The tests will use the same D-Bus
+name space as the browser component, so running the browser during these tests
+will result in an error.
+
 \section{Demo User-Interface}
 \subsection {Introduction}
 The idea of the demo user-interface application is to have a user-interface,
@@ -376,7 +409,7 @@ The source code of the demo user-interface application can to be found in the
 \begin{tabularx}{0.9\textwidth}{l X}
     main.cpp                    & mainsource file \\
     demoui.pro                  & Qt project file \\
-    {\tt QML/demoui/*}          & QML files for user interface \\
+    {\tt qml/demoui/*}          & QML files for user interface \\
     {\tt qtquick2application/*} & Classes for displaying a QtQuick UI \\
     {\tt images/*}              & Images used in implementation (icons taken
                                   from KDE oxygen theme 4.10.3)
diff --git a/documentation/designdocument/demoui.png b/documentation/designdocument/demoui.png
new file mode 100644
index 0000000..9559e25
--- /dev/null
+++ b/documentation/designdocument/demoui.png
diff --git a/documentation/designdocument/testui.png b/documentation/designdocument/testui.png
new file mode 100644
index 0000000..fba6add
--- /dev/null
+++ b/documentation/designdocument/testui.png