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 aboveimageDifferenceThreshold
. If the two images are different sizes, this function will always raise.Parameters: Raises ImageDifferenceException: 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 amountdelta
.Parameters: - element (string) – A CSS selector.
- delta ([x, y]) – The number of pixels to drag in
x
andy
. - 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 right100
pixels and up10
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
and255
, with0
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:
-
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.
Parameters: - filename (string) – The file path of the image.
- relative (bool) – Whether to treat the filename as a relative or absolute path.
Return type: Raises Exception: 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.
-
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 attributetestRevision
is used.Parameters: - testName (string) – The name of the test.
- revision (int) – The revision number to compare against.
Raises ImageDifferenceException: 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
anddeploy_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.
- Each testing subdirectory contains one or more test classes derived from this class.
Test classes each have a class attribute
-
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
toON
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
toOFF
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.