diff --git a/Modulefile b/Modulefile index 812ce2e..b75a668 100644 --- a/Modulefile +++ b/Modulefile @@ -5,7 +5,7 @@ author 'Joshua Hoblitt ' license 'Apache' project_page 'https://github.com/jhoblitt/puppet-selenium' source 'https://github.com/jhoblitt/puppet-selenium.git' -summary 'module skeleton' -description 'module skeleton' +summary 'Manages Selenium Server 2 - Standalone and Grid' +description 'Manages Selenium Server 2 - Standalone and Grid' dependency 'puppetlabs/stdlib', '>= 3.0.0' -dependency 'maestrodev/wget', '>= 0.0.1' +dependency 'maestrodev/wget', '>= 1.2.2' diff --git a/README.md b/README.md index 7e4553f..ab9a9c9 100644 --- a/README.md +++ b/README.md @@ -8,42 +8,272 @@ Puppet selenium Module 1. [Overview](#overview) 2. [Description](#description) 3. [Usage](#usage) -4. [Limitations](#limitations) + * [Simple](#simple) + * [Files](#files) + * [`selenium`](#selenium) + * [`selenium::server`](#selenium--server) + * [`selenium::hub`](#selenium--hub) + * [`selenium::node`](#selenium--node) +4. [Why Another Module?](#why-another-module) +5. [Limitations](#limitations) * [Tested Platforms](#tested-platforms) -5. [Support](#support) +6. [Support](#support) Overview -------- +Manages Selenium Server 2 - Standalone and Grid Description ----------- -https://github.com/adamgoucher/selenium-puppet +This is a puppet module for installation and configuration of the [Selenium +Server](http://docs.seleniumhq.org/docs/07_selenium_grid.jsp) 2 browser +automation package. Support is provided for configuring Selenium Server in +`standalone` mode along with the grid modes of `hub` and `node`. -Windows, no rspec-puppet tests +The design intent of this module is to only manage Selenium server and not any +of the other packages that might be required to required to create a selenium +server [role](http://www.craigdunn.org/2012/05/239/). -https://github.com/StoryIQ/puppet-selenium-grid +Usage +----- -Debian, no rspec-puppet tests +### Simple -https://github.com/kayakco/puppet-selenium +Stand alone server setup with display `:99` (default is `:0`). -Unreleased deps, role like, debian-ish (Centos), doesn't appear ready +```puppet +class { 'selenium::server: display => ':99' } +``` +Grid in a box setup with the Selenium `node` talking to the `hub` via +`127.0.0.1`. +```puppet +class { 'selenium::hub: } +class { 'selenium::node: } +``` +### Files -Usage ------ +Unless class `selenium` has `$install_root` changed from the default, these files paths will be used. Note that the log files and init scripts are only created for the relevant configured service. + +The log files will have the mode `0644` so that they can be inspected by users +other than the selenium role account. + +``` +/opt/selenium +|-- jars +| `-- selenium-server-standalone-2.35.0.jar +`-- log + |-- hub_stderr.log + |-- hub_stdout.log + |-- node_stderr.log + |-- node_stdout.log + |-- server_stderr.log + `-- server_stdout.log +/etc/init.d/seleniumhub +/etc/init.d/seleniumnode +/etc/init.d/seleniumserver +``` + +### `selenium` + +This class controls common configuration values used by the +`selenium::{server,hub,node}` classes. It is automatically included in the +manifest by those classes and it need not be explicitly declared except to +override the default values. + +```puppet +# defaults +class { 'selenium': + user => 'selenium', + group => 'selenium', + install_root => '/opt/selenium', + java => 'java', + version => '2.35.0', + url => undef, +} +``` + +#### `user` + +`String` + +The name/uid of the system role account to execute the server process under and +will have ownership of files. + +defaults to: `selenium` + +#### `group` + +`String` + +The group/gid of the system role account and group ownership of files. + +defaults to: `selenium` + +#### `install_root` + +`String` + +The dirname under which Selenium Server files (including logs) will be created. + +defaults to: `/opt/selenium` + +#### `java` + +`String` + +The path of the `java` interpreter to use. + +defaults to: `java` + +#### `version` + +`String` + +The version of Selenium Server to download. Used to form the URL used to fetch the jar file. + +defaults to: `2.35.0` (the latest release as of 2013-10-08) + +#### `url` + +`String` + +If defined, `url` will be used to download the Selenium Server jar file. However, the `version` parameter just match the version of the downloaded file as this information is needed when starting up the server (this may change to be be automatically parsed from the `url` in a later release). + +defaults to: `undef` + +### `selenium::server` + +```puppet +# defaults +class { 'selenium::server': + display => ':0', + options => '-Dwebdriver.enable.native.events=1', +} +``` + +#### `display` + +`String` + +The name of the `X` display to render too. This is set as an environment +variable passed to Selenium Server + +defaults to: `:0` + +#### `options` + +`String` + +Options passed to Selenium Server at startup. + +defaults to: `-Dwebdriver.enable.native.events=1` + +### `selenium::hub` + +Note that by default `selenium::server` and `selenium::hub` will try to listen +on the same TCP port (`4444`) and only one of them will be able to function. + +```puppet +# defaults +class { 'selenium::hub': + display => ':0', + options => '-Dwebdriver.enable.native.events=1', +} +``` + +#### `options` + +`String` + +Options passed to Selenium Server Hub at startup. + +defaults to: `-role hub` + +### `selenium::node` + +```puppet +# defaults +class { 'selenium::node': + display => ':0', + options => '-Dwebdriver.enable.native.events=1 -role node', + hub => 'http://localhost:4444/grid/register', +} +``` + +#### `display` + +`String` + +The name of the `X` display to render too. This is set as an environment +variable passed to Selenium Server + +defaults to: `:0` + +#### `options` + +`String` + +Options passed to Selenium Server Node at startup. + +defaults to: `-Dwebdriver.enable.native.events=1 -role node` + +#### `hub` + +`String` + +The URL of the Selenium Server Hub to connect to. + +defaults to: `http://localhost:4444/grid/register` + + +Why Another Module? +------------------- + +At the time work on this module was started, there were no other Selenium +Server modules published on the Puppet Forge. A number of existing modules +were identified on github but none of them fit the authors needs of: + +* Allowing the external setup of things like `Xvfb`, `java`, etc. +* Supporting a mixed environment of Scientific, Centos, and RedHat Linux + (basically `$::osfamily == 'RedHat'` +* Enough `rspec-puppet` coverage to prevent regressions + +The later is the most important issue. Attempting to add additional +`$::operatingsystem/$::osfamily` support to a puppet module without +`rspec-puppet` tests is a process fraught with peril. + +The modules that were identified were: + +* [adamgoucher/selenium-puppet](https://github.com/adamgoucher/selenium-puppet) + - Mostly aimed at Windows but with some Linux/POSIX support + - no `rspec-puppet` tests (deal breaker) +* [StoryIQ/puppet-selenium-grid](https://github.com/StoryIQ/puppet-selenium-grid) + - Debian only + - no `rspec-puppet` tests (deal breaker) +* [kayakco/puppet-selenium](https://github.com/kayakco/puppet-selenium) + - Unreleased deps (deal breaker) + - Very role like with lots of magic setup (deal breaker) + - debian-ish (may support Centos) + - Doesn't appear to be in a ready state Limitations ----------- +At present, only support for `$::osfamily == 'RedHat'` has been implemented. +Adding other Linux distributions will required the addition of platform +specific init scripts. + ### Tested Platforms +* el6.x + Support ------- @@ -51,3 +281,7 @@ Support Please log tickets and issues at [github](https://github.com/jhoblitt/puppet-selenium/issues) +See Also +-------- + +* [Selenium](http://docs.seleniumhq.org/) diff --git a/manifests/hub.pp b/manifests/hub.pp index b94fdfc..6b09f59 100644 --- a/manifests/hub.pp +++ b/manifests/hub.pp @@ -1,11 +1,26 @@ # == Class: selenium::hub # -# simple template +# === Parameters # +# Note that by default `selenium::server` and `selenium::hub` will try to +# listen on the same TCP port (`4444`) and only one of them will be able to +# function. # -# === Examples +# ```puppet +# # defaults +# class { 'selenium::hub': +# display => ':0', +# options => '-Dwebdriver.enable.native.events=1', +# } +# ``` # -# include selenium::hub +# #### `options` +# +# `String` +# +# Options passed to Selenium Server Hub at startup. +# +# defaults to: `-role hub` # # # === Authors diff --git a/manifests/init.pp b/manifests/init.pp index 4193697..6815a92 100644 --- a/manifests/init.pp +++ b/manifests/init.pp @@ -1,14 +1,77 @@ # == Class: selenium # -# # === Parameters # -# Accepts no parameters. +# This class controls common configuration values used by the +# `selenium::{server,hub,node}` classes. It is automatically included in the +# manifest by those classes and it need not be explicitly declared except to +# override the default values. +# +# ```puppet +# # defaults +# class { 'selenium': +# user => 'selenium', +# group => 'selenium', +# install_root => '/opt/selenium', +# java => 'java', +# version => '2.35.0', +# url => undef, +# } +# ``` +# +# #### `user` +# +# `String` +# +# The name/uid of the system role account to execute the server process under +# and will have ownership of files. +# +# defaults to: `selenium` +# +# #### `group` +# +# `String` +# +# The group/gid of the system role account and group ownership of files. +# +# defaults to: `selenium` +# +# #### `install_root` +# +# `String` +# +# The dirname under which Selenium Server files (including logs) will be +# created. +# +# defaults to: `/opt/selenium` +# +# #### `java` +# +# `String` +# +# The path of the `java` interpreter to use. +# +# defaults to: `java` +# +# #### `version` +# +# `String` +# +# The version of Selenium Server to download. Used to form the URL used to +# fetch the jar file. +# +# defaults to: `2.35.0` (the latest release as of 2013-10-08) +# +# #### `url` # +# `String` # -# === Examples +# If defined, `url` will be used to download the Selenium Server jar file. +# However, the `version` parameter just match the version of the downloaded +# file as this information is needed when starting up the server (this may +# change to be be automatically parsed from the `url` in a later release). # -# class{ 'selenium': } +# defaults to: `undef` # # # === Authors diff --git a/manifests/node.pp b/manifests/node.pp index 06ae450..4ab9d2f 100644 --- a/manifests/node.pp +++ b/manifests/node.pp @@ -1,11 +1,40 @@ # == Class: selenium::node # -# simple template +# === Parameters # +# ```puppet +# # defaults +# class { 'selenium::node': +# display => ':0', +# options => '-Dwebdriver.enable.native.events=1 -role node', +# hub => 'http://localhost:4444/grid/register', +# } +# ``` # -# === Examples +# #### `display` # -# include selenium::node +# `String` +# +# The name of the `X` display to render too. This is set as an environment +# variable passed to Selenium Server +# +# defaults to: `:0` +# +# #### `options` +# +# `String` +# +# Options passed to Selenium Server Node at startup. +# +# defaults to: `-Dwebdriver.enable.native.events=1 -role node` +# +# #### `hub` +# +# `String` +# +# The URL of the Selenium Server Hub to connect to. +# +# defaults to: `http://localhost:4444/grid/register` # # # === Authors diff --git a/manifests/server.pp b/manifests/server.pp index 942abc3..3e631e6 100644 --- a/manifests/server.pp +++ b/manifests/server.pp @@ -1,11 +1,31 @@ # == Class: selenium::server # -# simple template +# === Parameters # +# ```puppet +# # defaults +# class { 'selenium::server': +# display => ':0', +# options => '-Dwebdriver.enable.native.events=1', +# } +# ``` # -# === Examples +# #### `display` # -# include selenium::server +# `String` +# +# The name of the `X` display to render too. This is set as an environment +# variable passed to Selenium Server +# +# defaults to: `:0` +# +# #### `options` +# +# `String` +# +# Options passed to Selenium Server at startup. +# +# defaults to: `-Dwebdriver.enable.native.events=1` # # # === Authors