Holmium API documentation¶
Public classes¶
Page Objects & Friends¶
-
class
holmium.core.
Page
(driver, url=None, iframe=None)[source]¶ Base class for all page objects to extend from. void Instance methods implemented by subclasses are provisioned with fluent wrappers to facilitate with writing code such as:
class Google(Page): def query(self): .... def submit(self): .... def get_results(self): .... assert len(Google().query("page objects").submit().get_results()) > 0
-
class
holmium.core.
Section
(locator_type, query_string, iframe=None, timeout=0)[source]¶ Base class to encapsulate reusable page sections:
class MySection(Section): things = Elements( .... ) class MyPage(Page): section_1 = MySection(Locators.CLASS_NAME, "section") section_2 = MySection(Locators.ID, "unique_section")
-
class
holmium.core.
Sections
(locator_type, query_string, iframe=None, timeout=0)[source]¶ Base class for an Iterable view of a collection of
holmium.core.Section
objects.
-
class
holmium.core.
Element
(locator_type, query_string, base_element=None, timeout=0, value=<function ElementGetter.<lambda>>, only_if=<function ElementGetter.<lambda>>, facet=False, filter_by=<function ElementGetter.<lambda>>)[source]¶ Utility to get a
selenium.webdriver.remote.webelement.WebElement
by querying via one ofholmium.core.Locators
Parameters: - locator_type (holmium.core.Locators) – selenium locator to use when locating the element
- query_string (str) – the value to pass to the locator
- base_element (holmium.core.Element) – a reference to another element under which to locate this element.
- timeout (int) – time to implicitely wait for the element
- value (lambda) – transform function for the value of the element.
The located
selenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function. - only_if (function) – extra validation function that is called
repeatedly until
timeout
elapses. If not provided the default function used checks that the element is present. The locatedselenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function. - facet (bool) – flag to treat this element as a facet.
- filter_by (function) – condition function that determines if the
located
selenium.webdriver.remote.webelement.WebElement
, the only argument passed to the function, should be returned. If not provided, the default function used checks that the element is present.
-
class
holmium.core.
Elements
(locator_type, query_string=None, base_element=None, timeout=0, value=<function Elements.<lambda>>, only_if=<function Elements.<lambda>>, facet=False, filter_by=<function Elements.<lambda>>)[source]¶ Utility to get a collection of
selenium.webdriver.remote.webelement.WebElement
objects by querying via one ofholmium.core.Locators
Parameters: - locator_type (holmium.core.Locators) – selenium locator to use when locating the element
- query_string (str) – the value to pass to the locator
- base_element (holmium.core.Element) – a reference to another element under which to locate this element.
- timeout (int) – time to implicitely wait for the element
- value (lambda) – transform function for each element in the collection.
The located
selenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function. - only_if (function) – extra validation function that is called
repeatedly until
timeout
elapses. If not provided the default function used checks that the element collection is not empty. The list of locatedselenium.webdriver.remote.webelement.WebElement
instances is passed as the only argument to the function. - facet (bool) – flag to treat this element as a facet.
- filter_by (function) – condition function determines which elements are
included in the collection. If not provided the default function used
includes all elements identified by
query_string
. Aselenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function.
-
class
holmium.core.
ElementMap
(locator_type, query_string=None, base_element=None, timeout=0, key=<function ElementMap.<lambda>>, value=<function ElementMap.<lambda>>, only_if=<function ElementMap.<lambda>>, facet=False, filter_by=<function ElementMap.<lambda>>)[source]¶ Used to create dynamic dictionaries based on an element locator specified by one of
holmium.core.Locators
.The wrapped dictionary is an
collections.OrderedDict
instance.Parameters: - locator_type (holmium.core.Locators) – selenium locator to use when locating the element
- query_string (str) – the value to pass to the locator
- base_element (holmium.core.Element) – a reference to another element under which to locate this element.
- timeout (int) – time to implicitely wait for the element
- facet (bool) – flag to treat this element as a facet.
- key (lambda) – transform function for mapping a key to a WebElement in
the collection. The located
selenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function. - value (lambda) – transform function for the value when accessed via the
key. The located
selenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function. - only_if (function) – extra validation function that is called
repeatedly until
timeout
elapses. If not provided the default function used checks that the element collection is not empty. The list of locatedselenium.webdriver.remote.webelement.WebElement
instances is passed as the only argument to the function. - filter_by (function) – condition function determines which elements are
included in the collection. If not provided the default function used
includes all elements identified by
query_string
. Aselenium.webdriver.remote.webelement.WebElement
instance is passed as the only argument to the function.
Utilities¶
-
class
holmium.core.
TestCase
(methodName='runTest')[source]¶ Base class for creating test classes for writing holmium driven test cases. More details can be found at The TestCase base class
-
assertConditionWithWait
(driver, condition, timeout=0, msg=None, ignored_exceptions=None)[source]¶ Fail if the condition specified does not hold for the element within the specified timeout
Parameters: - driver – the selenium driver
- condition – an instance of
selenium.webdriver.support.expected_conditions
- msg – the failure message when timeout, could be a string or a callable without arguments that returns a string
- timeout – to be passed to selenium.webdriver.support.wait.WebDriverWait
- ignored_exceptions – to be passed to selenium.webdriver.support.wait.WebDriverWait
-
assertElementAttributeEqual
(element, key, value, msg=None)[source]¶ Fail if the element does not have the specified attribute value
-
assertElementCSS
(element, css_property, value, msg=None)[source]¶ Fail if the element does not exhibit the correct css property value. The value of the elements css property is the one returned by
selenium.webdriver.remote.webelement.WebElement.value_of_css_property()
-
assertElementSize
(element, width, height, msg=None)[source]¶ Fail if the element size does not match the provided values
-
assertElementTextEqual
(element, text, msg=None)[source]¶ Fail if the text attribute of the element does not match
-
assertElementsDisplayed
(elements, msg=None)[source]¶ Fail if any of the elements in the element collection are not visible
-
-
class
holmium.core.
Config
(dct, environment={'holmium': {'environment': 'development'}})[source]¶ - Dictionary like helper class for maintaining test data configurations
- per environment.
holmium.core.TestCase
looks for either a config.json or config.py file in the same directory as the test file, and will make aconfig
object available to the test case instance.The
holmium.core.Config
object is aware of the environment and will return the config variable from that environment or from the default key.Values in the config file can use
jinja2.Template
templates to access either values from itself, environment variables or a select magic holmium variables:holmium.environment
,holmium.browser
,holmium.user_agent
andholmium.remote
.Example config structure (which uses a magic variable
holmium.environment
and an environment variable$PATH
).JSON
{ "default": { "path": "{{PATH}}", "login_url": "{{url}}/{{holmium.environment}}/login", "username": "{{holmium.environment}}user" }, "production": { "url": "http://prod.com", "password": "sekret" }, "development": { "url": "http://dev.com", "password": "password" } }
Python
config = { { 'default': { 'path':"{{PATH}}", 'login_url': '{{url}}/{{holmium.environment}}/login'}, 'username' : '{{holmium.environment}}user' }, 'production': { 'url':'http://prod.com', 'password': 'sekret' }, 'development': { 'url':'http://dev.com', 'password': 'password' } } }
When accessing
self.config
within a test, due to the default:self.config['path']
will always return the value of the environment- variable PATH,
self.config['password']
will always return ‘sekret’
if
HO_ENV
or--holmium-env
areproduction
:self.config['username']
will returnproductionuser
self.config['password']
will returnsekret
self.config['login_url']
will returnhttp://prod.com/production/login
if
HO_ENV
or--holmium-env
aredevelopment
:self.config['username']
will returndevelopmentuser
self.config['password']
will returnpassword
self.config['login_url']
will returnhttp://dev.com/development/login
-
class
holmium.core.
ElementEnhancer
(element)[source]¶ base class for implementing custom element enhancers to add functionality to located webelements based on the element type (tag name)
-
holmium.core.
register_enhancer
(enhancer)[source]¶ registers a
ElementEnhancer
with the internal lookup
-
holmium.core.
reset_enhancers
()[source]¶ resets the state so that any
ElementEnhancer
that was registered via a call toregister_enhancer()
is removed.
Internal Classes¶
Page Object Helpers¶
-
class
holmium.core.pageobject.
ElementDict
(instance, *args, **kwargs)[source]¶ proxy to a standard dict which would be stored in a
holmium.core.Page
.
-
class
holmium.core.pageobject.
ElementList
(instance, *args, **kwargs)[source]¶ proxy to a standard list which would be stored in a
holmium.core.Page
.
-
class
holmium.core.pageobject.
ElementGetter
(locator_type, query_string, base_element=None, timeout=0, value=<function ElementGetter.<lambda>>, only_if=<function ElementGetter.<lambda>>, facet=False, filter_by=<function ElementGetter.<lambda>>)[source]¶ internal class to encapsulate the logic used by
holmium.core.Element
&holmium.core.Elements
-
classmethod
enhance
(element)[source]¶ incase a higher level abstraction for a WebElement is available we will use that in Pages. (e.g. a select element is converted into
selenium.webdriver.support.ui.Select
)
-
root
¶ returns the root webelement
-
classmethod
-
class
holmium.core.facets.
FacetCollection
(*a)[source]¶ utility collection class for pageobjects to encapsulate facets
-
append
(item)[source]¶ overridden add method to pop the last item if its type does not support multiple facets on the same object.
-
evaluate_all
(driver)[source]¶ iterate over all registered
Facet
objects and validate themParameters: driver (selenium.webdriver.remote.webdriver.WebDriver) – the webdriver
-
type_map
¶ view on the list to help with figuring out if a facet of the same type already exists
-
-
class
holmium.core.facets.
Facet
(required=True, debug=False, **kwargs)[source]¶ base class to implement an attribute of a page
-
evaluate
(driver)[source]¶ evaluate whether this facet holds true. Raise an Exception if not.
Parameters: driver (selenium.webdriver.remote.webdriver.WebDriver) – the webdriver
-
parent_class
¶ returns the parent class
-
register
(obj)[source]¶ registers a
Facet
on an objectParameters: obj (holmium.core.facets.Faceted) – the object to register the facet on.
-
-
class
holmium.core.facets.
Faceted
[source]¶ mixin for objects that want to have facets registered on them.
-
exception
holmium.core.facets.
FacetError
(facet, exc=None)[source]¶ exception raised when a facet has an error or can’t complete
Parameters: - facet (holmium.core.facets.Facet) – the facet that failed to evaluate
- exc (exceptions.Exception) – the inner exception that caused the failure
-
class
holmium.core.conditions.
BaseCondition
[source]¶ base class to implement conditions passed to the
only_if
parameter ofholmium.core.pageobject.ElementGetter
subclasses.
Test configuration / execution¶
-
class
holmium.core.config.
HolmiumConfig
(browser, remote, capabilities, user_agent, environment, ignore_ssl, fresh_instance)[source]¶ utility class for storing holmium configuration options strictly. The class behaves like a dictionary after construction with the additional behavior that any attributes set on it are available as keys in the dictionary and vice versa.