NAME

Promised::Docker::WebDriver - Headless browsers with WebDriver in Docker

SYNOPSIS

use Promised::Docker::WebDriver;
$server = Promised::Docker::WebDriver->chrome;
$server->start->then (sub {
  $url = $server->get_url_prefix;
  $host = $server->get_docker_host_hostname;
  ...
  POST qq<$url/session/url>, {url => qq<http://$host:8080/>};
  ...
})->then (sub {
  return $server->stop;
});

DESCRIPTION

The Promised::Docker::WebDriver module provides a Promise-aware wrapper API for docker images containing headless Web browsers exposing WebDriver Web APIs.

METHODS

Following methods are available:

$server = Promised::Docker::WebDriver->chrome

Create a new instance for the docker image "wakaba/docker-chromedriver:stable", which contains ChromeDriver with Chrome stable channel browser. (See <https://github.com/wakaba/docker-chromedriver>.)

$server = Promised::Docker::WebDriver->chromium

Create a new instance for the docker image "wakaba/docker-chromedriver:chromium", which contains ChromeDriver with Chromium browser. (See <https://github.com/wakaba/docker-chromedriver>.)

$server = Promised::Docker::WebDriver->firefox

Create a new instance for the docker image "wakaba/docker-firefoxdriver:stable", which contains FirefoxDriver with Firefox stable release browser. (See <https://github.com/wakaba/docker-firefoxdriver>.)

$promise = $server->start (NAME => VALUE, ...)

Start a Docker container and return a Promise, which is resolved after the WebDriver API server is ready to accept HTTP requests. The promise is rejected if the server failed to start.

Following options can be specified as zero or more name/value pairs:

host => $host

A Web::Host object (in the <https://github.com/manakai/perl-web-url> repository) that represents the IP address the WebDriver server should listen. If omitted, defaulted to an IPv4 address 127.0.0.1.

port => $port

An integer that represents the TCP port the WebDriver server should listen. If omitted, defaulted to an unused port.

$promise = $server->stop

Stop the Docker container and return a Promise, which is resolved after the Docker container is stopped.

This method must be invoked after the start method is resolved.

$promise = $server->completed

Return a Promise, which is resolved after the Docker container is stopped.

This method must be invoked after the start method is resolved.

$time = $server->start_timeout

$server->start_timeout ($time)

Get or set the timeout for the start, i.e. the maximum time interval between the completion of the docker run -d command and when the server becomes ready to accept requests.

This method must be invoked before the start method is invoked.

$boolean = $server->use_rtp

$server->use_rtp ($boolean)

Get or set whether the audio output should be exposed by RTP or not. This option is only applicable to a Docker image which supports this feature.

This method must be invoked before the start method is invoked.

$string? = $server->hls_path

$server->hls_path ($string?)

Get or set the WD_HLS_PATH environment variable within the docker container. This option is only applicable to a Docker image which supports this feature.

This method must be invoked before the start method is invoked.

$string? = $server->video_path

$server->video_path ($string?)

Get or set the WD_VIDEO_PATH environment variable within the docker container. This option is only applicable to a Docker image which supports this feature.

This method must be invoked before the start method is invoked.

$arrayref = $server->docker_args

$server->docker_args ($arrayref)

Get or set the additional arguments to the docker run command.

This method must be invoked before the start method is invoked.

$int = $server->get_port

Return the port number the WebDriver server is listening. This method must be invoked after the start promise is resolved.

$string = $server->get_hostname

Return the host name the WebDriver server is listening, as a string. This method must be invoked after the start promise is resolved.

$string = $server->get_host

Return a string that is equivalent to $server->get_hostname . ':' . $server->get_port. This method must be invoked after the start promise is resolved.

$url = $server->get_url_prefix

Return the URL prefix for the server. For example, the complete URL for the /session end point is the value returned by this method followed by /session. This method must be invoked after the start promise is resolved.

$string = $server->get_docker_host_hostname_for_container

Return the host name of the Docker host (the host where the Perl application is running) used within the Docker container. This host name can be used to construct the URL specified in the WebDriver API to let the browser access the server running on the host. This method must be invoked after the start promise is resolved.

$string = $server->get_rtp_hostname

Return the host name of the RTP stream. If not available, undef is returned instead.

$int = $server->get_rtp_port

Return the port number of the RTP stream. If not available, undef is returned instead.

During the server is running, signal handlers for SIGINT, SIGTERM, and SIGQUIT are installed such that these signal will terminate the server (and the current script). If the script wants to handle signal in other ways, the handling should be specified using the Promised::Command::Signals API from <https://github.com/wakaba/perl-promised-command> to avoid confliction.

DEPENDENCY

The module requires Perl 5.10 or later.

The module requires Promise <https://github.com/wakaba/perl-promise>, Promised::Command <https://github.com/wakaba/perl-promised-command>, and AnyEvent.

Obviously, Docker is also required.

SEE ALSO

Docker <https://www.docker.com/>.

The WebDriver Wire Protocol <https://web.archive.org/web/20160205035909/https://code.google.com/p/selenium/wiki/JsonWireProtocol>.

WebDriver <https://w3c.github.io/webdriver/webdriver-spec.html>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

HISTORY

This repository was located at <https://github.com/wakaba/perl-promised-docker-webdriver> until 19 April 2023, then transferred to <https://github.com/pawjy/perl-promised-docker-webdriver>.

LICENSE

Copyright 2015-2023 Wakaba <wakaba@suikawiki.org>.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.