Bug 1368265 - Provide a webdriver README. r=automatedtester
authorAndreas Tolfsen <ato@sny.no>
Sun, 03 Sep 2017 17:15:03 +0100
changeset 428262 4d2853618098b54be46de2441915f45dad83701d
parent 428261 ad94237d3b324eaf97de5baf748a9a3ffa6b3501
child 428263 04786fb4329f19533f7d394e1f7b7f515620b7d8
push id7761
push userjlund@mozilla.com
push dateFri, 15 Sep 2017 00:19:52 +0000
treeherdermozilla-beta@c38455951db4 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersautomatedtester
bugs1368265
milestone57.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1368265 - Provide a webdriver README. r=automatedtester Documentation is the hallmark of a good software library and this isn't great, but it is a step in the right direction. MozReview-Commit-ID: IHDwp2pjXom
testing/webdriver/README.md
--- a/testing/webdriver/README.md
+++ b/testing/webdriver/README.md
@@ -1,6 +1,101 @@
-# webdriver Rust library [![Crate version](https://img.shields.io/crates/v/webdriver.svg)](https://crates.io/crates/webdriver) [![Documentation](https://docs.rs/webdriver/badge.svg)](https://docs.rs/webdriver/) [![Build status](https://travis-ci.org/mozilla/webdriver-rust.svg?branch=master)](https://travis-ci.org/mozilla/webdriver-rust) 
+webdriver library
+=================
+
+The [webdriver crate] is a library implementation of the wire protocol
+for the [W3C WebDriver standard] written in Rust.  WebDriver is a remote
+control interface that enables introspection and control of user agents.
+It provides a platform- and language-neutral wire protocol as a way
+for out-of-process programs to remotely instruct the behaviour of web
+browsers.
+
+The webdriver library provides the formal types, error codes, type and
+bounds checks, and JSON marshaling conventions for correctly parsing
+and emitting the WebDriver protocol.  It also provides an HTTP server
+where endpoints are mapped to the different WebDriver commands.
+
+**As of right now, this is an implementation for the server side of the
+WebDriver API in Rust, not the client side.**
+
+[webdriver crate]: https://crates.io/crates/webdriver
+[W3C WebDriver standard]: https://w3c.github.io/webdriver/webdriver-spec.html
+
+
+Building
+========
+
+The library is built using the usual [Rust conventions]:
+
+    % cargo build
+
+To run the tests:
+
+    % cargo test
+
+[Rust conventions]: http://doc.crates.io/guide.html
+
+
+Usage
+=====
+
+To start an HTTP server that handles incoming command requests, a request
+handler needs to be implemented.  It takes an incoming `WebDriverMessage`
+and emits a `WebDriverResponse`:
 
-As of right now this is an implementation
-for the server side of the WebDriver API in Rust,
-not the client side.
+	impl WebDriverHandler for MyHandler {
+	    fn handle_command(
+	        &mut self,
+	        _: &Option<Session>,
+	        msg: WebDriverMessage,
+	    ) -> WebDriverResult<WebDriverResponse> {
+	        …
+	    }
+
+	    fn delete_session(&mut self, _: &Option<Session>) {
+	        …
+	    }
+	}
+
+	let addr = SocketAddr::new("localhost", 4444);
+	let handler = MyHandler {};
+	let server = webdriver::server::start(addr, handler, vec![])?;
+	info!("Listening on {}", server.socket);
+
+It is also possible to provide so called [extension commands] by providing
+a vector of known extension routes, for which each new route needs to
+implement the `WebDriverExtensionRoute` trait.  Each route needs to map
+to a `WebDriverExtensionCommand`:
+
+	pub enum MyExtensionRoute { HelloWorld }
+	pub enum MyExtensionCommand { HelloWorld }
 
+	impl WebDriverExtensionRoute for MyExtensionRoute {
+	    fn command(
+	        &self,
+	        captures: &Captures,
+	        body: &Json,
+	    ) -> WebDriverResult<WebDriverCommand<MyExtensionCommand>> {
+	        …
+	    }
+	}
+
+	let extension_routes = vec![
+	    (Method::Get, "/session/{sessionId}/moz/hello", MyExtensions::HelloWorld)
+	];
+
+	…
+
+	let server = webdriver::server::start(addr, handler, extension_routes[..])?;
+
+[extension commands]: https://w3c.github.io/webdriver/webdriver-spec.html#dfn-extension-commands
+
+Contact
+=======
+
+The mailing list for webdriver discussion is
+tools-marionette@lists.mozilla.org ([subscribe], [archive]).
+
+There is also an IRC channel to talk about using and developing webdriver
+in #ateam on irc.mozilla.org.
+
+[subscribe]: https://lists.mozilla.org/listinfo/tools-marionette
+[archive]: http://groups.google.com/group/mozilla.tools.marionette