Merge pull request #182 from gempesaw/parameter-finders

Install parameter find subs that don't croak

lib/Selenium/Remote/Driver.pm

@@ -22,6 +22,7 @@ use Selenium::Remote::Commands;
 use Selenium::Remote::WebElement;
 use File::Spec::Functions ();
 use File::Basename ();
+use Sub::Install ();
 
 use constant FINDERS => {
     class             => 'class name',
@@ -420,6 +421,8 @@ has 'inner_window_size' => (
 
 );
 
+with 'Selenium::Remote::Finders';
+
 sub BUILD {
     my $self = shift;
 
@@ -438,6 +441,22 @@ sub BUILD {
         my $size = $self->inner_window_size;
         $self->set_inner_window_size(@$size);
     }
+
+    # Setup non-croaking, parameter versions of finders
+    foreach my $by (keys %{ $self->FINDERS }) {
+        my $finder_name = 'find_element_by_' . $by;
+        # In case we get instantiated multiple times, we don't want to
+        # install into the name space every time.
+        unless ($self->can($finder_name)) {
+            my $find_sub = $self->_build_find_by($by);
+
+            Sub::Install::install_sub({
+                code => $find_sub,
+                into => __PACKAGE__,
+                as   => $finder_name,
+            });
+        }
+    }
 }
 
 sub new_from_caps {
@@ -1752,8 +1771,27 @@ sub get_page_source {
 =head2 find_element
 
  Description:
-    Search for an element on the page, starting from the document root. The
-    located element will be returned as a WebElement object.
+    Search for an element on the page, starting from the document
+    root. The located element will be returned as a WebElement
+    object. If the element cannot be found, we will CROAK, killing
+    your script. If you wish for a warning instead, use the
+    parameterized version of the finders:
+
+        find_element_by_class
+        find_element_by_class_name
+        find_element_by_css
+        find_element_by_id
+        find_element_by_link
+        find_element_by_link_text
+        find_element_by_name
+        find_element_by_partial_link_text
+        find_element_by_tag_name
+        find_element_by_xpath
+
+    These functions all take a single STRING argument: the locator
+    search target of the element you want. If the element is found, we
+    will receive a WebElement. Otherwise, we will return 0. Note that
+    invoking methods on 0 will of course kill your script.
 
  Input: 2 (1 optional)
     Required:
@@ -2005,6 +2043,46 @@ sub find_child_elements {
     }
 }
 
+=head2 find_element_by_class
+
+See L</find_element>.
+
+=head2 find_element_by_class_name
+
+See L</find_element>.
+
+=head2 find_element_by_css
+
+See L</find_element>.
+
+=head2 find_element_by_id
+
+See L</find_element>.
+
+=head2 find_element_by_link
+
+See L</find_element>.
+
+=head2 find_element_by_link_text
+
+See L</find_element>.
+
+=head2 find_element_by_name
+
+See L</find_element>.
+
+=head2 find_element_by_partial_link_text
+
+See L</find_element>.
+
+=head2 find_element_by_tag_name
+
+See L</find_element>.
+
+=head2 find_element_by_xpath
+
+See L</find_element>.
+
 =head2 get_active_element
 
  Description:

lib/Selenium/Remote/Finders.pm

@@ -0,0 +1,36 @@
+package Selenium::Remote::Finders;
+
+# ABSTRACT: Handle construction of generic parameter finders
+use Try::Tiny;
+use Carp qw/carp/;
+use Moo::Role;
+use namespace::clean;
+
+=head1 DESCRIPTION
+
+This package just takes care of setting up parameter finders - that
+is, the C<find_element_by_.*> versions of the find element
+functions. You probably don't need to do anything with this package;
+instead, see L<Selenium::Remote::Driver/find_element> documentation
+for the specific finder functions.
+
+=cut
+
+sub _build_find_by {
+    my ($self, $by) = @_;
+
+    return sub {
+        my ($driver, $locator) = @_;
+        my $strategy = $by;
+
+        return try {
+            return $driver->find_element($locator, $strategy);
+        }
+        catch {
+            carp $_;
+            return 0;
+        };
+    }
+}
+
+1;

t/Finders.t

@@ -0,0 +1,57 @@
+#! /usr/bin/perl
+
+use strict;
+use warnings;
+use Test::More;
+
+BEGIN: {
+    unless (use_ok('Selenium::Remote::Driver')) {
+        BAIL_OUT("Couldn't load Selenium::Remote::Driver");
+        exit;
+    }
+}
+
+use FindBin;
+use lib $FindBin::Bin . '/lib';
+use TestHarness;
+
+my $harness = TestHarness->new(
+    this_file => $FindBin::Script
+);
+
+my %selenium_args = %{ $harness->base_caps };
+
+my $driver = Selenium::Remote::Driver->new(%selenium_args);
+$driver->get('http://danielgempesaw.com/Selenium-Remote-Driver/xhtmlTest.html');
+
+# This depends explicitly on the page we're visiting (xhtmlTest.html),
+my %finders = (
+    class => 'navigation',
+    class_name => 'navigation',
+    css => 'html',
+    id => 'linkId',
+    link => 'this goes to the same place',
+    link_text => 'this goes to the same place',
+    name => 'windowOne',
+    partial_link_text => 'this goes to the same',
+    tag_name => 'html',
+    xpath => '//html'
+);
+
+foreach my $by (keys %finders) {
+    my $locator = $finders{$by};
+    my $method = 'find_element_by_' . $by;
+
+    ok($driver->can($method), $method . ':  installed properly');
+    my $elem = $driver->$method($locator);
+    ok($elem, $method . ': finds an element properly');
+    ok($elem->isa('Selenium::Remote::WebElement'), $method . ': element is a WebElement');
+    {
+        # Briefly suppress warning output for prettier tests
+        my $warned = 0;
+        local $SIG{__WARN__} = sub { $warned++ };
+        ok(!$driver->$method('missing') , $method . ': does not croak on unavailable elements');
+        ok($warned, $method . ': unavailable elements throw a warning');
+    }
+}
+done_testing;