Initial commit

Quviq · Jun 10, 2013 · 8d05e46 · 8d05e46
commit 8d05e46
Show file tree

Hide file tree

Showing 19 changed files with 3,582 additions and 0 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,26 @@
+VERSION=1.0
+RELDIR=./rel/webdrv-$(VERSION)
+
+all: compile doc
+.PHONY: test doc
+
+compile: 
+	@(cd src; erl -make)
+
+test: 
+	@(cd test; erl -make)
+
+doc:
+	erl -eval "edoc:application(webdrv,\".\",[{dir, \"./doc\"}, {preprocess, true}])" \
+-s init stop -noshell
+
+release: compile
+	rm -rf $(RELDIR);\
+mkdir -p $(RELDIR);\
+cp -r ebin doc include $(RELDIR)
+
+clean:
+	rm -f ebin/*.beam; \
+rm -f doc/*.html; \
+rm -f doc/*.png doc/*info doc/*.css; \
+rm -rf rel
diff --git a/README.md b/README.md
@@ -0,0 +1,66 @@
+webdrv - WebDriver implementation in Erlang
+===========================================
+
+This package contains an implementation of the WebDriver API in Erlang. The WebDriver API
+provides a platform- and language-neutral interface that allows programs to control the
+behavior and inspect the state of a web browser. It is mainly intended for automated
+tests, but can also be used to control a browser for other purposes.
+
+The WebDriver API is accessed via http-requests, data is serialized using JSON.
+
+This package contains two levels; one purerly functional level, where separate WebDriver
+commands can be made, and a gen_server based level, wrapping the concept of a WebDriver
+session (i.e. an interaction with a browser instance).
+
+The WebDriver API is currently being standardized by W3C (the latest working draft when
+writing this is from May 30th 2013), however the main implementors of the server-side of
+WebDriver (like Selenium and ChromeDriver) still follow the protocol as described by
+Selenium --
+[The WebDriver Wire Protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol).
+
+This implementation spans most of what is covered by the Wire Protocol, with the exception
+of the Touch interface, Geographical location and local storage. Extending with these
+things should be straightforward but we have not seen a usage of this functionality yet. 
+
+The package also contains tests, in the form of a [QuickCheck](http://quviq.com/) model,
+testing both the session wrapper and the Wire Protocol. Page navigation, window control
+and element location is well tested, while page element interaction and cookies remains as
+TODO.
+
+Building and Installing
+-----------------------
+
+There is a simplistic `Makefile` included in the repository. The command:
+
+    make all
+
+compiles all sources to BEAM's, and builds the documentation. `make all` is short for
+`make compile` and `make doc`. The command:
+
+    make test
+
+compiles all tests (to `./ebin`). The command:
+
+    make release
+
+creates a ready-to-be-installed directory in `./rel/webdrv-VERSION`. There is no automagic
+installation, if you want the library permanently in your code path; copy the generated
+directory to your `$ERLANG/lib/`. Finally, the command:
+
+    make clean
+
+removes all(?) generated files from the project.
+
+Contributing
+------------
+
+Please don't hesitate to improve and/or extend the implementation or the tests, there is
+plenty of room for improvement. The easiest way to contribute is:
+
+1. Fork it.
+2. Create a branch (`git checkout -b my_webdriver`)
+3. Commit your changes (`git commit -am "Added new cool feature X"`)
+4. Push to the branch (`git push origin my_webdriver`)
+5. Open a [Pull Request][1]
+
+[1]: http://github.com/Quviq/webdrv/pulls
diff --git a/data/elements.html b/data/elements.html
@@ -0,0 +1,11 @@
+<HTML>
+<HEAD></HEAD>
+<BODY>
+<UL>
+<LI id="id1" name="name1" class="class1"><A href="./elements.html">Link1</A></LI>
+<LI id="id2" name="name2" class="class2"><A href="./elements.html">Link2</A></LI>
+<LI id="id3" name="name3" class="class3"><A href="./elements.html">Link3</A></LI>
+</UL>
+<HR>
+</BODY>
+</HTML>
diff --git a/data/page0.html b/data/page0.html
@@ -0,0 +1,6 @@
+<HTML>
+<BODY>
+<H1>A simple test page0!</H1>
+</HR>
+</BODY>
+</HTML>
diff --git a/data/page1.html b/data/page1.html
@@ -0,0 +1,6 @@
+<HTML>
+<BODY>
+<H1>A simple test page1!</H1>
+</HR>
+</BODY>
+</HTML>
diff --git a/data/page2.html b/data/page2.html
@@ -0,0 +1,6 @@
+<HTML>
+<BODY>
+<H1>A simple test page2!</H1>
+</HR>
+</BODY>
+</HTML>
diff --git a/data/windows.html b/data/windows.html
@@ -0,0 +1,7 @@
+<HTML>
+<BODY>
+<A NAME="WINDOW-0" HREF="" target="WINDOW-0">Open window/tab named WINDOW0</A></BR>
+<A NAME="WINDOW-1" HREF="" target="WINDOW-1">Open window/tab named WINDOW1</A></BR>
+<A NAME="WINDOW-2" HREF="" target="WINDOW-2">Open window/tab named WINDOW2</A></BR>
+</BODY>
+</HTML>
diff --git a/doc/overview.edoc b/doc/overview.edoc
@@ -0,0 +1,57 @@
+------------------------------------------------------------------
+@author Hans Svensson <[email protected]>
+@copyright (C) 2013, Quviq AB
+
+@title WebDriver implementation for Erlang
+
+@doc 
+
+This package contains an implementation of the WebDriver API in Erlang. The WebDriver API
+provides a platform- and language-neutral interface that allows programs to control the
+behavior and inspect the state of a web browser. It is mainly intended for automated
+tests, but can also be used to control a browser for other purposes.
+
+The WebDriver API is accessed via http-requests, data is serialized using JSON. 
+
+This package contains two levels; one purerly functional level, where separate WebDriver
+commands can be made, and a gen_server based level, wrapping the concept of a WebDriver
+session (i.e. an interaction with a browser instance).
+
+The WebDriver API is currently being standardized by W3C (the latest working draft when
+writing this is from May 30th 2013), however the main implementors of the server-side of
+WebDriver (like Selenium and ChromeDriver) still follow the protocol as described by
+Selenium (<a href="https://code.google.com/p/selenium/wiki/JsonWireProtocol">The WebDriver
+Wire Protocol</a>).
+
+This implementation spans most of what is covered by the Wire Protocol, with the exception
+of the Touch interface, Geographical location and local storage. Extending with these
+things should be straightforward but we have not seen a usage of this functionality yet. 
+
+The package also contains tests, in the form of a <a
+href="http://quviq.com/">QuickCheck</a> model, testing both the session wrapper and the
+Wire Protocol. Page navigation, window control and element location is well tested, while
+page element interaction and cookies remains as TODO.
+
+<h2>License</h2>
+<pre>
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy,
+modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. </pre>
+@end
+------------------------------------------------------------------
diff --git a/ebin/Emakefile b/ebin/Emakefile
@@ -0,0 +1,2 @@
+{'../src/*', []}.
+{'../test/*', []}.
diff --git a/include/webdrv.hrl b/include/webdrv.hrl
@@ -0,0 +1,76 @@
+%%%-------------------------------------------------------------------
+%%% @author Hans Svensson <[email protected]>
+%%% @copyright (C) 2013, Quviq AB
+%%% @license
+%%% Permission is hereby granted, free of charge, to any person
+%%% obtaining a copy of this software and associated documentation
+%%% files (the "Software"), to deal in the Software without
+%%% restriction, including without limitation the rights to use, copy,
+%%% modify, merge, publish, distribute, sublicense, and/or sell copies
+%%% of the Software, and to permit persons to whom the Software is
+%%% furnished to do so, subject to the following conditions:
+%%%
+%%% The above copyright notice and this permission notice shall be
+%%% included in all copies or substantial portions of the Software.
+%%%
+%%% THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+%%% EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+%%% MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+%%% NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+%%% BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+%%% ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+%%% CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+%%% SOFTWARE.
+%%%-------------------------------------------------------------------
+%%% @doc
+%%% Includes for WebDriver
+%%% @end
+%%%-------------------------------------------------------------------
+
+-record(capability,
+        { browserName
+        %% , browserVersion
+        , version = <<"">>
+        %% , platformName
+        , platform = <<"ANY">>
+        %% , platformVersion
+        , javascriptEnabled = true
+        }).
+
+-record(webdrv_opts, { url, timeout = 5000, session_id = null }).
+
+-type session_id() :: string() | null.
+-type url() :: string().
+
+-type frame_id() :: jsonstr() | number() | null.
+
+-type json()     :: jsonobj() | jsonlist() | jsonnum() | jsonstr() | true | false | null.
+-type jsonobj()  :: {obj, [{jsonkey(), json()}]}.
+-type jsonkey()  :: string().
+-type jsonlist() :: [json()].
+-type jsonnum()  :: integer() | float().
+-type jsonstr()  :: binary().
+
+-type request_error() :: {html_error, string()}
+                       | {json_error, string()}
+                       | {cmd_error, json()}
+                       | {wire_error, {atom(), string()}, session_id()}
+                       | {type_error, atom(), term()}.
+
+-type request_ok() :: {ok, session_id(), jsonobj()}.
+
+-type request_res() :: request_ok() | request_error().
+
+-type capability() :: #capability{} | null | jsonobj().
+
+-type orientation() :: landscape | portrait.
+-type cookie() :: jsonobj().
+
+-type button() :: integer() | left | middle | right.
+
+-type log_entry() :: {number(), string(), string()}.
+-type log() :: [log_entry()].
+
+-type cache_status() ::
+        uncached | idle | checking | downloading | update_ready | obsolete.
+
diff --git a/src/Emakefile b/src/Emakefile
@@ -0,0 +1 @@
+{'*', [{outdir, "../ebin"}]}.