File Coverage

blib/lib/Selenium/Remote/Driver.pm

Criterion	Covered	Total	%
statement	408	700	58.2
branch	113	258	43.8
condition	56	134	41.7
subroutine	87	124	70.1
pod	83	85	97.6
total	747	1301	57.4

package Selenium::Remote::Driver;
$Selenium::Remote::Driver::VERSION = '1.48';
use strict;
use warnings;

# ABSTRACT: Perl Client for Selenium Remote Driver

use Moo;
use Try::Tiny;

use 5.006;
use v5.10.0;    # Before 5.006, v5.10.0 would not be understood.

# See http://perldoc.perl.org/5.10.0/functions/use.html#use-VERSION
# and http://www.dagolden.com/index.php/369/version-numbers-should-be-boring/
# for details.

use Carp;
our @CARP_NOT;

use IO::String;
use Archive::Zip qw( :ERROR_CODES );
use Scalar::Util;
use Selenium::Remote::RemoteConnection;
use Selenium::Remote::Commands;
use Selenium::Remote::Spec;
use Selenium::Remote::WebElement;
use Selenium::Remote::WDKeys;
use File::Spec::Functions ();
use File::Basename qw(basename);
use Sub::Install ();
use MIME::Base64 ();
use Time::HiRes qw(usleep);
use Clone qw{clone};
use List::Util qw{any};

use constant FINDERS => {
    class             => 'class name',
    class_name        => 'class name',
    css               => 'css selector',
    id                => 'id',
    link              => 'link text',
    link_text         => 'link text',
    name              => 'name',
    partial_link_text => 'partial link text',
    tag_name          => 'tag name',
    xpath             => 'xpath',
};

our $FORCE_WD2            = 0;
our $FORCE_WD3            = 0;
our %CURRENT_ACTION_CHAIN = ( actions => [] );




has 'remote_server_addr' => (
    is     => 'rw',
    coerce => sub { ( defined( $_[0] ) ? $_[0] : 'localhost' ) },
    default   => sub { 'localhost' },
    predicate => 1
);

has 'browser_name' => (
    is     => 'rw',
    coerce => sub { ( defined( $_[0] ) ? $_[0] : 'firefox' ) },
    default => sub { 'firefox' },
);

has 'base_url' => (
    is     => 'lazy',
    coerce => sub {
        my $base_url = shift;
        $base_url =~ s|/$||;
        return $base_url;
    },
    predicate => 'has_base_url',
);

has 'platform' => (
    is     => 'rw',
    coerce => sub { ( defined( $_[0] ) ? $_[0] : 'ANY' ) },
    default => sub { 'ANY' },
);

has 'port' => (
    is     => 'rw',
    coerce => sub { ( defined( $_[0] ) ? $_[0] : '4444' ) },
    default   => sub { '4444' },
    predicate => 1
);

has 'version' => (
    is      => 'rw',
    default => sub { '' },
);

has 'webelement_class' => (
    is      => 'rw',
    default => sub { 'Selenium::Remote::WebElement' },
);

has 'default_finder' => (
    is      => 'rw',
    coerce  => sub { __PACKAGE__->FINDERS->{ $_[0] } },
    default => sub { 'xpath' },
);

has 'session_id' => (
    is      => 'rw',
    default => sub { undef },
);

has 'remote_conn' => (
    is      => 'lazy',
    builder => sub {
        my $self = shift;
        return Selenium::Remote::RemoteConnection->new(
            remote_server_addr => $self->remote_server_addr,
            port               => $self->port,
            ua                 => $self->ua,
            wd_context_prefix  => $self->wd_context_prefix
        );
    },
);

has 'error_handler' => (
    is     => 'rw',
    coerce => sub {
        my ($maybe_coderef) = @_;

        if ( ref($maybe_coderef) eq 'CODE' ) {
            return $maybe_coderef;
        }
        else {
            croak 'The error handler must be a code ref.';
        }
    },
    clearer   => 1,
    predicate => 1
);

has 'ua' => (
    is      => 'lazy',
    builder => sub { return LWP::UserAgent->new }
);

has 'commands' => (
    is      => 'lazy',
    builder => sub {
        return Selenium::Remote::Commands->new;
    },
);

has 'commands_v3' => (
    is      => 'lazy',
    builder => sub {
        return Selenium::Remote::Spec->new;
    },
);

has 'auto_close' => (
    is     => 'rw',
    coerce => sub { ( defined( $_[0] ) ? $_[0] : 1 ) },
    default => sub { 1 },
);

has 'pid' => (
    is      => 'lazy',
    builder => sub { return $$ }
);

has 'javascript' => (
    is     => 'rw',
    coerce => sub { $_[0] ? JSON::true : JSON::false },
    default => sub { return JSON::true }
);

has 'accept_ssl_certs' => (
    is     => 'rw',
    coerce => sub { $_[0] ? JSON::true : JSON::false },
    default => sub { return JSON::true }
);

has 'proxy' => (
    is     => 'rw',
    coerce => sub {
        my $proxy = $_[0];
        if ( $proxy->{proxyType} =~ /^pac$/i ) {
            if ( not defined $proxy->{proxyAutoconfigUrl} ) {
                croak "proxyAutoconfigUrl not provided\n";
            }
            elsif ( not( $proxy->{proxyAutoconfigUrl} =~ /^(http|file)/g ) ) {
                croak
                  "proxyAutoconfigUrl should be of format http:// or file://";
            }

            if ( $proxy->{proxyAutoconfigUrl} =~ /^file/ ) {
                my $pac_url = $proxy->{proxyAutoconfigUrl};
                my $file    = $pac_url;
                $file =~ s{^file://}{};

                if ( !-e $file ) {
                    warn "proxyAutoConfigUrl file does not exist: '$pac_url'";
                }
            }
        }
        $proxy;
    },
);

has 'extra_capabilities' => (
    is      => 'rw',
    default => sub { {} }
);

has 'firefox_profile' => (
    is     => 'rw',
    coerce => sub {
        my $profile = shift;
        unless ( Scalar::Util::blessed($profile)
            && $profile->isa('Selenium::Firefox::Profile') )
        {
            croak "firefox_profile should be a Selenium::Firefox::Profile\n";
        }

        return $profile;
    },
    predicate => 'has_firefox_profile',
    clearer   => 1
);

has debug => (
    is => 'lazy',
    default => sub { 0 },
);

has 'desired_capabilities' => (
    is        => 'lazy',
    predicate => 'has_desired_capabilities'
);

has 'inner_window_size' => (
    is        => 'lazy',
    predicate => 1,
    coerce    => sub {
        my $size = shift;

        croak "inner_window_size must have two elements: [ height, width ]"
          unless scalar @$size == 2;

        foreach my $dim (@$size) {
            croak 'inner_window_size only accepts integers, not: ' . $dim
              unless Scalar::Util::looks_like_number($dim);
        }

        return $size;
    },

);

# At the time of writing, Geckodriver uses a different endpoint than
# the java bindings for executing synchronous and asynchronous
# scripts. As a matter of fact, Geckodriver does conform to the W3C
# spec, but as are bound to support both while the java bindings
# transition to full spec support, we need some way to handle the
# difference.

has '_execute_script_suffix' => (
    is      => 'lazy',
    default => ''
);

with 'Selenium::Remote::Finders';
with 'Selenium::Remote::Driver::CanSetWebdriverContext';

sub BUILD {
    my $self = shift;

    if ( !( defined $self->session_id ) ) {
        if ( $self->has_desired_capabilities ) {
            $self->new_desired_session( $self->desired_capabilities );
        }
        else {
            # Connect to remote server & establish a new session
            $self->new_session( $self->extra_capabilities );
        }
    }

    if ( !( defined $self->session_id ) ) {
        croak "Could not establish a session with the remote server\n";
    }
    elsif ( $self->has_inner_window_size ) {
        my $size = $self->inner_window_size;
        $self->set_inner_window_size(@$size);
    }

    #Set debug if needed
    $self->debug_on() if $self->debug;

    # 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 {
    my ( $self, %args ) = @_;

    if ( not exists $args{desired_capabilities} ) {
        $args{desired_capabilities} = {};
    }

    return $self->new(%args);
}

sub DEMOLISH {
    my ( $self, $in_global_destruction ) = @_;
    return if $$ != $self->pid;
    return if $in_global_destruction;
    $self->quit() if ( $self->auto_close && defined $self->session_id );
}

# We install an 'around' because we can catch more exceptions this way
# than simply wrapping the explicit croaks in _execute_command.
# @args should be fed to the handler to provide context
# return_value could be assigned from the handler if we want to allow the
# error_handler to handle the errors

around '_execute_command' => sub {
    my $orig = shift;
    my $self = shift;

    # copy @_ because it gets lost in the way
    my @args = @_;
    my $return_value;
    try {
        $return_value = $orig->( $self, @args );
    }
    catch {
        if ( $self->has_error_handler ) {
            $return_value = $self->error_handler->( $self, $_, @args );
        }
        else {
            croak $_;
        }
    };
    return $return_value;
};

# This is an internal method used the Driver & is not supposed to be used by
# end user. This method is used by Driver to set up all the parameters
# (url & JSON), send commands & receive processed response from the server.
sub _execute_command {
    my ( $self, $res, $params ) = @_;
    $res->{'session_id'} = $self->session_id;

    print "Prepping $res->{command}\n" if $self->{debug};

    #webdriver 3 shims
    return $self->{capabilities}
      if $res->{command} eq 'getCapabilities' && $self->{capabilities};
    $res->{ms}    = $params->{ms}    if $params->{ms};
    $res->{type}  = $params->{type}  if $params->{type};
    $res->{text}  = $params->{text}  if $params->{text};
    $res->{using} = $params->{using} if $params->{using};
    $res->{value} = $params->{value} if $params->{value};

    print "Executing $res->{command}\n" if $self->{debug};
    my $resource =
        $self->{is_wd3}
      ? $self->commands_v3->get_params($res)
      : $self->commands->get_params($res);

    #Fall-back to legacy if wd3 command doesn't exist
    if ( !$resource && $self->{is_wd3} ) {
        print "Falling back to legacy selenium method for $res->{command}\n"
          if $self->{debug};
        $resource = $self->commands->get_params($res);
    }

    #XXX InternetExplorerDriver quirks
    if ( $self->{is_wd3} && $self->browser_name eq 'internet explorer' ) {
        delete $params->{ms};
        delete $params->{type};
        delete $resource->{payload}->{type};
        my $oldvalue = delete $params->{'page load'};
        $params->{pageLoad} = $oldvalue if $oldvalue;
    }

    if ($resource) {
        $params = {} unless $params;
        my $resp = $self->remote_conn->request( $resource, $params );

#In general, the parse_response for v3 is better, which is why we use it *even if* we are falling back.
        return $self->commands_v3->parse_response( $res, $resp )
          if $self->{is_wd3};
        return $self->commands->parse_response( $res, $resp );
    }
    else {
        #Tell the use about the offending setting.
        croak "Couldn't retrieve command settings properly ".$res->{command}."\n";
    }
}


sub new_session {
    my ( $self, $extra_capabilities ) = @_;
    $extra_capabilities ||= {};

    my $args = {
        'desiredCapabilities' => {
            'browserName'       => $self->browser_name,
            'platform'          => $self->platform,
            'javascriptEnabled' => $self->javascript,
            'version'           => $self->version // '',
            'acceptSslCerts'    => $self->accept_ssl_certs,
            %$extra_capabilities,
        },
    };
    $args->{'extra_capabilities'} = \%$extra_capabilities unless $FORCE_WD2;

    if ( defined $self->proxy ) {
        $args->{desiredCapabilities}->{proxy} = $self->proxy;
    }

    if (   $args->{desiredCapabilities}->{browserName} =~ /firefox/i
        && $self->has_firefox_profile )
    {
        $args->{desiredCapabilities}->{firefox_profile} =
          $self->firefox_profile->_encode;
    }

    $self->_request_new_session($args);
}


sub new_desired_session {
    my ( $self, $caps ) = @_;

    $self->_request_new_session(
        {
            desiredCapabilities => $caps
        }
    );
}

sub _request_new_session {
    my ( $self, $args ) = @_;

    #XXX UGLY shim for webdriver3
    $args->{capabilities}->{alwaysMatch} =
      clone( $args->{desiredCapabilities} );
    my $cmap = $self->commands_v3->get_caps_map();
    my $caps = $self->commands_v3->get_caps();
    foreach my $cap ( keys( %{ $args->{capabilities}->{alwaysMatch} } ) ) {

        #Handle browser specific capabilities
        if ( exists( $args->{desiredCapabilities}->{browserName} )
            && $cap eq 'extra_capabilities' )
        {

            if (
                exists $args->{capabilities}->{alwaysMatch}
                ->{'moz:firefoxOptions'}->{args} )
            {
                $args->{capabilities}->{alwaysMatch}->{$cap}->{args} =
                  $args->{capabilities}->{alwaysMatch}->{'moz:firefoxOptions'}
                  ->{args};
            }
            $args->{capabilities}->{alwaysMatch}->{'moz:firefoxOptions'} =
              $args->{capabilities}->{alwaysMatch}->{$cap}
              if $args->{desiredCapabilities}->{browserName} eq 'firefox';

#XXX the chrome documentation is lies, you can't do this yet
#$args->{capabilities}->{alwaysMatch}->{'goog:chromeOptions'}      = $args->{capabilities}->{alwaysMatch}->{$cap} if $args->{desiredCapabilities}->{browserName} eq 'chrome';
#Does not appear there are any MSIE based options, so let's just let that be
        }
        if (   exists( $args->{desiredCapabilities}->{browserName} )
            && $args->{desiredCapabilities}->{browserName} eq 'firefox'
            && $cap eq 'firefox_profile' )
        {
            if (
                ref $args->{capabilities}->{alwaysMatch}->{$cap} eq
                'Selenium::Firefox::Profile' )
            {
                #XXX not sure if I need to keep a ref to the File::Temp::Tempdir object to prevent reaping
                $args->{capabilities}->{alwaysMatch}->{'moz:firefoxOptions'}
                  ->{args} = [
                    '-profile',
                    $args->{capabilities}->{alwaysMatch}->{$cap}->{profile_dir}
                      ->dirname()
                  ];
            }
        }
        foreach my $newkey ( keys(%$cmap) ) {
            if ( $newkey eq $cap ) {
                last if $cmap->{$newkey} eq $cap;
                $args->{capabilities}->{alwaysMatch}->{ $cmap->{$newkey} } =
                  $args->{capabilities}->{alwaysMatch}->{$cap};
                delete $args->{capabilities}->{alwaysMatch}->{$cap};
                last;
            }
        }
        delete $args->{capabilities}->{alwaysMatch}->{$cap}
          if !any { $_ eq $cap } @$caps;
    }
    delete $args->{desiredCapabilities}
      if $FORCE_WD3;    #XXX fork working-around busted fallback in firefox
    delete $args->{capabilities}
      if $FORCE_WD2; #XXX 'secret' feature to help the legacy unit tests to work

    #Delete compatibility layer when using drivers directly
    if ( $self->isa('Selenium::Firefox') || $self->isa('Selenium::Chrome') || $self->isa('Selenium::Edge') ) {
        if (   exists $args->{capabilities}
            && exists $args->{capabilities}->{alwaysMatch} )
        {
            delete $args->{capabilities}->{alwaysMatch}->{browserName};
            delete $args->{capabilities}->{alwaysMatch}->{browserVersion};
            delete $args->{capabilities}->{alwaysMatch}->{platformName};
        }
    }

    #Fix broken out of the box chrome because they hate the maintainers of their interfaces
    if ( $self->isa('Selenium::Chrome') ) {
        if ( exists $args->{desiredCapabilities} ) {
            $args->{desiredCapabilities}{'goog:chromeOptions'}{args} //= [];
            push(@{$args->{desiredCapabilities}{'goog:chromeOptions'}{args}}, qw{no-sandbox disable-dev-shm-usage});
        }
    }

    # Get actual status
    $self->remote_conn->check_status();

    # command => 'newSession' to fool the tests of commands implemented
    # TODO: rewrite the testing better, this is so fragile.
    my $resource_new_session = {
        method => $self->commands->get_method('newSession'),
        url    => $self->commands->get_url('newSession'),
        no_content_success =>
          $self->commands->get_no_content_success('newSession'),
    };
    my $rc = $self->remote_conn;
    my $resp = $rc->request( $resource_new_session, $args, );

    if ( $resp->{cmd_status} && $resp->{cmd_status} eq 'NOT OK' ) {
        croak "Could not obtain new session: ". $resp->{cmd_return}{message};
    }

    if ( ( defined $resp->{'sessionId'} ) && $resp->{'sessionId'} ne '' ) {
        $self->session_id( $resp->{'sessionId'} );
    }
    else {
        my $error = 'Could not create new session';

        if ( ref $resp->{cmd_return} eq 'HASH' ) {
            $error .= ': ' . $resp->{cmd_return}->{message};
        }
        else {
            $error .= ': ' . $resp->{cmd_return};
        }
        croak $error;
    }

    #Webdriver 3 - best guess that this is 'whats goin on'
    if ( ref $resp->{cmd_return} eq 'HASH'
        && $resp->{cmd_return}->{capabilities} )
    {
        $self->{is_wd3}           = 1;
        $self->{emulate_jsonwire} = 1;
        $self->{capabilities}     = $resp->{cmd_return}->{capabilities};
    }

    #XXX chromedriver DOES NOT FOLLOW SPEC!
    if ( ref $resp->{cmd_return} eq 'HASH' && $resp->{cmd_return}->{chrome} ) {
        if ( defined $resp->{cmd_return}->{setWindowRect} )
        {    #XXX i'm inferring we are wd3 based on the presence of this
            $self->{is_wd3}           = 1;
            $self->{emulate_jsonwire} = 1;
            $self->{capabilities}     = $resp->{cmd_return};
        }
    }

    #XXX unsurprisingly, neither does microsoft
    if (   ref $resp->{cmd_return} eq 'HASH'
        && $resp->{cmd_return}->{pageLoadStrategy}
        && $self->browser_name eq 'MicrosoftEdge' )
    {
        $self->{is_wd3}           = 1;
        $self->{emulate_jsonwire} = 1;
        $self->{capabilities}     = $resp->{cmd_return};
    }

    return ( $args, $resp );
}


sub is_webdriver_3 {
    my $self = shift;
    return $self->{is_wd3};
}


sub debug_on {
    my ($self) = @_;
    $self->{debug} = 1;
    $self->remote_conn->debug(1);
}


sub debug_off {
    my ($self) = @_;
    $self->{debug} = 0;
    $self->remote_conn->debug(0);
}


sub get_sessions {
    my ($self) = @_;
    my $res = { 'command' => 'getSessions' };
    return $self->_execute_command($res);
}


sub status {
    my ($self) = @_;
    my $res = { 'command' => 'status' };
    return $self->_execute_command($res);
}


sub get_alert_text {
    my ($self) = @_;
    my $res = { 'command' => 'getAlertText' };
    return $self->_execute_command($res);
}


sub send_keys_to_active_element {
    my ( $self, @strings ) = @_;

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        @strings = map { split( '', $_ ) } @strings;
        my @acts = map {
            (
                {
                    type  => 'keyDown',
                    value => $_,
                },
                {
                    type  => 'keyUp',
                    value => $_,
                }
              )
        } @strings;

        my $action = {
            actions => [
                {
                    id      => 'key',
                    type    => 'key',
                    actions => \@acts,
                }
            ]
        };
        return $self->general_action(%$action);
    }

    my $res    = { 'command' => 'sendKeysToActiveElement' };
    my $params = { 'value'   => \@strings, };
    return $self->_execute_command( $res, $params );
}


sub send_keys_to_alert {
    return shift->send_keys_to_prompt(@_);
}


sub send_keys_to_prompt {
    my ( $self, $keys ) = @_;
    my $res    = { 'command' => 'sendKeysToPrompt' };
    my $params = { 'text'    => $keys };
    return $self->_execute_command( $res, $params );
}


sub accept_alert {
    my ($self) = @_;
    my $res = { 'command' => 'acceptAlert' };
    return $self->_execute_command($res);
}


sub dismiss_alert {
    my ($self) = @_;
    my $res = { 'command' => 'dismissAlert' };
    return $self->_execute_command($res);
}


sub general_action {
    my ( $self, %action ) = @_;

    _queue_action(%action);
    my $res = { 'command' => 'generalAction' };
    my $out = $self->_execute_command( $res, \%CURRENT_ACTION_CHAIN );
    %CURRENT_ACTION_CHAIN = ( actions => [] );
    return $out;
}

sub _queue_action {
    my (%action) = @_;
    if ( ref $action{actions} eq 'ARRAY' ) {
        foreach my $live_action ( @{ $action{actions} } ) {
            my $existing_action;
            foreach my $global_action ( @{ $CURRENT_ACTION_CHAIN{actions} } ) {
                if ( $global_action->{id} eq $live_action->{id} ) {
                    $existing_action = $global_action;
                    last;
                }
            }
            if ($existing_action) {
                push(
                    @{ $existing_action->{actions} },
                    @{ $live_action->{actions} }
                );
            }
            else {
                push( @{ $CURRENT_ACTION_CHAIN{actions} }, $live_action );
            }
        }
    }
}


sub release_general_action {
    my ($self) = @_;
    my $res = { 'command' => 'releaseGeneralAction' };
    %CURRENT_ACTION_CHAIN = ( actions => [] );
    return $self->_execute_command($res);
}


sub mouse_move_to_location {
    my ( $self, %params ) = @_;
    $params{element} = $params{element}{id} if exists $params{element};

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        my $origin      = $params{element};
        my $move_action = {
            type     => "pointerMove",
            duration => 0,
            x        => $params{xoffset} // 0,
            y        => $params{yoffset} // 0,
        };
        $move_action->{origin} =
          { 'element-6066-11e4-a52e-4f735466cecf' => $origin }
          if $origin;

        _queue_action(
            actions => [
                {
                    type         => "pointer",
                    id           => 'mouse',
                    "parameters" => { "pointerType" => "mouse" },
                    actions      => [$move_action],
                }
            ]
        );
        return 1;
    }

    my $res = { 'command' => 'mouseMoveToLocation' };
    return $self->_execute_command( $res, \%params );
}


sub move_to {
    return shift->mouse_move_to_location(@_);
}


sub get_capabilities {
    my $self = shift;
    my $res = { 'command' => 'getCapabilities' };
    return $self->_execute_command($res);
}


sub get_timeouts {
    my $self = shift;
    my $res = { 'command' => 'getTimeouts' };
    return $self->_execute_command( $res, {} );
}


sub set_timeout {
    my ( $self, $type, $ms ) = @_;
    if ( not defined $type ) {
        croak "Expecting type";
    }
    $ms   = _coerce_timeout_ms($ms);
    $type = 'pageLoad'
      if $type eq 'page load'
      && $self->browser_name ne
      'MicrosoftEdge';    #XXX SHIM they changed the WC3 standard mid stream

    my $res    = { 'command' => 'setTimeout' };
    my $params = { $type     => $ms };

    #XXX edge still follows earlier versions of the WC3 standard
    if ( $self->browser_name eq 'MicrosoftEdge' ) {
        $params->{ms}   = $ms;
        $params->{type} = $type;
    }
    return $self->_execute_command( $res, $params );
}


sub set_async_script_timeout {
    my ( $self, $ms ) = @_;

    return $self->set_timeout( 'script', $ms ) if $self->{is_wd3};

    $ms = _coerce_timeout_ms($ms);
    my $res    = { 'command' => 'setAsyncScriptTimeout' };
    my $params = { 'ms'      => $ms };
    return $self->_execute_command( $res, $params );
}


sub set_implicit_wait_timeout {
    my ( $self, $ms ) = @_;
    return $self->set_timeout( 'implicit', $ms ) if $self->{is_wd3};

    $ms = _coerce_timeout_ms($ms);
    my $res    = { 'command' => 'setImplicitWaitTimeout' };
    my $params = { 'ms'      => $ms };
    return $self->_execute_command( $res, $params );
}


sub pause {
    my $self = shift;
    my $timeout = ( shift // 1000 ) * 1000;
    usleep($timeout);
}


sub close {
    my $self = shift;
    my $res = { 'command' => 'close' };
    $self->_execute_command($res);
}


sub quit {
    my $self = shift;
    my $res = { 'command' => 'quit' };
    $self->_execute_command($res);
    $self->session_id(undef);
}


sub get_current_window_handle {
    my $self = shift;
    my $res = { 'command' => 'getCurrentWindowHandle' };
    return $self->_execute_command($res);
}


sub get_window_handles {
    my $self = shift;
    my $res = { 'command' => 'getWindowHandles' };
    return $self->_execute_command($res);
}


sub get_window_size {
    my ( $self, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    my $res = { 'command' => 'getWindowSize', 'window_handle' => $window };
    $res = { 'command' => 'getWindowRect', handle => $window }
      if $self->{is_wd3};
    return $self->_execute_command($res);
}


sub get_window_position {
    my ( $self, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    my $res = { 'command' => 'getWindowPosition', 'window_handle' => $window };
    $res = { 'command' => 'getWindowRect', handle => $window }
      if $self->{is_wd3};
    return $self->_execute_command($res);
}


sub get_current_url {
    my $self = shift;
    my $res = { 'command' => 'getCurrentUrl' };
    return $self->_execute_command($res);
}


sub navigate {
    my ( $self, $url ) = @_;
    $self->get($url);
}


sub get {
    my ( $self, $url ) = @_;

    if ( $self->has_base_url && $url !~ m|://| ) {
        $url =~ s|^/||;
        $url = $self->base_url . "/" . $url;
    }

    my $res    = { 'command' => 'get' };
    my $params = { 'url'     => $url };
    return $self->_execute_command( $res, $params );
}


sub get_title {
    my $self = shift;
    my $res = { 'command' => 'getTitle' };
    return $self->_execute_command($res);
}


sub go_back {
    my $self = shift;
    my $res = { 'command' => 'goBack' };
    return $self->_execute_command($res);
}


sub go_forward {
    my $self = shift;
    my $res = { 'command' => 'goForward' };
    return $self->_execute_command($res);
}


sub refresh {
    my $self = shift;
    my $res = { 'command' => 'refresh' };
    return $self->_execute_command($res);
}


sub has_javascript {
    my $self = shift;
    return int( $self->javascript );
}


sub execute_async_script {
    my ( $self, $script, @args ) = @_;
    if ( $self->has_javascript ) {
        if ( not defined $script ) {
            croak 'No script provided';
        }
        my $res =
          { 'command' => 'executeAsyncScript' . $self->_execute_script_suffix };

        # Check the args array if the elem obj is provided & replace it with
        # JSON representation
        for ( my $i = 0 ; $i < @args ; $i++ ) {
            if ( Scalar::Util::blessed( $args[$i] )
                and $args[$i]->isa('Selenium::Remote::WebElement') )
            {
                if ( $self->{is_wd3} ) {
                    $args[$i] =
                      { 'element-6066-11e4-a52e-4f735466cecf' =>
                          ( $args[$i] )->{id} };
                }
                else {
                    $args[$i] = { 'ELEMENT' => ( $args[$i] )->{id} };
                }
            }
        }

        my $params = { 'script' => $script, 'args' => \@args };
        my $ret = $self->_execute_command( $res, $params );

        # replace any ELEMENTS with WebElement
        if (    ref($ret)
            and ( ref($ret) eq 'HASH' )
            and $self->_looks_like_element($ret) )
        {
            $ret = $self->webelement_class->new(
                id     => $ret,
                driver => $self
            );
        }
        return $ret;
    }
    else {
        croak 'Javascript is not enabled on remote driver instance.';
    }
}


sub execute_script {
    my ( $self, $script, @args ) = @_;
    if ( $self->has_javascript ) {
        if ( not defined $script ) {
            croak 'No script provided';
        }
        my $res =
          { 'command' => 'executeScript' . $self->_execute_script_suffix };

        # Check the args array if the elem obj is provided & replace it with
        # JSON representation
        for ( my $i = 0 ; $i < @args ; $i++ ) {
            if ( Scalar::Util::blessed( $args[$i] )
                and $args[$i]->isa('Selenium::Remote::WebElement') )
            {
                if ( $self->{is_wd3} ) {
                    $args[$i] =
                      { 'element-6066-11e4-a52e-4f735466cecf' =>
                          ( $args[$i] )->{id} };
                }
                else {
                    $args[$i] = { 'ELEMENT' => ( $args[$i] )->{id} };
                }
            }
        }

        my $params = { 'script' => $script, 'args' => [@args] };
        my $ret = $self->_execute_command( $res, $params );

        return $self->_convert_to_webelement($ret);
    }
    else {
        croak 'Javascript is not enabled on remote driver instance.';
    }
}

# _looks_like_element
# An internal method to check if a return value might be an element

sub _looks_like_element {
    my ( $self, $maybe_element ) = @_;

    return (
             exists $maybe_element->{ELEMENT}
          or exists $maybe_element->{'element-6066-11e4-a52e-4f735466cecf'}
    );
}

# _convert_to_webelement
# An internal method used to traverse a data structure
# and convert any ELEMENTS with WebElements

sub _convert_to_webelement {
    my ( $self, $ret ) = @_;

    if ( ref($ret) and ( ref($ret) eq 'HASH' ) ) {
        if ( $self->_looks_like_element($ret) ) {

            # replace an ELEMENT with WebElement
            return $self->webelement_class->new(
                id     => $ret,
                driver => $self
            );
        }

        my %hash;
        foreach my $key ( keys %$ret ) {
            $hash{$key} = $self->_convert_to_webelement( $ret->{$key} );
        }
        return \%hash;
    }

    if ( ref($ret) and ( ref($ret) eq 'ARRAY' ) ) {
        my @array = map { $self->_convert_to_webelement($_) } @$ret;
        return \@array;
    }

    return $ret;
}


sub screenshot {
    my ($self, $params) = @_;
    $params //= { full => 0 };

    croak "Full page screenshot only supported on geckodriver" if $params->{full} && ( $self->{browser_name} ne 'firefox' );

    my $res = { 'command' => $params->{'full'} == 1 ? 'mozScreenshotFull' : 'screenshot' };
    return $self->_execute_command($res);
}


sub capture_screenshot {
    my ( $self, $filename, $params ) = @_;
    croak '$filename is required' unless $filename;

    open( my $fh, '>', $filename );
    binmode $fh;
    print $fh MIME::Base64::decode_base64( $self->screenshot($params) );
    CORE::close $fh;
    return 1;
}


#TODO emulate behavior on wd3?
#grep { eval { Selenium::Remote::Driver->new( browser => $_ ) } } (qw{firefox MicrosoftEdge chrome opera safari htmlunit iphone phantomjs},'internet_explorer');
#might do the trick
sub available_engines {
    my ($self) = @_;
    my $res = { 'command' => 'availableEngines' };
    return $self->_execute_command($res);
}


sub switch_to_frame {
    my ( $self, $id ) = @_;

    my $json_null = JSON::null;
    my $params;
    $id = ( defined $id ) ? $id : $json_null;

    my $res = { 'command' => 'switchToFrame' };

    if ( ref $id eq $self->webelement_class ) {
        if ( $self->{is_wd3} ) {
            $params =
              { 'id' =>
                  { 'element-6066-11e4-a52e-4f735466cecf' => $id->{'id'} } };
        }
        else {
            $params = { 'id' => { 'ELEMENT' => $id->{'id'} } };
        }
    }
    else {
        $params = { 'id' => $id };
    }
    return $self->_execute_command( $res, $params );
}


sub switch_to_parent_frame {
    my ($self) = @_;
    my $res = { 'command' => 'switchToParentFrame' };
    return $self->_execute_command($res);
}


sub switch_to_window {
    my ( $self, $name ) = @_;
    if ( not defined $name ) {
        return 'Window name not provided';
    }
    my $res = { 'command' => 'switchToWindow' };
    my $params = { 'name' => $name, 'handle' => $name };
    return $self->_execute_command( $res, $params );
}


sub set_window_position {
    my ( $self, $x, $y, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    if ( not defined $x and not defined $y ) {
        croak "X & Y co-ordinates are required";
    }
    croak qq{Error: In set_window_size, argument x "$x" isn't numeric}
      unless Scalar::Util::looks_like_number($x);
    croak qq{Error: In set_window_size, argument y "$y" isn't numeric}
      unless Scalar::Util::looks_like_number($y);
    $x +=
      0;  # convert to numeric if a string, otherwise they'll be sent as strings
    $y += 0;
    my $res = { 'command' => 'setWindowPosition', 'window_handle' => $window };
    my $params = { 'x' => $x, 'y' => $y };
    if ( $self->{is_wd3} ) {
        $res = { 'command' => 'setWindowRect', handle => $window };
    }
    my $ret = $self->_execute_command( $res, $params );
    return $ret ? 1 : 0;
}


sub set_window_size {
    my ( $self, $height, $width, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    if ( not defined $height and not defined $width ) {
        croak "height & width of browser are required";
    }
    croak qq{Error: In set_window_size, argument height "$height" isn't numeric}
      unless Scalar::Util::looks_like_number($height);
    croak qq{Error: In set_window_size, argument width "$width" isn't numeric}
      unless Scalar::Util::looks_like_number($width);
    $height +=
      0;  # convert to numeric if a string, otherwise they'll be sent as strings
    $width += 0;
    my $res = { 'command' => 'setWindowSize', 'window_handle' => $window };
    my $params = { 'height' => $height, 'width' => $width };
    if ( $self->{is_wd3} ) {
        $res = { 'command' => 'setWindowRect', handle => $window };
    }
    my $ret = $self->_execute_command( $res, $params );
    return $ret ? 1 : 0;
}


sub maximize_window {
    my ( $self, $window ) = @_;

    $window = ( defined $window ) ? $window : 'current';
    my $res = { 'command' => 'maximizeWindow', 'window_handle' => $window };
    my $ret = $self->_execute_command($res);
    return $ret ? 1 : 0;
}


sub minimize_window {
    my ( $self, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    my $res = { 'command' => 'minimizeWindow', 'window_handle' => $window };
    my $ret = $self->_execute_command($res);
    return $ret ? 1 : 0;
}


sub fullscreen_window {
    my ( $self, $window ) = @_;
    $window = ( defined $window ) ? $window : 'current';
    my $res = { 'command' => 'fullscreenWindow', 'window_handle' => $window };
    my $ret = $self->_execute_command($res);
    return $ret ? 1 : 0;
}


sub get_all_cookies {
    my ($self) = @_;
    my $res = { 'command' => 'getAllCookies' };
    return $self->_execute_command($res);
}


sub add_cookie {
    my ( $self, $name, $value, $path, $domain, $secure, $httponly, $expiry ) =
      @_;

    if (   ( not defined $name )
        || ( not defined $value ) )
    {
        croak "Missing parameters";
    }

    my $res        = { 'command' => 'addCookie' };
    my $json_false = JSON::false;
    my $json_true  = JSON::true;
    $secure = ( defined $secure && $secure ) ? $json_true : $json_false;

    my $params = {
        'cookie' => {
            'name'   => $name,
            'value'  => $value,
            'path'   => $path,
            'secure' => $secure,
        }
    };
    $params->{cookie}->{domain}     = $domain   if $domain;
    $params->{cookie}->{'httponly'} = $httponly if $httponly;
    $params->{cookie}->{'expiry'}   = $expiry   if $expiry;

    return $self->_execute_command( $res, $params );
}


sub delete_all_cookies {
    my ($self) = @_;
    my $res = { 'command' => 'deleteAllCookies' };
    return $self->_execute_command($res);
}


sub get_cookie_named {
    my ( $self, $cookie_name ) = @_;
    my $res = { 'command' => 'getCookieNamed', 'name' => $cookie_name };
    return $self->_execute_command($res);
}


sub delete_cookie_named {
    my ( $self, $cookie_name ) = @_;
    if ( not defined $cookie_name ) {
        croak "Cookie name not provided";
    }
    my $res = { 'command' => 'deleteCookieNamed', 'name' => $cookie_name };
    return $self->_execute_command($res);
}


sub get_page_source {
    my ($self) = @_;
    my $res = { 'command' => 'getPageSource' };
    return $self->_execute_command($res);
}


sub find_element {
    my ( $self, $query, $method ) = @_;
    if ( not defined $query ) {
        croak 'Search string to find element not provided.';
    }

    my $res = { 'command' => 'findElement' };
    my $params = $self->_build_find_params( $method, $query );
    my $ret_data = eval { $self->_execute_command( $res, $params ); };
    if ($@) {
        if ( $@ =~
/(An element could not be located on the page using the given search parameters)/
          )
        {
            # give details on what element wasn't found
            $@ = "$1: $query,$params->{using}";
            local @CARP_NOT = ( "Selenium::Remote::Driver", @CARP_NOT );
            croak $@;
        }
        else {
            # re throw if the exception wasn't what we expected
            die $@;
        }
    }
    return $self->webelement_class->new(
        id     => $ret_data,
        driver => $self
    );
}


sub find_elements {
    my ( $self, $query, $method ) = @_;
    if ( not defined $query ) {
        croak 'Search string to find element not provided.';
    }

    my $res = { 'command' => 'findElements' };
    my $params = $self->_build_find_params( $method, $query );
    my $ret_data = eval { $self->_execute_command( $res, $params ); };
    if ($@) {
        if ( $@ =~
/(An element could not be located on the page using the given search parameters)/
          )
        {
            # give details on what element wasn't found
            $@ = "$1: $query,$params->{using}";
            local @CARP_NOT = ( "Selenium::Remote::Driver", @CARP_NOT );
            croak $@;
        }
        else {
            # re throw if the exception wasn't what we expected
            die $@;
        }
    }
    my $elem_obj_arr = [];
    foreach (@$ret_data) {
        push(
            @$elem_obj_arr,
            $self->webelement_class->new(
                id     => $_,
                driver => $self
            )
        );
    }
    return wantarray ? @{$elem_obj_arr} : $elem_obj_arr;
}


sub find_child_element {
    my ( $self, $elem, $query, $method ) = @_;
    if ( ( not defined $elem ) || ( not defined $query ) ) {
        croak "Missing parameters";
    }
    my $res = { 'command' => 'findChildElement', 'id' => $elem->{id} };
    my $params = $self->_build_find_params( $method, $query );
    my $ret_data = eval { $self->_execute_command( $res, $params ); };
    if ($@) {
        if ( $@ =~
/(An element could not be located on the page using the given search parameters)/
          )
        {
            # give details on what element wasn't found
            $@ = "$1: $query,$params->{using}";
            local @CARP_NOT = ( "Selenium::Remote::Driver", @CARP_NOT );
            croak $@;
        }
        else {
            # re throw if the exception wasn't what we expected
            die $@;
        }
    }
    return $self->webelement_class->new(
        id     => $ret_data,
        driver => $self
    );
}


sub find_child_elements {
    my ( $self, $elem, $query, $method ) = @_;
    if ( ( not defined $elem ) || ( not defined $query ) ) {
        croak "Missing parameters";
    }

    my $res = { 'command' => 'findChildElements', 'id' => $elem->{id} };
    my $params = $self->_build_find_params( $method, $query );
    my $ret_data = eval { $self->_execute_command( $res, $params ); };
    if ($@) {
        if ( $@ =~
/(An element could not be located on the page using the given search parameters)/
          )
        {
            # give details on what element wasn't found
            $@ = "$1: $query,$params->{using}";
            local @CARP_NOT = ( "Selenium::Remote::Driver", @CARP_NOT );
            croak $@;
        }
        else {
            # re throw if the exception wasn't what we expected
            die $@;
        }
    }
    my $elem_obj_arr = [];
    my $i            = 0;
    foreach (@$ret_data) {
        $elem_obj_arr->[$i] = $self->webelement_class->new(
            id     => $_,
            driver => $self
        );
        $i++;
    }
    return wantarray ? @{$elem_obj_arr} : $elem_obj_arr;
}


sub _build_find_params {
    my ( $self, $method, $query ) = @_;

    my $using = $self->_build_using($method);

    # geckodriver doesn't accept name as a valid selector
    if ( $self->isa('Selenium::Firefox') && $using eq 'name' ) {
        return {
            using => 'css selector',
            value => qq{[name="$query"]}
        };
    }
    else {
        return {
            using => $using,
            value => $query
        };
    }
}

sub _build_using {
    my ( $self, $method ) = @_;

    if ($method) {
        if ( $self->FINDERS->{$method} ) {
            return $self->FINDERS->{$method};
        }
        else {
            croak 'Bad method, expected: '
              . join( ', ', keys %{ $self->FINDERS } )
              . ", got $method";
        }
    }
    else {
        return $self->default_finder;
    }
}

sub get_active_element {
    my ($self) = @_;
    my $res = { 'command' => 'getActiveElement' };
    my $ret_data = eval { $self->_execute_command($res) };
    if ($@) {
        croak $@;
    }
    else {
        return $self->webelement_class->new(
            id     => $ret_data,
            driver => $self
        );
    }
}


sub cache_status {
    my ($self) = @_;
    my $res = { 'command' => 'cacheStatus' };
    return $self->_execute_command($res);
}


sub set_geolocation {
    my ( $self, %params ) = @_;
    my $res = { 'command' => 'setGeolocation' };
    return $self->_execute_command( $res, \%params );
}


sub get_geolocation {
    my ($self) = @_;
    my $res = { 'command' => 'getGeolocation' };
    return $self->_execute_command($res);
}


sub get_log {
    my ( $self, $type ) = @_;
    my $res = { 'command' => 'getLog' };
    return $self->_execute_command( $res, { type => $type } );
}


sub get_log_types {
    my ($self) = @_;
    my $res = { 'command' => 'getLogTypes' };
    return $self->_execute_command($res);
}


sub set_orientation {
    my ( $self, $orientation ) = @_;
    my $res = { 'command' => 'setOrientation' };
    return $self->_execute_command( $res, { orientation => $orientation } );
}


sub get_orientation {
    my ($self) = @_;
    my $res = { 'command' => 'getOrientation' };
    return $self->_execute_command($res);
}


sub send_modifier {
    my ( $self, $modifier, $isdown ) = @_;
    if ( $isdown =~ /(down|up)/ ) {
        $isdown = $isdown =~ /down/ ? 1 : 0;
    }

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        my $acts = [
            {
                type => $isdown ? 'keyDown' : 'keyUp',
                value => KEYS->{ lc($modifier) },
            },
        ];

        my $action = {
            actions => [
                {
                    id      => 'key',
                    type    => 'key',
                    actions => $acts,
                }
            ]
        };
        _queue_action(%$action);
        return 1;
    }

    my $res = { 'command' => 'sendModifier' };
    my $params = {
        value  => $modifier,
        isdown => $isdown
    };
    return $self->_execute_command( $res, $params );
}


sub compare_elements {
    my ( $self, $elem1, $elem2 ) = @_;
    my $res = {
        'command' => 'elementEquals',
        'id'      => $elem1->{id},
        'other'   => $elem2->{id}
    };
    return $self->_execute_command($res);
}


sub click {
    my ( $self, $button, $append ) = @_;
    $button = _get_button($button);

    my $res    = { 'command' => 'click' };
    my $params = { 'button'  => $button };

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        $params = {
            actions => [
                {
                    type       => "pointer",
                    id         => 'mouse',
                    parameters => { "pointerType" => "mouse" },
                    actions    => [
                        {
                            type     => "pointerDown",
                            duration => 0,
                            button   => $button,
                        },
                        {
                            type     => "pointerUp",
                            duration => 0,
                            button   => $button,
                        },
                    ],
                }
            ],
        };
        if ($append) {
            _queue_action(%$params);
            return 1;
        }
        return $self->general_action(%$params);
    }

    return $self->_execute_command( $res, $params );
}

sub _get_button {
    my $button = shift;
    my $button_enum = { LEFT => 0, MIDDLE => 1, RIGHT => 2 };
    if ( defined $button && $button =~ /(LEFT|MIDDLE|RIGHT)/i ) {
        return $button_enum->{ uc $1 };
    }
    if ( defined $button && $button =~ /(0|1|2)/ ) {
        #Handle user error sending in "1"
        return int($1);
    }
    return 0;
}


sub double_click {
    my ( $self, $button ) = @_;

    $button = _get_button($button);

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        $self->click( $button, 1 );
        $self->click( $button, 1 );
        return $self->general_action();
    }

    my $res = { 'command' => 'doubleClick' };
    return $self->_execute_command($res);
}


sub button_down {
    my ($self) = @_;

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        my $params = {
            actions => [
                {
                    type       => "pointer",
                    id         => 'mouse',
                    parameters => { "pointerType" => "mouse" },
                    actions    => [
                        {
                            type     => "pointerDown",
                            duration => 0,
                            button   => 0,
                        },
                    ],
                }
            ],
        };
        _queue_action(%$params);
        return 1;
    }

    my $res = { 'command' => 'buttonDown' };
    return $self->_execute_command($res);
}


sub button_up {
    my ($self) = @_;

    if ( $self->{is_wd3}
        && !( grep { $self->browser_name eq $_ } qw{MicrosoftEdge} ) )
    {
        my $params = {
            actions => [
                {
                    type       => "pointer",
                    id         => 'mouse',
                    parameters => { "pointerType" => "mouse" },
                    actions    => [
                        {
                            type     => "pointerDown",
                            duration => 0,
                            button   => 0,
                        },
                    ],
                }
            ],
        };
        _queue_action(%$params);
        return 1;
    }

    my $res = { 'command' => 'buttonUp' };
    return $self->_execute_command($res);
}


# this method duplicates upload() method in the
# org.openqa.selenium.remote.RemoteWebElement java class.

sub upload_file {
    my ( $self, $filename, $raw_content ) = @_;

    my $params;
    if ( defined $raw_content ) {

        #If no processing is passed, send the argument raw
        $params = { file => $raw_content };
    }
    else {
        #Otherwise, zip/base64 it.
        $params = $self->_prepare_file($filename);
    }

    my $res = { 'command' => 'uploadFile' };    # /session/:SessionId/file
    my $ret = $self->_execute_command( $res, $params );

    return $ret;
}

sub _prepare_file {
    my ( $self, $filename ) = @_;

    if ( not -r $filename ) { croak "upload_file: no such file: $filename"; }
    my $string = "";                            # buffer
    my $zip    = Archive::Zip->new();
    $zip->addFile( $filename, basename($filename) );
    if ( $zip->writeToFileHandle( IO::String->new($string) ) != AZ_OK ) {
        die 'zip failed';
    }

    return { file => MIME::Base64::encode_base64( $string, '' ) };
}


sub get_text {
    my $self = shift;
    return $self->find_element(@_)->get_text();
}


sub get_body {
    my $self = shift;
    return $self->get_text( '//body', 'xpath' );
}


sub get_path {
    my $self     = shift;
    my $location = $self->get_current_url;
    $location =~ s/\?.*//;               # strip of query params
    $location =~ s/#.*//;                # strip of anchors
    $location =~ s#^https?://[^/]+##;    # strip off host
    return $location;
}


sub get_user_agent {
    my $self = shift;
    return $self->execute_script('return window.navigator.userAgent;');
}


sub set_inner_window_size {
    my $self     = shift;
    my $height   = shift;
    my $width    = shift;
    my $location = $self->get_current_url;

    $self->execute_script( 'window.open("' . $location . '", "_blank")' );
    $self->close;
    my @handles = @{ $self->get_window_handles };
    $self->switch_to_window( pop @handles );

    my @resize = (
        'window.innerHeight = ' . $height,
        'window.innerWidth  = ' . $width,
        'return 1'
    );

    return $self->execute_script( join( ';', @resize ) ) ? 1 : 0;
}


sub get_local_storage_item {
    my ( $self, $key ) = @_;
    my $res    = { 'command' => 'getLocalStorageItem' };
    my $params = { 'key'     => $key };
    return $self->_execute_command( $res, $params );
}


sub delete_local_storage_item {
    my ( $self, $key ) = @_;
    my $res    = { 'command' => 'deleteLocalStorageItem' };
    my $params = { 'key'     => $key };
    return $self->_execute_command( $res, $params );
}

sub _coerce_timeout_ms {
    my ($ms) = @_;

    if ( defined $ms ) {
        return _coerce_number($ms);
    }
    else {
        croak 'Expecting a timeout in ms';
    }
}

sub _coerce_number {
    my ($maybe_number) = @_;

    if ( Scalar::Util::looks_like_number($maybe_number) ) {
        return $maybe_number + 0;
    }
    else {
        croak "Expecting a number, not: $maybe_number";
    }
}

1;

__END__