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 of holmium.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 located selenium.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 of holmium.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 located selenium.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. A selenium.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 located selenium.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. A selenium.webdriver.remote.webelement.WebElement instance is passed as the only argument to the function.
class holmium.core.Locators[source]

proxy class to access locator types

CLASS_NAME = 'class name'
CSS_SELECTOR = 'css selector'
ID = 'id'
NAME = 'name'
TAG_NAME = 'tag name'
XPATH = 'xpath'

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()

assertElementDisplayed(element, msg=None)[source]

Fail if the element is not visible

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

classmethod setUpClass()[source]

prepare the driver initialization based on the environment variables that have been set. The driver is not actually initialized until the test itself actually refers to it via self.driver.

tearDown()[source]

clear the cookies on the driver after each test

classmethod tearDownClass()[source]

quit the driver after the test run (or after all the test methods in the class have finished if HO_BROWSER_PER_TEST is set).

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 a config 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 and holmium.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 are production:

  • self.config['username'] will return productionuser
  • self.config['password'] will return sekret
  • self.config['login_url'] will return http://prod.com/production/login

if HO_ENV or --holmium-env are development:

  • self.config['username'] will return developmentuser
  • self.config['password'] will return password
  • self.config['login_url'] will return http://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)

classmethod matches(element)[source]

class method to verify that this enhancer is appropriate for the provided webelement

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 to register_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.

items() → a set-like object providing a view on D's items[source]
values() → an object providing a view on D's values[source]
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

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 them

Parameters: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
get_name()[source]

returns the class name of the facet

get_parent_name()[source]

returns the class name of the parent

parent_class

returns the parent class

register(obj)[source]

registers a Facet on an object

Parameters: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.

evaluate()[source]

evaluates all registered facets (class & instance)

classmethod get_class_facets()[source]

returns the facets registered on the class (presumably via a decorator)

get_instance_facets()[source]

returns the facets registered on the instance

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 of holmium.core.pageobject.ElementGetter subclasses.

evaluate(element)[source]

abstract method to be implemented by derived classes.

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.