selenium_test¶

class selenium_test.BaseTest(methodName='runTest')¶

Bases: unittest.case.TestCase

Base class for all selenium based tests. This class contains several attributes that are configured by cmake to give the test cases information about the build environment. The class attributes representing paths should not be modified by derived classes in general unless noted in the docstrings.

The testing framework is intended to be organized as follows:

Each testing subdirectory contains one or more test classes derived from this class. Test classes each have a class attribute BaseTest.testCase that should be a tuple of strings.
Each test class contains one or more test functions that are run independently.
Each test function contains one or more unit tests that are referred to in the arguments list as testName.

The tests are discovered and executed using python’s unittest module on the commandline by executing:

python -m unittest discover

Paths to test specific resources such as base line images are computed as follows:

Test web page

DEPLOY_PATH/test/selenium/testDirectory/index.html

Test case image store path

DEPLOY_PATH/test/selenium/testDirectory/testCase[0]/testCase[1]/.../

Unit test screenshots

DEPLOY_PATH/test/selenium/testDirectory/testCase[0]/testCase[1]/.../testName.png

MIDAS image store
```
MIDAS_COMMUNITY/Testing/test/selenium/testDirectory/testCase[0]/testCase[1]/.../testName.png
```
Where each MIDAS item contains multiple revisions and bitstreams to account for changes in the code and differences between platforms.

Unit test screenshot comparisons for debugging

DEPLOY_PATH/test/selenium/testDirectory/testCase[0]/testCase[1]/.../testName_test.png
DEPLOY_PATH/test/selenium/testDirectory/testCase[0]/testCase[1]/.../testName_base_NN.png
DEPLOY_PATH/test/selenium/testDirectory/testCase[0]/testCase[1]/.../testName_diff_NN.png

build_path = '@CMAKE_CURRENT_BINARY_DIR@'¶: The absolute path to the build root.

click(element, offset=(0, 0))¶

Click on a element given (by a CSS selector) at offset relative to the center of the element.

Parameters:	element (string) – A CSS selector offset ([x, y]) – The offset from the element center

For example,

>>> test.click('button.test-button')

classmethod compareImages(baseImage, testImage, testName, iImage=0)¶

Compute the difference between two images and throw a ImageDifferenceException if the difference is above imageDifferenceThreshold. If the two images are different sizes, this function will always raise.

Raises ImageDifferenceException:
Parameters:	baseImage (Image) – The base line image. testImage (Image) – The image generated by a screenshot. testName (string) – The name of the test. iImage (int) – A number used to generate unique file names when doing multiple comparisons per test.
	If the images are different.

deploy_path = '@GEOJS_DEPLOY_DIR@'¶: The absolute path to the webserver root.

drag(element, delta, offset=(0, 0))¶

Drag the element given (by a CSS selector) starting at offset relative to the center of the element by an amount delta.

Parameters:	element (string) – A CSS selector. delta ([x, y]) – The number of pixels to drag in `x` and `y`. offset ([x, y]) – The offset from the element center to start the drag.

For example,

>>> test.drag('#map', (100, -10), (-50, 0))

performs a mousedown on #map 50 pixels to the left of its center, drags right 100 pixels and up 10 pixels, and then performs a mouseup.

driverName = 'null'¶: String representing the selenium driver to be used. Currently supports ‘firefox’ and ‘chrome’

classmethod exportTestImage(img, testName, kind='', deploy='')¶

Save an image to the local image store path. This is an internal method providing a unified method for saving image outputs from tests for debugging test failures.

Parameters:	img (Image) – The image object to save. testName (string) – The name of the test. kind (string) – (optional) Additional string to added to the file name distinguishing multiple images. deploy (string) – (optional) Root path for the local image store.
Returns:	The full path of the saved image.
Return type:	string

getElement(selector)¶

Find an element on the page by a CSS selector. For example,

>>> node = test.getElement('#my-div')

Parameters:	selector (string) – A CSS selector.
Return type:	WebElement

getElements(selector)¶

Find all elements on the page matching a css selector.

>>> divs = test.getElements('div')

Parameters:	selector (string) – A CSS selector.
Return type:	List of WebElement

hover(element, offset=(0, 0))¶

Move the mouse pointer over the given element and offset.

Parameters:	element (string) – A CSS selector. offset ([x, y]) – The offset from the element center

imageDifferenceThreshold = 2.0¶: The maximum allowable image difference between screenshots and baseline images. The difference is calculated as the RMS average difference between pixel values in the RGB channels. This should be a number between 0 and 255, with 0 meaning a perfect match.

classmethod loadImageFile(filename, relative=True)¶

Load an image from a local file. If relative is True, then load it relative the current testing directory, otherwise assume an absolute path.

Parameters:	filename (string) – The file path of the image. relative (bool) – Whether to treat the filename as a relative or absolute path.
Return type:	Image

classmethod loadImageURL(filename, relative=True)¶

Load an image from a URL. If relative is True, then load it relative the current testing path, otherwise assume an absolute URL.

Raises Exception:
Parameters:	filename (string) – The file path of the image. relative (bool) – Whether to treat the filename as a relative or absolute path.
Return type:	Image
	if the image could not be loaded

classmethod loadTestImages(testName, revision=None)¶

Load all images from the globally configured MIDAS image store. The images are used for matching a screenshot for the current test. Multiple images are possible to account for differences on multiple platforms. If no revision is provided, then the class attribute testRevision is used.

Parameters:	testName (string) – The name of the current test. revision (int) – The revision number to load.
Return type:	List of Images.

loadURL(url, relative=True)¶

Load a URL path on the test server.

Parameters:	url (string) – The path to the page go load. relative (bool) – Whether or not to prefix with the current test path.

For example,

>>> test.loadURL('index.html')

will load http://localhost:50100/index.html, and

>>> test.loadURL('/index.html', False)

will load http://localhost:50100/path/to/test/index.html using the currently configured test path.

midas = <midas_handler.MidasHandler object>¶: A midas_handler.MidasHandler object providing methods for downloading and uploading data to the geojs MIDAS community.

midasPath = ('Testing', 'test', 'selenium')¶: A tuple representing the relative path to test data relative to the geojs MIDAS community.

resizeWindow(width, height)¶

Resize the browser to the given width and height.

Parameters:	width (int) – The width of the view in pixels. height (in) – The height of the view in pixels.

runScript(script)¶

Run a javascript script in the browser. Scripts that execute asynchronously should set a global variable when finished so that a BaseTest.wait() call can be made to block for it to finish, as follows:

>>> script = 'window.setTimeout(function () { window.finished = true; })'
>>> test.runScript(script)
>>> test.wait('window.finished')

Parameters:	script (string) – The script content to run.

screenshot()¶

Capture a screenshot of the current viewport.

Return type:	Image

screenshotTest(testName, revision=None)¶

Convenience method for taking a screenshot and comparing to stored images. Throws an exception if the images differ by more than imageDifferenceThreshold. This method also exports the images and differences under the deploy path for debugging failed tests. If no revision is provided, then the class attribute testRevision is used.

Raises ImageDifferenceException:
Parameters:	testName (string) – The name of the test. revision (int) – The revision number to compare against.
	If the images are different.

setUp()¶: Start up a selenium driver.

source_path = '@CMAKE_CURRENT_SOURCE_DIR@'¶: The absolute path to the source root.

srcTestPath = ('testing', 'test-cases', 'selenium-tests')¶: A tuple representing the path to the selenium test sources relative to source_path.

classmethod startServer()¶: Start a local web server. (depreciated)

classmethod stopServer()¶: Stop the local webserver. (depreciated)

tearDown()¶: Stop the selenium driver and calls the coverage handler if enabled.

testBaseURL = 'http://@TESTING_HOST@:@TESTING_PORT@'¶: The root URL of the test webserver.

testCase = ()¶: A tuple representing the path to a specific test case. This value should be set by all derived classes. The path is used to determine both the image store path on MIDAS server and the local image output path.

testHost = '@TESTING_HOST@'¶: The address of the webserver hosting the test content configured by cmake.

testPath = ('test', 'selenium')¶: A tuple giving the selenium test root relative to both testBaseURL and deploy_path.

testPort = '@TESTING_PORT@'¶: The port of the webserver hosting the test content configured by cmake.

testRevision = 1¶: The revision number of the test. This value should be set by all derived classes and incremented whenever there are changes to either the test case or the geojs source resulting in an expected change in screenshots. After incrementing this value, new baseline images must be uploaded to the MIDAS server.

wait(variable='window.testComplete', function=None, timeout=30)¶

Wait for a variable to be set to true, or a function to return true. Raise an error if timeout is exceeded.

Parameters:	variable (string) – The variable to query. function (string) – The function to execute. timeout (float) – The maximum number of seconds to wait.

class selenium_test.ChromeTest(methodName='runTest')¶

Bases: selenium_test.BaseTest

Chrome test base class. Uses the Chrome selenium driver. May be extended in the future to handle Chrome specific customizations. All tests derived from here are disabled by default because they require special drivers to be installed. Setting the environment variable CHROME_TESTS to ON will enable them.

class selenium_test.FirefoxTest(methodName='runTest')¶

Bases: selenium_test.BaseTest

Firefox test base class. Uses the Firefox selenium driver. May be extended in the future to handle Firefox specific customizations. Setting the environment variable FIREFOX_TESTS to OFF will turn off all tests derived from here.

exception selenium_test.ImageDifferenceException(**kw)¶

Bases: exceptions.BaseException

Exception to be raised when two images differ. Stores extra information that can be captured to handle uploading failed tests.

class selenium_test.NullDriver¶

Bases: object

A placeholder for selenium drivers that does nothing.

exception selenium_test.ThresholdException(**kw)¶

Bases: exceptions.BaseException

Exception to be raised when a test doesn’t meet a threshold value.

selenium_test.makeAllBrowserTest(cls, baseName=None, **kw)¶

Instrument a test class to run in all currently enabled browsers. Takes in a class that will be used to generate browser specific classes using class mixins. This is a convience function for the case when a test doesn’t need any special handling for different browsers. Extra keyword arguments are appended as class level variables.

Parameters:	cls (class) – The base test class baseName (str) – Override cls.__name__ to construct generated class names

For example,

class MyTest(object):
    def test_example(self):
        pass  # Do test here

makeAllBrowserTest(MyTest, aparam=1)

selenium_test.setUpModule()¶: A module wide set up method that starts the test web server. Unless there is a reason to override the default behavior in your test, you should import this function into your test module.

selenium_test.tearDownModule()¶: A module wide tear down method that stops the test web server. Unless there is a reason to override the default behavior in your test, you should import this function into your test module.