[libweasel-perl] 18/24: * Add README.md

[Robert James Clay]

This is an automated email from the git hooks/post-receive script.

jame-guest pushed a commit to tag v0.02
in repository libweasel-perl.

commit e8f450ca828c2880dcb1c999c21dc35405ba9704
Author: Erik Huelsmann <ehuels at gmail.com>
Date:   Wed Jun 22 16:20:32 2016 +0200

    * Add README.md
---
 README.md | 143 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e7506a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,143 @@
+
+
+# NAME
+
+Weasel - Perl's php/Mink-inspired abstracted web-driver framework
+
+# VERSION
+
+0.01
+
+# SYNOPSIS
+
+```perl
+  use Weasel;
+  use Weasel::Session;
+  use Weasel::Driver::Selenium2;
+
+  my $weasel = Weasel->new(
+       default_session => 'default',
+       sessions => {
+          default => Weasel::Session->new(
+            driver => Weasel::Driver::Selenium2->new(%opts),
+          ),
+       });
+
+  $weasel->session->get('http://localhost/index');
+```
+
+# DESCRIPTION
+
+This module abstracts away the differences between the various
+web-driver protocols, like the Mink project does for PHP.
+
+While heavily inspired by Mink, `Weasel` aims to improve over it
+by being extensible, providing not just access to the underlying
+browser, yet to provide building blocks for further development
+and abstraction.
+
+[Pherkin::Extension::Weasel](https://github.com/perl-weasel/pherkin-extension-weasel)
+provides integration with
+[Test::BDD::Cucumber](https://github.com/pjlsergeant/test-bdd-cucumber-perl)
+(aka pherkin), for BDD testing.
+
+For the actual page interaction, this module needs a driver to
+be installed.  Currently, that means
+[Weasel::Driver::Selenium2](https://github.com/perl-weasel/weasel-driver-selenium2).
+Other driver implementations, such as [Sahi](http://sahipro.com/)
+can be independently developed and uploaded to CPAN, or contributed.
+(We welcome and encourage both!)
+
+
+## DIFFERENCES WITH OTHER FRAMEWORKS
+
+
+### Mnemonics for element lookup patterns
+
+The central registry of xpath expressions to find common page elements
+helps to keep page access code clean. E.g. compare:
+
+```perl
+   use Weasel::FindExpanders::HTML;
+   $session->page->find('*contains', text => 'Some text');
+```
+
+With
+
+```perl
+   $session->page->find(".//*[contains(.,'Some text')]
+                              [not(.//*[contains(.,'Some text')])]");
+```
+
+Multiple patterns can be registered for a single mnemonic, which
+will be concatenated to a single xpath expression to find the matching
+tags in a single driver query.
+
+Besides good performance, this has the benefit that the following
+
+```perl
+   $session->page->find('*button', text => 'Click!');
+```
+
+can be easily extended to match
+[Dojo toolkit's](http://dojotoolkit.org/documentation/) buttons, which
+on the HTML level don't contain visible button or input tags, simply
+by using the widget support set:
+
+```perl
+   use Weasel::Widgets::Dojo;
+```
+
+### Widgets encapsulate specific behaviours
+
+All elements in `Weasel` are of the base type `Weasel::Element`, which
+encapsulates the regular element interactions (click, find children, etc).
+
+While most elements will be represented by `Weasel::Element`, it's possible
+to implement other wrappers.  These offer a logical extension point to
+implement tag-specific utility functions.  E.g.
+`Weasel::Widgets::HTML::Select`, which adds the utility function
+`select_option`.
+
+These widgets also offer a good way to override default behaviours.  One
+such case is the Dojo implementation of a `select` element.  This element
+replaces the select tag entirely and in contrast with the original, doesn't
+keep the options as child elements of the `select`-replacing tag.  By using
+the Dojo widget library
+
+```perl
+   use Weasel::Widget::Dojo;
+```
+
+the lack of the parent/child relation between the the select and its options
+is transparently handled by overriding the widget's `find` and `find_all`
+methods.
+
+# INSTALLATION
+
+```sh
+  # Install Weasel
+  $ cpanm Weasel
+
+  # Install Weasel's web driver
+  $ cpanm Weasel::Driver::Selenium2
+```
+
+If you want to use Weasel with its Pherkin (BDD) integration, also:
+
+```sh
+  $ cpanm Pherkin::Extension::Weasel
+```
+
+# SUPPORT
+
+## BUGS
+
+Bugs can be filed in the GitHub issue tracker for the Weasel project:
+ https://github.com/perl-weasel/weasel/issues
+
+## DISCUSSION
+
+Community support is available through
+[perl-weasel at googlegroups.com](mailto:perl-weasel at googlegroups.com).
+

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libweasel-perl.git