Holmium API documentation

Public classes

Page Objects & Friends

class holmium.core.Page(driver, url=None, iframe=None)

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)

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)

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 <lambda> at 0x7f1c42f601b8>, only_if=<function <lambda> at 0x7f1c42f60230>, facet=False)

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 elapases. 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.
class holmium.core.Elements(locator_type, query_string=None, base_element=None, timeout=0, value=<function <lambda> at 0x7f1c42f60578>, only_if=<function <lambda> at 0x7f1c42f605f0>, facet=False)

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 all the elements are present. 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.
class holmium.core.ElementMap(locator_type, query_string=None, base_element=None, timeout=0, key=<function <lambda> at 0x7f1c42f607d0>, value=<function <lambda> at 0x7f1c42f60848>, only_if=<function <lambda> at 0x7f1c42f608c0>, facet=False)

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. If not provided the default function used checks that all the elements are present. The list of located selenium.webdriver.remote.webelement.WebElement instances is passed as the only argument to the function.
class holmium.core.Locators

proxy class to access locator types

CLASS_NAME = 'class name'
CSS_SELECTOR = 'css selector'
ID = 'id'
NAME = 'name'
TAG_NAME = 'tag name'
XPATH = 'xpath'
classmethod is_valid(by)

Deprecated Classes

Deprecated since version 0.3.

Warning

Earlier versions of holmium.core used rather verbose names for Page objects and elements. They have been removed as of version 0.4 and accessing them will raise a exceptions.SyntaxError.

class holmium.core.PageObject(driver, url=None, iframe=None)

Deprecated alias for Page

class holmium.core.PageElement(locator_type, query_string, base_element=None, timeout=0, value=<function <lambda> at 0x7f1c42f601b8>, only_if=<function <lambda> at 0x7f1c42f60230>, facet=False)

Deprecated alias for Element

class holmium.core.PageElements(locator_type, query_string=None, base_element=None, timeout=0, value=<function <lambda> at 0x7f1c42f60578>, only_if=<function <lambda> at 0x7f1c42f605f0>, facet=False)

Deprecated alias for Elements

class holmium.core.PageElementMap(locator_type, query_string=None, base_element=None, timeout=0, key=<function <lambda> at 0x7f1c42f607d0>, value=<function <lambda> at 0x7f1c42f60848>, only_if=<function <lambda> at 0x7f1c42f608c0>, facet=False)

Deprecated alias for ElementMap

class holmium.core.HolmiumTestCase(methodName='runTest')

Deprecated alias for TestCase

Utilities

class holmium.core.TestCase(methodName='runTest')

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, element, timeout=0, msg=None)

Fail if the condition specified does not hold for the element within the specified timeout

Parameters:
assertElementAttributeEqual(element, key, value, msg=None)

Fail if the element does not have the specified attribute value

assertElementCSS(element, css_property, value, msg=None)

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)

Fail if the element is not visible

assertElementSize(element, width, height, msg=None)

Fail if the element size does not match the provided values

assertElementTextEqual(element, text, msg=None)

Fail if the text attribute of the element does not match

assertElementsDisplayed(elements, msg=None)

Fail if any of the elements in the element collection are not visible

classmethod setUpClass()

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

clear the cookies on the driver after each test

classmethod tearDownClass()

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'}})
Dictionary like helper class for maintaining test data configurations
per environment.

holmium.core.TestCase and holmium.core.HolmiumNose both look 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 (specified with --holmium-env when using nose or HO_ENV as an environment variable) 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)

base class for implementing custom element enhancers to add functionality to located webelements based on the element type (tag name)

classmethod matches(element)

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

holmium.core.register_enhancer(enhancer)

registers a ElementEnhancer with the internal lookup

holmium.core.reset_enhancers()

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.

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 <lambda> at 0x7f1c42f601b8>, only_if=<function <lambda> at 0x7f1c42f60230>, facet=False)[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[source]

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[source]

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[source]

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

nose plugin to allow bootstrapping testcases with a selenium driver

afterTest(_)

run after the test completes. kill the browser or just clear cookies depending on config

beforeTest(test)

setup the initialization for the driver, and load the config

static is_freshen_test(test)

checks for tell tale signs of being a fresher test

options(parser, env)

Register command line options

startTest(test)

before each test set the self.driver/self.drivers attribute for the test.

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.