buster-selenium
Buster.js Selenium and Python Test Integration
This package provides wrappers for the Buster.js server and test runner that integrate bits of selenium to control the capture of Buster slaves. It also provides wrappers for running Buster.js tests as a part of a Python test suite and further integration with zope.testrunner for doing test discovery and testing layers for controlling the buster-server and capturing Buster.JS browser slaves.
buster-server
and Capturing Browser Slaves
Managing The buster_selenium.case.BusterJSTestCase
class is a sub-class of
unittest.TestCase and can be used to create Python test cases that
will run a Buster.JS test suite corresponding to one buster.js
test
configuration:
>>> from buster_selenium import case >>> def suite(): >>> suite = unittest.TestSuite() ... suite.addTest( ... case.BusterJSTestCase('/path/to/buster.js')) ... return suite
The test case will start buster-server
, launch a browser, and
capture a browser slave in the test setUp
. Then it will invoke
buster-test
passing the buster.js
config file and will report
failure if buster-test
exits with a status code of 1
or will
report erro if it exits with any other non-zero status code. Finally,
it will shutdown the browser slave and the buster-server
.
Before running buster-test
, the BusterJSTestCase
will create a
directory corresponding to the buster*.js
test suite in the
current working directory and change to that directory before
executing. This can be useful when working with the
buster-coverage extension, for example, so that the output of the
extension is collected in a unique directory without clobbering the
output from other test suites.
The BusterJSTestCase
class uses a few environment variables to
control how the buster-test
executable is invoked and what is done
with its output:
- BUSTER_TEST_EXECUTABLE
- If defined, the value of this will be used as the path to the
buster-test
executable to be used to run the tests. Useful if you're installing/building Buster.JS as a part of your build/deployment environment. If this variable is not defined, the firstbuster-test
available onPATH
will be used. - BUSTER_TEST_OPTIONS
- If defined, the value of this variable will be passed to Python's
shlex.split and passed as arguments/options to the
buster-test
executable. This can be useful, for example, to use different buster-test --report options. - BUSTER_TEST_STDOUT
- If defined, the stdout output of the
buster-test
executable will be written to this file. The file will be written in the same directory created as described above. - BUSTER_SERVER_EXECUTABLE
- Like
BUSTER_TEST_EXECUTABLE
, if defined, the path given will be used as thebuster-server
executable. Otherwise the firstbuster-server
found onPATH
will be used. - BUSTER_SLAVE_BROWSER_EXECUTABLE
- If defined, the executable at the path given will be invoked as a
slave browser and captured by the
buster-server
previously started. If theselenium.webdriver
package is availble, setting this overrides the default behavior of capturing a browser slave via Selenium. - BUSTER_SLAVE_BROWSER_OPTIONS
- If defined, the value of this variable will be passed to Python's
shlex.split and passed as arguments/options to the
BUSTER_SLAVE_BROWSER_EXECUTABLE
executable. - BUSTER_SLAVE_SELENIUM_DRIVER
- If the
selenium.webdriver
package is availble and this variable is set, the value will be used to retrieve a Selenium driver from the selenium.webdriver Python module. By default,Firefox
is used. - BUSTER_SLAVE_SELENIUM_ARGS
- If defined, the value of this variable will be passed to Python's
shlex.split and passed as positional arguments to the
selenium.webdriver
used. - BUSTER_SLAVE_SELENIUM_GRID_BROWSERNAME, BUSTER_SLAVE_SELENIUM_GRID_VERSION, BUSTER_SLAVE_SELENIUM_GRID_PLATFORM, BUSTER_SLAVE_SELENIUM_GRID_JAVASCRIPTENABLED
- If using Selenium Grid by setting
BUSTER_SLAVE_SELENIUM_DRIVER=Remote
and this variable defined, these values will be used to modify the values for thebrowserName
,version
,platform
, andjavascriptEnabled
keys in theselenium.webdriver.DesiredCapabilities
dictionaries. This is useful to run your buster tests against different OS's, browsers, and versions.
Buster.JS Test Discovery
The buster-selenium
package provides a buster-testrunner
console script which adds discovery of Buster.JS tests to the
zope.testrunner support for automatically finding tests
throughout a project. In particular, it will create a test suite for
any buster configuration file of the pattern buster*.js
in a
directory under a valid buster-testrunner --test-path
:
$ buster-testrunner --test-path=/path/to/project/module --test-path=/path/to/project/other-module
See the zope.testrunner docs or buster-testrunner --help
for more
details on controlling test discovery and which tests are run.
If you want to redirect buster-test
output using
BUSTER_TEST_STDOUT
, be aware that running multiple Buster.JS test
suites in the same buster.js
configuration file will result in the
output for all suites in that file being written to the same output
file. With the buster-test --reporter xml
reporter, for example,
this will result in invalid XML. A workaround is to use a separate
buster*.js
configuration file for each suite so that output is
written to separate directories.
buster-server
and Browser Slave Capture Between Tests
Sharing The buster_selenium.layer
module uses zope.testrunner
support for
testing layers to start buster-server
, launch a browser, and
capture a browser slave and use those for all buster-test
runs when
the tests are run with buster-testrunner
. This can help speed up
the running of multiple Buster.JS test suites while still providing
clean mangement of the buster-server
and captured browser slaves.
These layers are used automatically when using the test discovery
described above.
Managing Browser Slaves with Selenium Webdriver
If the selenium Python package is available, by default the
BusterJSTestCase
and testing layer support described above will
use selenium.webdriver to open, capture, and clean up a browser
slave. The way that selenium.webdriver
launches browsers provides
an additional degree of isolation from user extensions, profiles,
themes, and other add-ons and provides greater isolation for Buster.JS
tests.