"""Robot Framework test library for verifying and modifying XML documents.

ROBOT_LIBRARY_SCOPE = 'GLOBAL'

ROBOT_LIBRARY_VERSION = get_version()

_xml_declaration = re.compile('^<\?xml .*\?>')

def __init__(self, use_lxml=False):

"""Import library with optionally lxml mode enabled.

use_lxml = is_truthy(use_lxml)

if use_lxml and lxml_etree:

self.etree = lxml_etree

self.modern_etree = True

self.lxml_etree = True

else:

self.etree = ET

self.modern_etree = ET.VERSION >= '1.3'

self.lxml_etree = False

if use_lxml and not lxml_etree:

logger.warn('XML library reverted to use standard ElementTree '

'because lxml module is not installed.')

self._ns_stripper = NameSpaceStripper(self.etree, self.lxml_etree)

def parse_xml(self, source, keep_clark_notation=False, strip_namespaces=False):

"""Parses the given XML file or string into an element structure.

with ETSource(source) as source:

tree = self.etree.parse(source)

if self.lxml_etree:

strip = (lxml_etree.Comment, lxml_etree.ProcessingInstruction)

lxml_etree.strip_elements(tree, *strip, **dict(with_tail=False))

root = tree.getroot()

if not is_truthy(keep_clark_notation):

self._ns_stripper.strip(root, preserve=is_falsy(strip_namespaces))

return root

def get_element(self, source, xpath='.'):

"""Returns an element in the ``source`` matching the ``xpath``.

elements = self.get_elements(source, xpath)

if len(elements) != 1:

self._raise_wrong_number_of_matches(len(elements), xpath)

return elements[0]

def _raise_wrong_number_of_matches(self, count, xpath, message=None):

if not message:

message = self._wrong_number_of_matches(count, xpath)

raise AssertionError(message)

def _wrong_number_of_matches(self, count, xpath):

if not count:

return "No element matching '%s' found." % xpath

if count == 1:

return "One element matching '%s' found." % xpath

return "Multiple elements (%d) matching '%s' found." % (count, xpath)

def get_elements(self, source, xpath):

"""Returns a list of elements in the ``source`` matching the ``xpath``.

if is_string(source) or is_bytes(source):

source = self.parse_xml(source)

finder = ElementFinder(self.etree, self.modern_etree, self.lxml_etree)

return finder.find_all(source, xpath)

def get_child_elements(self, source, xpath='.'):

"""Returns the child elements of the specified element as a list.

return list(self.get_element(source, xpath))

def get_element_count(self, source, xpath='.'):

"""Returns and logs how many elements the given ``xpath`` matches.

count = len(self.get_elements(source, xpath))

logger.info("%d element%s matched '%s'." % (count, s(count), xpath))

return count

def element_should_exist(self, source, xpath='.', message=None):

"""Verifies that one or more element match the given ``xpath``.

count = self.get_element_count(source, xpath)

if not count:

self._raise_wrong_number_of_matches(count, xpath, message)

def element_should_not_exist(self, source, xpath='.', message=None):

"""Verifies that no element match the given ``xpath``.

count = self.get_element_count(source, xpath)

if count:

self._raise_wrong_number_of_matches(count, xpath, message)

def get_element_text(self, source, xpath='.', normalize_whitespace=False):

"""Returns all text of the element, possibly whitespace normalized.

element = self.get_element(source, xpath)

text = ''.join(self._yield_texts(element))

if is_truthy(normalize_whitespace):

text = self._normalize_whitespace(text)

return text

def _yield_texts(self, element, top=True):

if element.text:

yield element.text

for child in element:

for text in self._yield_texts(child, top=False):

yield text

if element.tail and not top:

yield element.tail

def _normalize_whitespace(self, text):

return ' '.join(text.split())

def get_elements_texts(self, source, xpath, normalize_whitespace=False):

"""Returns text of all elements matching ``xpath`` as a list.

return [self.get_element_text(elem, normalize_whitespace=normalize_whitespace)

for elem in self.get_elements(source, xpath)]

def element_text_should_be(self, source, expected, xpath='.',

normalize_whitespace=False, message=None):

"""Verifies that the text of the specified element is ``expected``.

text = self.get_element_text(source, xpath, normalize_whitespace)

should_be_equal(text, expected, message, values=False)

def element_text_should_match(self, source, pattern, xpath='.',

normalize_whitespace=False, message=None):

"""Verifies that the text of the specified element matches ``expected``.

text = self.get_element_text(source, xpath, normalize_whitespace)

should_match(text, pattern, message, values=False)

@keyword(types=None)

def get_element_attribute(self, source, name, xpath='.', default=None):

"""Returns the named attribute of the specified element.

return self.get_element(source, xpath).get(name, default)

def get_element_attributes(self, source, xpath='.'):

"""Returns all attributes of the specified element.

return dict(self.get_element(source, xpath).attrib)

def element_attribute_should_be(self, source, name, expected, xpath='.',

message=None):

"""Verifies that the specified attribute is ``expected``.

attr = self.get_element_attribute(source, name, xpath)

should_be_equal(attr, expected, message, values=False)

def element_attribute_should_match(self, source, name, pattern, xpath='.',

message=None):

"""Verifies that the specified attribute matches ``expected``.

attr = self.get_element_attribute(source, name, xpath)

if attr is None:

raise AssertionError("Attribute '%s' does not exist." % name)

should_match(attr, pattern, message, values=False)

def element_should_not_have_attribute(self, source, name, xpath='.', message=None):

"""Verifies that the specified element does not have attribute ``name``.

attr = self.get_element_attribute(source, name, xpath)

if attr is not None:

raise AssertionError(message or "Attribute '%s' exists and "

"has value '%s'." % (name, attr))

def elements_should_be_equal(self, source, expected, exclude_children=False,

normalize_whitespace=False):

"""Verifies that the given ``source`` element is equal to ``expected``.

self._compare_elements(source, expected, should_be_equal,

exclude_children, normalize_whitespace)

def elements_should_match(self, source, expected, exclude_children=False,

normalize_whitespace=False):

"""Verifies that the given ``source`` element matches ``expected``.

self._compare_elements(source, expected, should_match,

exclude_children, normalize_whitespace)

def _compare_elements(self, source, expected, comparator, exclude_children,

normalize_whitespace):

normalizer = self._normalize_whitespace \

if is_truthy(normalize_whitespace) else None

comparator = ElementComparator(comparator, normalizer, exclude_children)

comparator.compare(self.get_element(source), self.get_element(expected))

def set_element_tag(self, source, tag, xpath='.'):

"""Sets the tag of the specified element.

source = self.get_element(source)

self.get_element(source, xpath).tag = tag

return source

def set_elements_tag(self, source, tag, xpath='.'):

"""Sets the tag of the specified elements.

for elem in self.get_elements(source, xpath):

self.set_element_tag(elem, tag)

@keyword(types=None)

def set_element_text(self, source, text=None, tail=None, xpath='.'):

"""Sets text and/or tail text of the specified element.

source = self.get_element(source)

element = self.get_element(source, xpath)

if text is not None:

element.text = text

if tail is not None:

element.tail = tail