Robot Framework library for verifying and modifying XML documents. More...

Public Member Functions
def	__init__ (self, use_lxml=False)
	Import library with optionally lxml mode enabled. More...

def	add_element (self, source, element, index=None, xpath='.')
	Adds a child element to the specified element. More...

def	clear_element (self, source, xpath='.', clear_tail=False)
	Clears the contents of the specified element. More...

def	copy_element (self, source, xpath='.')
	Returns a copy of the specified element. More...

def	element_attribute_should_be (self, source, name, expected, xpath='.', message=None)
	Verifies that the specified attribute is `expected`. More...

def	element_attribute_should_match (self, source, name, pattern, xpath='.', message=None)
	Verifies that the specified attribute matches `expected`. More...

def	element_should_exist (self, source, xpath='.', message=None)
	Verifies that one or more element match the given `xpath`. More...

def	element_should_not_exist (self, source, xpath='.', message=None)
	Verifies that no element match the given `xpath`. More...

def	element_should_not_have_attribute (self, source, name, xpath='.', message=None)
	Verifies that the specified element does not have attribute `name`. More...

def	element_text_should_be (self, source, expected, xpath='.', normalize_whitespace=False, message=None)
	Verifies that the text of the specified element is `expected`. More...

def	element_text_should_match (self, source, pattern, xpath='.', normalize_whitespace=False, message=None)
	Verifies that the text of the specified element matches `expected`. More...

def	element_to_string (self, source, xpath='.', encoding=None)
	Returns the string representation of the specified element. More...

def	elements_should_be_equal (self, source, expected, exclude_children=False, normalize_whitespace=False)
	Verifies that the given `source` element is equal to `expected`. More...

def	elements_should_match (self, source, expected, exclude_children=False, normalize_whitespace=False)
	Verifies that the given `source` element matches `expected`. More...

def	evaluate_xpath (self, source, expression, context='.')
	Evaluates the given xpath expression and returns results. More...

def	get_child_elements (self, source, xpath='.')
	Returns the child elements of the specified element as a list. More...

def	get_element (self, source, xpath='.')
	Returns an element in the `source` matching the `xpath`. More...

def	get_element_attribute (self, source, name, xpath='.', default=None)
	Returns the named attribute of the specified element. More...

def	get_element_attributes (self, source, xpath='.')
	Returns all attributes of the specified element. More...

def	get_element_count (self, source, xpath='.')
	Returns and logs how many elements the given `xpath` matches. More...

def	get_element_text (self, source, xpath='.', normalize_whitespace=False)
	Returns all text of the element, possibly whitespace normalized. More...

def	get_elements (self, source, xpath)
	Returns a list of elements in the `source` matching the `xpath`. More...

def	get_elements_texts (self, source, xpath, normalize_whitespace=False)
	Returns text of all elements matching `xpath` as a list. More...

def	log_element (self, source, level='INFO', xpath='.')
	Logs the string representation of the specified element. More...

def	parse_xml (self, source, keep_clark_notation=False, strip_namespaces=False)
	Parses the given XML file or string into an element structure. More...

def	remove_element (self, source, xpath='', remove_tail=False)
	Removes the element matching `xpath` from the `source` structure. More...

def	remove_element_attribute (self, source, name, xpath='.')
	Removes attribute `name` from the specified element. More...

def	remove_element_attributes (self, source, xpath='.')
	Removes all attributes from the specified element. More...

def	remove_elements (self, source, xpath='', remove_tail=False)
	Removes all elements matching `xpath` from the `source` structure. More...

def	remove_elements_attribute (self, source, name, xpath='.')
	Removes attribute `name` from the specified elements. More...

def	remove_elements_attributes (self, source, xpath='.')
	Removes all attributes from the specified elements. More...

def	save_xml (self, source, path, encoding='UTF-8')
	Saves the given element to the specified file. More...

def	set_element_attribute (self, source, name, value, xpath='.')
	Sets attribute `name` of the specified element to `value`. More...

def	set_element_tag (self, source, tag, xpath='.')
	Sets the tag of the specified element. More...

def	set_element_text (self, source, text=None, tail=None, xpath='.')
	Sets text and/or tail text of the specified element. More...

def	set_elements_attribute (self, source, name, value, xpath='.')
	Sets attribute `name` of the specified elements to `value`. More...

def	set_elements_tag (self, source, tag, xpath='.')
	Sets the tag of the specified elements. More...

def	set_elements_text (self, source, text=None, tail=None, xpath='.')
	Sets text and/or tail text of the specified elements. More...

Public Attributes
	etree

	lxml_etree

	modern_etree

Static Public Attributes
string	ROBOT_LIBRARY_SCOPE = 'GLOBAL'

	ROBOT_LIBRARY_VERSION = get_version()

Private Member Functions
def	_compare_elements (self, source, expected, comparator, exclude_children, normalize_whitespace)

def	_find_parent (self, root, element)

def	_normalize_whitespace (self, text)

def	_preserve_tail (self, element, parent)

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

def	_remove_element (self, root, element, remove_tail=False)

def	_wrong_number_of_matches (self, count, xpath)

def	_yield_texts (self, element, top=True)

Private Attributes
	_ns_stripper

Static Private Attributes
	_xml_declaration

Detailed Description

Robot Framework library for verifying and modifying XML documents.

As the name implies, _XML_ is a library for verifying contents of XML files.
In practice, it is a pretty thin wrapper on top of Python's
[http://docs.python.org/library/xml.etree.elementtree.html|ElementTree XML API].

The library has the following main usages:

- Parsing an XML file, or a string containing XML, into an XML element
  structure and finding certain elements from it for for further analysis
  (e.g. `Parse XML` and `Get Element` keywords).
- Getting text or attributes of elements
  (e.g. `Get Element Text` and `Get Element Attribute`).
- Directly verifying text, attributes, or whole elements
  (e.g `Element Text Should Be` and `Elements Should Be Equal`).
- Modifying XML and saving it (e.g. `Set Element Text`, `Add Element`
  and `Save XML`).

== Table of contents ==

%TOC%

= Parsing XML =

XML can be parsed into an element structure using `Parse XML` keyword.
The XML to be parsed can be specified using a path to an XML file or as
a string or bytes that contain XML directly. The keyword returns the root
element of the structure, which then contains other elements as its
children and their children. Possible comments and processing instructions
in the source XML are removed.

XML is not validated during parsing even if has a schema defined. How
possible doctype elements are handled otherwise depends on the used XML
module and on the platform. The standard ElementTree strips doctypes
altogether but when `using lxml` they are preserved when XML is saved.

The element structure returned by `Parse XML`, as well as elements
returned by keywords such as `Get Element`, can be used as the ``source``
argument with other keywords. In addition to an already parsed XML
structure, other keywords also accept paths to XML files and strings
containing XML similarly as `Parse XML`. Notice that keywords that modify
XML do not write those changes back to disk even if the source would be
given as a path to a file. Changes must always be saved explicitly using
`Save XML` keyword.

When the source is given as a path to a file, the forward slash character
(``/``) can be used as the path separator regardless the operating system.
On Windows also the backslash works, but in the data it needs to be
escaped by doubling it (``\\\\``). Using the built-in variable ``${/}``
naturally works too.

Note: Support for XML as bytes is new in Robot Framework 3.2.

= Using lxml =

By default, this library uses Python's standard
[http://docs.python.org/library/xml.etree.elementtree.html|ElementTree]
module for parsing XML, but it can be configured to use
[http://lxml.de|lxml] module instead when `importing` the library.
The resulting element structure has same API regardless which module
is used for parsing.

The main benefits of using lxml is that it supports richer xpath syntax
than the standard ElementTree and enables using `Evaluate Xpath` keyword.
It also preserves the doctype and possible namespace prefixes saving XML.

= Example =

The following simple example demonstrates parsing XML and verifying its
contents both using keywords in this library and in _BuiltIn_ and
_Collections_ libraries. How to use xpath expressions to find elements
and what attributes the returned elements contain are discussed, with
more examples, in `Finding elements with xpath` and `Element attributes`
sections.

In this example, as well as in many other examples in this documentation,
``${XML}`` refers to the following example XML document. In practice
``${XML}`` could either be a path to an XML file or it could contain the XML
itself.

| <example>
|   <first id="1">text</first>
|   <second id="2">
|     <child/>
|   </second>
|   <third>
|     <child>more text</child>
|     <second id="child"/>
|     <child><grandchild/></child>
|   </third>
|   <html>
|     <p>
|       Text with <b>bold</b> and <i>italics</i>.
|     </p>
|   </html>
| </example>

| ${root} =                | `Parse XML`   | ${XML}  |       |             |
| `Should Be Equal`        | ${root.tag}   | example |       |             |
| ${first} =               | `Get Element` | ${root} | first |             |
| `Should Be Equal`        | ${first.text} | text    |       |             |
| `Dictionary Should Contain Key` | ${first.attrib}  | id    |             |
| `Element Text Should Be` | ${first}      | text    |       |             |
| `Element Attribute Should Be` | ${first} | id      | 1     |             |
| `Element Attribute Should Be` | ${root}  | id      | 1     | xpath=first |
| `Element Attribute Should Be` | ${XML}   | id      | 1     | xpath=first |

Notice that in the example three last lines are equivalent. Which one to
use in practice depends on which other elements you need to get or verify.
If you only need to do one verification, using the last line alone would
suffice. If more verifications are needed, parsing the XML with `Parse XML`
only once would be more efficient.

= Finding elements with xpath =

ElementTree, and thus also this library, supports finding elements using
xpath expressions. ElementTree does not, however, support the full xpath
standard. The supported xpath syntax is explained below and
[https://docs.python.org/library/xml.etree.elementtree.html#xpath-support|
ElementTree documentation] provides more details. In the examples
``${XML}`` refers to the same XML structure as in the earlier example.

If lxml support is enabled when `importing` the library, the whole
[http://www.w3.org/TR/xpath/|xpath 1.0 standard] is supported.
That includes everything listed below but also lot of other useful
constructs.

== Tag names ==

When just a single tag name is used, xpath matches all direct child
elements that have that tag name.

| ${elem} =          | `Get Element`  | ${XML}      | third |
| `Should Be Equal`  | ${elem.tag}    | third       |       |
| @{children} =      | `Get Elements` | ${elem}     | child |
| `Length Should Be` | ${children}    | 2           |       |

== Paths ==

Paths are created by combining tag names with a forward slash (``/``). For
example, ``parent/child`` matches all ``child`` elements under ``parent``
element. Notice that if there are multiple ``parent`` elements that all
have ``child`` elements, ``parent/child`` xpath will match all these
``child`` elements.

| ${elem} =         | `Get Element` | ${XML}     | second/child            |
| `Should Be Equal` | ${elem.tag}   | child      |                         |
| ${elem} =         | `Get Element` | ${XML}     | third/child/grandchild  |
| `Should Be Equal` | ${elem.tag}   | grandchild |                         |

== Wildcards ==

An asterisk (``*``) can be used in paths instead of a tag name to denote
any element.

| @{children} =      | `Get Elements` | ${XML} | */child |
| `Length Should Be` | ${children}    | 3      |         |

== Current element ==

The current element is denoted with a dot (``.``). Normally the current
element is implicit and does not need to be included in the xpath.

== Parent element ==

The parent element of another element is denoted with two dots (``..``).
Notice that it is not possible to refer to the parent of the current
element.

| ${elem} =         | `Get Element` | ${XML} | */second/.. |
| `Should Be Equal` | ${elem.tag}   | third  |             |

== Search all sub elements ==

Two forward slashes (``//``) mean that all sub elements, not only the
direct children, are searched. If the search is started from the current
element, an explicit dot is required.

| @{elements} =      | `Get Elements` | ${XML} | .//second |
| `Length Should Be` | ${elements}    | 2      |           |
| ${b} =             | `Get Element`  | ${XML} | html//b   |
| `Should Be Equal`  | ${b.text}      | bold   |           |

== Predicates ==

Predicates allow selecting elements using also other criteria than tag
names, for example, attributes or position. They are specified after the
normal tag name or path using syntax ``path[predicate]``. The path can have
wildcards and other special syntax explained earlier. What predicates
the standard ElementTree supports is explained in the table below.

|  = Predicate =  |             = Matches =           |    = Example =     |
| @attrib         | Elements with attribute ``attrib``. | second[@id]        |
| @attrib="value" | Elements with attribute ``attrib`` having value ``value``. | *[@id="2"] |
| position        | Elements at the specified position. Position can be an integer (starting from 1), expression ``last()``, or relative expression like ``last() - 1``. | third/child[1] |
| tag             | Elements with a child element named ``tag``. | third/child[grandchild] |

Predicates can also be stacked like ``path[predicate1][predicate2]``.
A limitation is that possible position predicate must always be first.

= Element attributes =

All keywords returning elements, such as `Parse XML`, and `Get Element`,
return ElementTree's
[http://docs.python.org/library/xml.etree.elementtree.html#element-objects|Element objects].
These elements can be used as inputs for other keywords, but they also
contain several useful attributes that can be accessed directly using
the extended variable syntax.

The attributes that are both useful and convenient to use in the data
are explained below. Also other attributes, including methods, can
be accessed, but that is typically better to do in custom libraries than
directly in the data.

The examples use the same ``${XML}`` structure as the earlier examples.

== tag ==

The tag of the element.

| ${root} =         | `Parse XML` | ${XML}  |
| `Should Be Equal` | ${root.tag} | example |

== text ==

The text that the element contains or Python ``None`` if the element has no
text. Notice that the text _does not_ contain texts of possible child
elements nor text after or between children. Notice also that in XML
whitespace is significant, so the text contains also possible indentation
and newlines. To get also text of the possible children, optionally
whitespace normalized, use `Get Element Text` keyword.

| ${1st} =          | `Get Element` | ${XML}  | first        |
| `Should Be Equal` | ${1st.text}   | text    |              |
| ${2nd} =          | `Get Element` | ${XML}  | second/child |
| `Should Be Equal` | ${2nd.text}   | ${NONE} |              |
| ${p} =            | `Get Element` | ${XML}  | html/p       |
| `Should Be Equal` | ${p.text}     | \\n${SPACE*6}Text with${SPACE} |

== tail ==

The text after the element before the next opening or closing tag. Python
``None`` if the element has no tail. Similarly as with ``text``, also
``tail`` contains possible indentation and newlines.

| ${b} =            | `Get Element` | ${XML}  | html/p/b  |
| `Should Be Equal` | ${b.tail}     | ${SPACE}and${SPACE} |

== attrib ==

A Python dictionary containing attributes of the element.

| ${2nd} =          | `Get Element`       | ${XML} | second |
| `Should Be Equal` | ${2nd.attrib['id']} | 2      |        |
| ${3rd} =          | `Get Element`       | ${XML} | third  |
| `Should Be Empty` | ${3rd.attrib}       |        |        |

= Handling XML namespaces =

ElementTree and lxml handle possible namespaces in XML documents by adding
the namespace URI to tag names in so called Clark Notation. That is
inconvenient especially with xpaths, and by default this library strips
those namespaces away and moves them to ``xmlns`` attribute instead. That
can be avoided by passing ``keep_clark_notation`` argument to `Parse XML`
keyword. Alternatively `Parse XML` supports stripping namespace information
altogether by using ``strip_namespaces`` argument. The pros and cons of
different approaches are discussed in more detail below.

== How ElementTree handles namespaces ==

If an XML document has namespaces, ElementTree adds namespace information
to tag names in [http://www.jclark.com/xml/xmlns.htm|Clark Notation]
(e.g. ``{http://ns.uri}tag``) and removes original ``xmlns`` attributes.
This is done both with default namespaces and with namespaces with a prefix.
How it works in practice is illustrated by the following example, where
``${NS}`` variable contains this XML document:

| <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
|                 xmlns="http://www.w3.org/1999/xhtml">
|   <xsl:template match="/">
|     <html></html>
|   </xsl:template>
| </xsl:stylesheet>

| ${root} = | `Parse XML` | ${NS} | keep_clark_notation=yes |
| `Should Be Equal` | ${root.tag} | {http://www.w3.org/1999/XSL/Transform}stylesheet |
| `Element Should Exist` | ${root} | {http://www.w3.org/1999/XSL/Transform}template/{http://www.w3.org/1999/xhtml}html |
| `Should Be Empty` | ${root.attrib} |

As you can see, including the namespace URI in tag names makes xpaths
really long and complex.

If you save the XML, ElementTree moves namespace information back to
``xmlns`` attributes. Unfortunately it does not restore the original
prefixes:

| <ns0:stylesheet xmlns:ns0="http://www.w3.org/1999/XSL/Transform">
|   <ns0:template match="/">
|     <ns1:html xmlns:ns1="http://www.w3.org/1999/xhtml"></ns1:html>
|   </ns0:template>
| </ns0:stylesheet>

The resulting output is semantically same as the original, but mangling
prefixes like this may still not be desirable. Notice also that the actual
output depends slightly on ElementTree version.

== Default namespace handling ==

Because the way ElementTree handles namespaces makes xpaths so complicated,
this library, by default, strips namespaces from tag names and moves that
information back to ``xmlns`` attributes. How this works in practice is
shown by the example below, where ``${NS}`` variable contains the same XML
document as in the previous example.

| ${root} = | `Parse XML` | ${NS} |
| `Should Be Equal` | ${root.tag} | stylesheet |
| `Element Should Exist` | ${root} | template/html |
| `Element Attribute Should Be` | ${root} | xmlns | http://www.w3.org/1999/XSL/Transform |
| `Element Attribute Should Be` | ${root} | xmlns | http://www.w3.org/1999/xhtml | xpath=template/html |

Now that tags do not contain namespace information, xpaths are simple again.

A minor limitation of this approach is that namespace prefixes are lost.
As a result the saved output is not exactly same as the original one in
this case either:

| <stylesheet xmlns="http://www.w3.org/1999/XSL/Transform">
|   <template match="/">
|     <html xmlns="http://www.w3.org/1999/xhtml"></html>
|   </template>
| </stylesheet>

Also this output is semantically same as the original. If the original XML
had only default namespaces, the output would also look identical.

== Namespaces when using lxml ==

This library handles namespaces same way both when `using lxml` and when
not using it. There are, however, differences how lxml internally handles
namespaces compared to the standard ElementTree. The main difference is
that lxml stores information about namespace prefixes and they are thus
preserved if XML is saved. Another visible difference is that lxml includes
namespace information in child elements got with `Get Element` if the
parent element has namespaces.

== Stripping namespaces altogether ==

Because namespaces often add unnecessary complexity, `Parse XML` supports
stripping them altogether by using ``strip_namespaces=True``. When this
option is enabled, namespaces are not shown anywhere nor are they included
if XML is saved.

== Attribute namespaces ==

Attributes in XML documents are, by default, in the same namespaces as
the element they belong to. It is possible to use different namespaces
by using prefixes, but this is pretty rare.

If an attribute has a namespace prefix, ElementTree will replace it with
Clark Notation the same way it handles elements. Because stripping
namespaces from attributes could cause attribute conflicts, this library
does not handle attribute namespaces at all. Thus the following example
works the same way regardless how namespaces are handled.

| ${root} = | `Parse XML` | <root id="1" ns:id="2" xmlns:ns="http://my.ns"/> |
| `Element Attribute Should Be` | ${root} | id | 1 |
| `Element Attribute Should Be` | ${root} | {http://my.ns}id | 2 |

= Boolean arguments =

Some keywords accept arguments that are handled as Boolean values true or
false. If such an argument is given as a string, it is considered false if
it is an empty string or equal to ``FALSE``, ``NONE``, ``NO``, ``OFF`` or
``0``, case-insensitively. Other strings are considered true regardless
their value, and other argument types are tested using the same
[http://docs.python.org/library/stdtypes.html#truth|rules as in Python].

True examples:
| `Parse XML` | ${XML} | keep_clark_notation=True    | # Strings are generally true.    |
| `Parse XML` | ${XML} | keep_clark_notation=yes     | # Same as the above.             |
| `Parse XML` | ${XML} | keep_clark_notation=${TRUE} | # Python ``True`` is true.       |
| `Parse XML` | ${XML} | keep_clark_notation=${42}   | # Numbers other than 0 are true. |

False examples:
| `Parse XML` | ${XML} | keep_clark_notation=False    | # String ``false`` is false.   |
| `Parse XML` | ${XML} | keep_clark_notation=no       | # Also string ``no`` is false. |
| `Parse XML` | ${XML} | keep_clark_notation=${EMPTY} | # Empty string is false.       |
| `Parse XML` | ${XML} | keep_clark_notation=${FALSE} | # Python ``False`` is false.   |

Considering ``OFF`` and ``0`` false is new in Robot Framework 3.1.

== Pattern matching ==

Some keywords, for example `Elements Should Match`, support so called
[http://en.wikipedia.org/wiki/Glob_(programming)|glob patterns] where:

| ``*``        | matches any string, even an empty string                |
| ``?``        | matches any single character                            |
| ``[chars]``  | matches one character in the bracket                    |
| ``[!chars]`` | matches one character not in the bracket                |
| ``[a-z]``    | matches one character from the range in the bracket     |
| ``[!a-z]``   | matches one character not from the range in the bracket |

Unlike with glob patterns normally, path separator characters ``/`` and
``\\`` and the newline character ``\\n`` are matches by the above
wildcards.

Support for brackets like ``[abc]`` and ``[!a-z]`` is new in
Robot Framework 3.1

Definition at line 456 of file XML.py.

Constructor & Destructor Documentation

◆ init()

def robot.libraries.XML.XML.__init__	(	self,
		use_lxml = `False`
	)

Import library with optionally lxml mode enabled.

    By default this library uses Python's standard
    [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree]
    module for parsing XML. If ``use_lxml`` argument is given a true value
    (see `Boolean arguments`), the library will use [http://lxml.de|lxml]
    module instead. See `Using lxml` section for benefits provided by lxml.

    Using lxml requires that the lxml module is installed on the system.
    If lxml mode is enabled but the module is not installed, this library
    will emit a warning and revert back to using the standard ElementTree.

Definition at line 476 of file XML.py.

Member Function Documentation

◆ _compare_elements()

def robot.libraries.XML.XML._compare_elements	(	self,
		source,
		expected,
		comparator,
		exclude_children,
		normalize_whitespace
	)

private

Definition at line 947 of file XML.py.

◆ _find_parent()

def robot.libraries.XML.XML._find_parent	(	self,
		root,
		element
	)

private

Definition at line 1230 of file XML.py.

◆ _normalize_whitespace()

def robot.libraries.XML.XML._normalize_whitespace	(	self,
		text
	)

private

Definition at line 705 of file XML.py.

◆ _preserve_tail()

def robot.libraries.XML.XML._preserve_tail	(	self,
		element,
		parent
	)

private

Definition at line 1237 of file XML.py.

◆ _raise_wrong_number_of_matches()

def robot.libraries.XML.XML._raise_wrong_number_of_matches	(	self,
		count,
		xpath,
		message = `None`
	)

private

Definition at line 565 of file XML.py.

◆ _remove_element()

def robot.libraries.XML.XML._remove_element	(	self,
		root,
		element,
		remove_tail = `False`
	)

private

Definition at line 1224 of file XML.py.

◆ _wrong_number_of_matches()

def robot.libraries.XML.XML._wrong_number_of_matches	(	self,
		count,
		xpath
	)

private

Definition at line 570 of file XML.py.

◆ _yield_texts()

def robot.libraries.XML.XML._yield_texts	(	self,
		element,
		top = `True`
	)

private

Definition at line 696 of file XML.py.

◆ add_element()

def robot.libraries.XML.XML.add_element	(	self,
		source,
		element,
		index = `None`,
		xpath = `'.'`
	)

Adds a child element to the specified element.

    The element to whom to add the new element is specified using ``source``
    and ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    The ``element`` to add can be specified as a path to an XML file or
    as a string containing XML, or it can be an already parsed XML element.
    The element is copied before adding so modifying either the original
    or the added element has no effect on the other
    .
    The element is added as the last child by default, but a custom index
    can be used to alter the position. Indices start from zero (0 = first
    position, 1 = second position, etc.), and negative numbers refer to
    positions at the end (-1 = second last position, -2 = third last, etc.).

    Examples using ``${XML}`` structure from `Example`:
    | Add Element | ${XML} | <new id="x"><c1/></new> |
    | Add Element | ${XML} | <c2/> | xpath=new |
    | Add Element | ${XML} | <c3/> | index=1 | xpath=new |
    | ${new} = | Get Element | ${XML} | new |
    | Elements Should Be Equal | ${new} | <new id="x"><c1/><c3/><c2/></new> |

    Use `Remove Element` or `Remove Elements` to remove elements.

Definition at line 1164 of file XML.py.

◆ clear_element()

def robot.libraries.XML.XML.clear_element	(	self,
		source,
		xpath = `'.'`,
		clear_tail = `False`
	)

Clears the contents of the specified element.

    The element to clear is specified using ``source`` and ``xpath``. They
    have exactly the same semantics as with `Get Element` keyword.
    The resulting XML structure is returned, and if the ``source`` is
    an already parsed XML structure, it is also modified in place.

    Clearing the element means removing its text, attributes, and children.
    Element's tail text is not removed by default, but that can be changed
    by giving ``clear_tail`` a true value (see `Boolean arguments`). See
    `Element attributes` section for more information about tail in
    general.

    Examples using ``${XML}`` structure from `Example`:
    | Clear Element            | ${XML}   | xpath=first |
    | ${first} = | Get Element | ${XML}   | xpath=first |
    | Elements Should Be Equal | ${first} | <first/>    |
    | Clear Element            | ${XML}   | xpath=html/p/b | clear_tail=yes |
    | Element Text Should Be   | ${XML}   | Text with italics. | xpath=html/p | normalize_whitespace=yes |
    | Clear Element            | ${XML}   |
    | Elements Should Be Equal | ${XML}   | <example/> |

    Use `Remove Element` to remove the whole element.

Definition at line 1271 of file XML.py.

◆ copy_element()

def robot.libraries.XML.XML.copy_element	(	self,
		source,
		xpath = `'.'`
	)

Returns a copy of the specified element.

    The element to copy is specified using ``source`` and ``xpath``. They
    have exactly the same semantics as with `Get Element` keyword.

    If the copy or the original element is modified afterwards, the changes
    have no effect on the other.

    Examples using ``${XML}`` structure from `Example`:
    | ${elem} =  | Get Element  | ${XML}  | xpath=first |
    | ${copy1} = | Copy Element | ${elem} |
    | ${copy2} = | Copy Element | ${XML}  | xpath=first |
    | Set Element Text         | ${XML}   | new text    | xpath=first      |
    | Set Element Attribute    | ${copy1} | id          | new              |
    | Elements Should Be Equal | ${elem}  | <first id="1">new text</first> |
    | Elements Should Be Equal | ${copy1} | <first id="new">text</first>   |
    | Elements Should Be Equal | ${copy2} | <first id="1">text</first>     |

Definition at line 1298 of file XML.py.

◆ element_attribute_should_be()

def robot.libraries.XML.XML.element_attribute_should_be	(	self,
		source,
		name,
		expected,
		xpath = `'.'`,
		message = `None`
	)

Verifies that the specified attribute is expected.

    The element whose attribute is verified is specified using ``source``
    and ``xpath``. They have exactly the same semantics as with
    `Get Element` keyword.

    The keyword passes if the attribute ``name`` of the element is equal to
    the ``expected`` value, and otherwise it fails. The default error
    message can be overridden with the ``message`` argument.

    To test that the element does not have a certain attribute, Python
    ``None`` (i.e. variable ``${NONE}``) can be used as the expected value.
    A cleaner alternative is using `Element Should Not Have Attribute`.

    Examples using ``${XML}`` structure from `Example`:
    | Element Attribute Should Be | ${XML} | id | 1       | xpath=first |
    | Element Attribute Should Be | ${XML} | id | ${NONE} |             |

    See also `Element Attribute Should Match` and `Get Element Attribute`.

Definition at line 838 of file XML.py.

◆ element_attribute_should_match()

def robot.libraries.XML.XML.element_attribute_should_match	(	self,
		source,
		name,
		pattern,
		xpath = `'.'`,
		message = `None`
	)

Verifies that the specified attribute matches expected.

    This keyword works exactly like `Element Attribute Should Be` except
    that the expected value can be given as a pattern that the attribute of
    the element must match.

    Pattern matching is similar as matching files in a shell with
    ``*``, ``?`` and ``[chars]`` acting as wildcards. See the
    `Pattern matching` section for more information.

    Examples using ``${XML}`` structure from `Example`:
    | Element Attribute Should Match | ${XML} | id | ?   | xpath=first |
    | Element Attribute Should Match | ${XML} | id | c*d | xpath=third/second |

Definition at line 857 of file XML.py.

◆ element_should_exist()

def robot.libraries.XML.XML.element_should_exist	(	self,
		source,
		xpath = `'.'`,
		message = `None`
	)

Verifies that one or more element match the given xpath.

    Arguments ``source`` and ``xpath`` have exactly the same semantics as
    with `Get Elements` keyword. Keyword passes if the ``xpath`` matches
    one or more elements in the ``source``. The default error message can
    be overridden with the ``message`` argument.

    See also `Element Should Not Exist` as well as `Get Element Count`
    that this keyword uses internally.

Definition at line 639 of file XML.py.

◆ element_should_not_exist()

def robot.libraries.XML.XML.element_should_not_exist	(	self,
		source,
		xpath = `'.'`,
		message = `None`
	)

Verifies that no element match the given xpath.

    Arguments ``source`` and ``xpath`` have exactly the same semantics as
    with `Get Elements` keyword. Keyword fails if the ``xpath`` matches any
    element in the ``source``. The default error message can be overridden
    with the ``message`` argument.

    See also `Element Should Exist` as well as `Get Element Count`
    that this keyword uses internally.

Definition at line 654 of file XML.py.

◆ element_should_not_have_attribute()

def robot.libraries.XML.XML.element_should_not_have_attribute	(	self,
		source,
		name,
		xpath = `'.'`,
		message = `None`
	)

Verifies that the specified element does not have attribute name.

    The element whose attribute is verified is specified using ``source``
    and ``xpath``. They have exactly the same semantics as with
    `Get Element` keyword.

    The keyword fails if the specified element has attribute ``name``. The
    default error message can be overridden with the ``message`` argument.

    Examples using ``${XML}`` structure from `Example`:
    | Element Should Not Have Attribute | ${XML} | id  |
    | Element Should Not Have Attribute | ${XML} | xxx | xpath=first |

    See also `Get Element Attribute`, `Get Element Attributes`,
    `Element Text Should Be` and `Element Text Should Match`.

Definition at line 880 of file XML.py.

◆ element_text_should_be()

def robot.libraries.XML.XML.element_text_should_be	(	self,
		source,
		expected,
		xpath = `'.'`,
		normalize_whitespace = `False`,
		message = `None`
	)

Verifies that the text of the specified element is expected.

    The element whose text is verified is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    The text to verify is got from the specified element using the same
    logic as with `Get Element Text`. This includes optional whitespace
    normalization using the ``normalize_whitespace`` option.

    The keyword passes if the text of the element is equal to the
    ``expected`` value, and otherwise it fails. The default error message
    can be overridden with the ``message`` argument.  Use `Element Text
    Should Match` to verify the text against a pattern instead of an exact
    value.

    Examples using ``${XML}`` structure from `Example`:
    | Element Text Should Be | ${XML}       | text     | xpath=first      |
    | Element Text Should Be | ${XML}       | ${EMPTY} | xpath=second/child |
    | ${paragraph} =         | Get Element  | ${XML}   | xpath=html/p     |
    | Element Text Should Be | ${paragraph} | Text with bold and italics. | normalize_whitespace=yes |

Definition at line 750 of file XML.py.

◆ element_text_should_match()

def robot.libraries.XML.XML.element_text_should_match	(	self,
		source,
		pattern,
		xpath = `'.'`,
		normalize_whitespace = `False`,
		message = `None`
	)

Verifies that the text of the specified element matches expected.

    This keyword works exactly like `Element Text Should Be` except that
    the expected value can be given as a pattern that the text of the
    element must match.

    Pattern matching is similar as matching files in a shell with
    ``*``, ``?`` and ``[chars]`` acting as wildcards. See the
    `Pattern matching` section for more information.

    Examples using ``${XML}`` structure from `Example`:
    | Element Text Should Match | ${XML}       | t???   | xpath=first  |
    | ${paragraph} =            | Get Element  | ${XML} | xpath=html/p |
    | Element Text Should Match | ${paragraph} | Text with * and *. | normalize_whitespace=yes |

Definition at line 770 of file XML.py.

◆ element_to_string()

def robot.libraries.XML.XML.element_to_string	(	self,
		source,
		xpath = `'.'`,
		encoding = `None`
	)

Returns the string representation of the specified element.

    The element to convert to a string is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    By default the string is returned as Unicode. If ``encoding`` argument
    is given any value, the string is returned as bytes in the specified
    encoding. The resulting string never contains the XML declaration.

    See also `Log Element` and `Save XML`.

Definition at line 1313 of file XML.py.

◆ elements_should_be_equal()

def robot.libraries.XML.XML.elements_should_be_equal	(	self,
		source,
		expected,
		exclude_children = `False`,
		normalize_whitespace = `False`
	)

Verifies that the given source element is equal to expected.

    Both ``source`` and ``expected`` can be given as a path to an XML file,
    as a string containing XML, or as an already parsed XML element
    structure. See `introduction` for more information about parsing XML in
    general.

    The keyword passes if the ``source`` element and ``expected`` element
    are equal. This includes testing the tag names, texts, and attributes
    of the elements. By default also child elements are verified the same
    way, but this can be disabled by setting ``exclude_children`` to a
    true value (see `Boolean arguments`).

    All texts inside the given elements are verified, but possible text
    outside them is not. By default texts must match exactly, but setting
    ``normalize_whitespace`` to a true value makes text verification
    independent on newlines, tabs, and the amount of spaces. For more
    details about handling text see `Get Element Text` keyword and
    discussion about elements' `text` and `tail` attributes in the
    `introduction`.

    Examples using ``${XML}`` structure from `Example`:
    | ${first} =               | Get Element | ${XML} | first             |
    | Elements Should Be Equal | ${first}    | <first id="1">text</first> |
    | ${p} =                   | Get Element | ${XML} | html/p            |
    | Elements Should Be Equal | ${p} | <p>Text with <b>bold</b> and <i>italics</i>.</p> | normalize_whitespace=yes |
    | Elements Should Be Equal | ${p} | <p>Text with</p> | exclude | normalize |

    The last example may look a bit strange because the ``<p>`` element
    only has text ``Text with``. The reason is that rest of the text
    inside ``<p>`` actually belongs to the child elements. This includes
    the ``.`` at the end that is the `tail` text of the ``<i>`` element.

    See also `Elements Should Match`.

Definition at line 921 of file XML.py.

◆ elements_should_match()

def robot.libraries.XML.XML.elements_should_match	(	self,
		source,
		expected,
		exclude_children = `False`,
		normalize_whitespace = `False`
	)

Verifies that the given source element matches expected.

    This keyword works exactly like `Elements Should Be Equal` except that
    texts and attribute values in the expected value can be given as
    patterns.

    Pattern matching is similar as matching files in a shell with
    ``*``, ``?`` and ``[chars]`` acting as wildcards. See the
    `Pattern matching` section for more information.

    Examples using ``${XML}`` structure from `Example`:
    | ${first} =            | Get Element | ${XML} | first          |
    | Elements Should Match | ${first}    | <first id="?">*</first> |

    See `Elements Should Be Equal` for more examples.

Definition at line 942 of file XML.py.

◆ evaluate_xpath()

def robot.libraries.XML.XML.evaluate_xpath	(	self,
		source,
		expression,
		context = `'.'`
	)

Evaluates the given xpath expression and returns results.

    The element in which context the expression is executed is specified
    using ``source`` and ``context`` arguments. They have exactly the same
    semantics as ``source`` and ``xpath`` arguments have with `Get Element`
    keyword.

    The xpath expression to evaluate is given as ``expression`` argument.
    The result of the evaluation is returned as-is.

    Examples using ``${XML}`` structure from `Example`:
    | ${count} =      | Evaluate Xpath | ${XML}  | count(third/*) |
    | Should Be Equal | ${count}       | ${3}    |
    | ${text} =       | Evaluate Xpath | ${XML}  | string(descendant::second[last()]/@id) |
    | Should Be Equal | ${text}        | child   |
    | ${bold} =       | Evaluate Xpath | ${XML}  | boolean(preceding-sibling::*[1] = 'bold') | context=html/p/i |
    | Should Be Equal | ${bold}        | ${True} |

    This keyword works only if lxml mode is taken into use when `importing`
    the library.

Definition at line 1396 of file XML.py.

◆ get_child_elements()

def robot.libraries.XML.XML.get_child_elements	(	self,
		source,
		xpath = `'.'`
	)

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

    The element whose children to return is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    All the direct child elements of the specified element are returned.
    If the element has no children, an empty list is returned.

    Examples using ``${XML}`` structure from `Example`:
    | ${children} =    | Get Child Elements | ${XML} |             |
    | Length Should Be | ${children}        | 4      |             |
    | ${children} =    | Get Child Elements | ${XML} | xpath=first |
    | Should Be Empty  | ${children}        |        |             |

Definition at line 614 of file XML.py.

◆ get_element()

def robot.libraries.XML.XML.get_element	(	self,
		source,
		xpath = `'.'`
	)

Returns an element in the source matching the xpath.

    The ``source`` can be a path to an XML file, a string containing XML, or
    an already parsed XML element. The ``xpath`` specifies which element to
    find. See the `introduction` for more details about both the possible
    sources and the supported xpath syntax.

    The keyword fails if more, or less, than one element matches the
    ``xpath``. Use `Get Elements` if you want all matching elements to be
    returned.

    Examples using ``${XML}`` structure from `Example`:
    | ${element} = | Get Element | ${XML}     | second |
    | ${child} =   | Get Element | ${element} | child  |

    `Parse XML` is recommended for parsing XML when the whole structure
    is needed. It must be used if there is a need to configure how XML
    namespaces are handled.

    Many other keywords use this keyword internally, and keywords modifying
    XML are typically documented to both to modify the given source and
    to return it. Modifying the source does not apply if the source is
    given as a string. The XML structure parsed based on the string and
    then modified is nevertheless returned.

Definition at line 559 of file XML.py.

◆ get_element_attribute()

def robot.libraries.XML.XML.get_element_attribute	(	self,
		source,
		name,
		xpath = `'.'`,
		default = `None`
	)

Returns the named attribute of the specified element.

    The element whose attribute to return is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    The value of the attribute ``name`` of the specified element is returned.
    If the element does not have such element, the ``default`` value is
    returned instead.

    Examples using ``${XML}`` structure from `Example`:
    | ${attribute} =  | Get Element Attribute | ${XML} | id | xpath=first |
    | Should Be Equal | ${attribute}          | 1      |    |             |
    | ${attribute} =  | Get Element Attribute | ${XML} | xx | xpath=first | default=value |
    | Should Be Equal | ${attribute}          | value  |    |             |

    See also `Get Element Attributes`, `Element Attribute Should Be`,
    `Element Attribute Should Match` and `Element Should Not Have Attribute`.

Definition at line 795 of file XML.py.

◆ get_element_attributes()

def robot.libraries.XML.XML.get_element_attributes	(	self,
		source,
		xpath = `'.'`
	)

Returns all attributes of the specified element.

    The element whose attributes to return is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    Attributes are returned as a Python dictionary. It is a copy of the
    original attributes so modifying it has no effect on the XML structure.

    Examples using ``${XML}`` structure from `Example`:
    | ${attributes} = | Get Element Attributes      | ${XML} | first |
    | Dictionary Should Contain Key | ${attributes} | id     |       |
    | ${attributes} = | Get Element Attributes      | ${XML} | third |
    | Should Be Empty | ${attributes}               |        |       |

    Use `Get Element Attribute` to get the value of a single attribute.

Definition at line 815 of file XML.py.

◆ get_element_count()

def robot.libraries.XML.XML.get_element_count	(	self,
		source,
		xpath = `'.'`
	)

Returns and logs how many elements the given xpath matches.

    Arguments ``source`` and ``xpath`` have exactly the same semantics as
    with `Get Elements` keyword that this keyword uses internally.

    See also `Element Should Exist` and `Element Should Not Exist`.

Definition at line 624 of file XML.py.

◆ get_element_text()

def robot.libraries.XML.XML.get_element_text	(	self,
		source,
		xpath = `'.'`,
		normalize_whitespace = `False`
	)

Returns all text of the element, possibly whitespace normalized.

    The element whose text to return is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword.

    This keyword returns all the text of the specified element, including
    all the text its children and grandchildren contain. If the element
    has no text, an empty string is returned. The returned text is thus not
    always the same as the `text` attribute of the element.

    By default all whitespace, including newlines and indentation, inside
    the element is returned as-is. If ``normalize_whitespace`` is given
    a true value (see `Boolean arguments`), then leading and trailing
    whitespace is stripped, newlines and tabs converted to spaces, and
    multiple spaces collapsed into one. This is especially useful when
    dealing with HTML data.

    Examples using ``${XML}`` structure from `Example`:
    | ${text} =       | Get Element Text | ${XML}       | first        |
    | Should Be Equal | ${text}          | text         |              |
    | ${text} =       | Get Element Text | ${XML}       | second/child |
    | Should Be Empty | ${text}          |              |              |
    | ${paragraph} =  | Get Element      | ${XML}       | html/p       |
    | ${text} =       | Get Element Text | ${paragraph} | normalize_whitespace=yes |
    | Should Be Equal | ${text}          | Text with bold and italics. |

    See also `Get Elements Texts`, `Element Text Should Be` and
    `Element Text Should Match`.

Definition at line 689 of file XML.py.

◆ get_elements()

def robot.libraries.XML.XML.get_elements	(	self,
		source,
		xpath
	)

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

    The ``source`` can be a path to an XML file, a string containing XML, or
    an already parsed XML element. The ``xpath`` specifies which element to
    find. See the `introduction` for more details.

    Elements matching the ``xpath`` are returned as a list. If no elements
    match, an empty list is returned. Use `Get Element` if you want to get
    exactly one match.

    Examples using ``${XML}`` structure from `Example`:
    | ${children} =    | Get Elements | ${XML} | third/child |
    | Length Should Be | ${children}  | 2      |             |
    | ${children} =    | Get Elements | ${XML} | first/child |
    | Should Be Empty  |  ${children} |        |             |

Definition at line 593 of file XML.py.

◆ get_elements_texts()

def robot.libraries.XML.XML.get_elements_texts	(	self,
		source,
		xpath,
		normalize_whitespace = `False`
	)

Returns text of all elements matching xpath as a list.

    The elements whose text to return is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Elements`
    keyword.

    The text of the matched elements is returned using the same logic
    as with `Get Element Text`. This includes optional whitespace
    normalization using the ``normalize_whitespace`` option.

    Examples using ``${XML}`` structure from `Example`:
    | @{texts} =       | Get Elements Texts | ${XML}    | third/child |
    | Length Should Be | ${texts}           | 2         |             |
    | Should Be Equal  | @{texts}[0]        | more text |             |
    | Should Be Equal  | @{texts}[1]        | ${EMPTY}  |             |

Definition at line 724 of file XML.py.

◆ log_element()

def robot.libraries.XML.XML.log_element	(	self,
		source,
		level = `'INFO'`,
		xpath = `'.'`
	)

Logs the string representation of the specified element.

    The element specified with ``source`` and ``xpath`` is first converted
    into a string using `Element To String` keyword internally. The
    resulting string is then logged using the given ``level``.

    The logged string is also returned.

Definition at line 1329 of file XML.py.

◆ parse_xml()

def robot.libraries.XML.XML.parse_xml	(	self,
		source,
		keep_clark_notation = `False`,
		strip_namespaces = `False`
	)

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

    The ``source`` can either be a path to an XML file or a string
    containing XML. In both cases the XML is parsed into ElementTree
    [http://docs.python.org/library/xml.etree.elementtree.html#element-objects|element structure]
    and the root element is returned. Possible comments and processing
    instructions in the source XML are removed.

    As discussed in `Handling XML namespaces` section, this keyword, by
    default, removes namespace information ElementTree has added to tag
    names and moves it into ``xmlns`` attributes. This typically eases
    handling XML documents with namespaces considerably. If you do not
    want that to happen, or want to avoid the small overhead of going
    through the element structure when your XML does not have namespaces,
    you can disable this feature by giving ``keep_clark_notation`` argument
    a true value (see `Boolean arguments`).

    If you want to strip namespace information altogether so that it is
    not included even if XML is saved, you can give a true value to
    ``strip_namespaces`` argument.

    Examples:
    | ${root} = | Parse XML | <root><child/></root> |
    | ${xml} = | Parse XML | ${CURDIR}/test.xml | keep_clark_notation=True |
    | ${xml} = | Parse XML | ${CURDIR}/test.xml | strip_namespaces=True |

    Use `Get Element` keyword if you want to get a certain element and not
    the whole structure. See `Parsing XML` section for more details and
    examples.

Definition at line 521 of file XML.py.

◆ remove_element()

def robot.libraries.XML.XML.remove_element	(	self,
		source,
		xpath = `''`,
		remove_tail = `False`
	)

Removes the element matching xpath from the source structure.

    The element to remove from the ``source`` is specified with ``xpath``
    using the same semantics as with `Get Element` keyword. The resulting
    XML structure is returned, and if the ``source`` is an already parsed
    XML structure, it is also modified in place.

    The keyword fails if ``xpath`` does not match exactly one element.
    Use `Remove Elements` to remove all matched elements.

    Element's tail text is not removed by default, but that can be changed
    by giving ``remove_tail`` a true value (see `Boolean arguments`). See
    `Element attributes` section for more information about `tail` in
    general.

    Examples using ``${XML}`` structure from `Example`:
    | Remove Element           | ${XML} | xpath=second |
    | Element Should Not Exist | ${XML} | xpath=second |
    | Remove Element           | ${XML} | xpath=html/p/b | remove_tail=yes |
    | Element Text Should Be   | ${XML} | Text with italics. | xpath=html/p | normalize_whitespace=yes |

Definition at line 1195 of file XML.py.

◆ remove_element_attribute()

def robot.libraries.XML.XML.remove_element_attribute	(	self,
		source,
		name,
		xpath = `'.'`
	)

Removes attribute name from the specified element.

    The element whose attribute to remove is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    It is not a failure to remove a non-existing attribute. Use `Remove
    Element Attributes` to remove all attributes and `Set Element Attribute`
    to set them.

    Examples using ``${XML}`` structure from `Example`:
    | Remove Element Attribute          | ${XML} | id | xpath=first |
    | Element Should Not Have Attribute | ${XML} | id | xpath=first |

    Can only remove an attribute from a single element. Use `Remove Elements
    Attribute` to remove an attribute of multiple elements in one call.

Definition at line 1087 of file XML.py.

◆ remove_element_attributes()

def robot.libraries.XML.XML.remove_element_attributes	(	self,
		source,
		xpath = `'.'`
	)

Removes all attributes from the specified element.

    The element whose attributes to remove is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    Use `Remove Element Attribute` to remove a single attribute and
    `Set Element Attribute` to set them.

    Examples using ``${XML}`` structure from `Example`:
    | Remove Element Attributes         | ${XML} | xpath=first |
    | Element Should Not Have Attribute | ${XML} | id | xpath=first |

    Can only remove attributes from a single element. Use `Remove Elements
    Attributes` to remove all attributes of multiple elements in one call.

Definition at line 1122 of file XML.py.

◆ remove_elements()

def robot.libraries.XML.XML.remove_elements	(	self,
		source,
		xpath = `''`,
		remove_tail = `False`
	)

Removes all elements matching xpath from the source structure.

    The elements to remove from the ``source`` are specified with ``xpath``
    using the same semantics as with `Get Elements` keyword. The resulting
    XML structure is returned, and if the ``source`` is an already parsed
    XML structure, it is also modified in place.

    It is not a failure if ``xpath`` matches no elements. Use `Remove
    Element` to remove exactly one element.

    Element's tail text is not removed by default, but that can be changed
    by using ``remove_tail`` argument similarly as with `Remove Element`.

    Examples using ``${XML}`` structure from `Example`:
    | Remove Elements          | ${XML} | xpath=*/child      |
    | Element Should Not Exist | ${XML} | xpath=second/child |
    | Element Should Not Exist | ${XML} | xpath=third/child  |

Definition at line 1218 of file XML.py.

◆ remove_elements_attribute()

def robot.libraries.XML.XML.remove_elements_attribute	(	self,
		source,
		name,
		xpath = `'.'`
	)

Removes attribute name from the specified elements.

    Like `Remove Element Attribute` but removes the attribute of all
    elements matching the given ``xpath``.

Definition at line 1099 of file XML.py.

◆ remove_elements_attributes()

def robot.libraries.XML.XML.remove_elements_attributes	(	self,
		source,
		xpath = `'.'`
	)

Removes all attributes from the specified elements.

    Like `Remove Element Attributes` but removes all attributes of all
    elements matching the given ``xpath``.

Definition at line 1132 of file XML.py.

◆ save_xml()

def robot.libraries.XML.XML.save_xml	(	self,
		source,
		path,
		encoding = `'UTF-8'`
	)

Saves the given element to the specified file.

    The element to save is specified with ``source`` using the same
    semantics as with `Get Element` keyword.

    The file where the element is saved is denoted with ``path`` and the
    encoding to use with ``encoding``. The resulting file always contains
    the XML declaration.

    The resulting XML file may not be exactly the same as the original:
    - Comments and processing instructions are always stripped.
    - Possible doctype and namespace prefixes are only preserved when
      `using lxml`.
    - Other small differences are possible depending on the ElementTree
      or lxml version.

    Use `Element To String` if you just need a string representation of
    the element.

Definition at line 1353 of file XML.py.

◆ set_element_attribute()

def robot.libraries.XML.XML.set_element_attribute	(	self,
		source,
		name,
		value,
		xpath = `'.'`
	)

Sets attribute name of the specified element to value.

    The element whose attribute to set is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    It is possible to both set new attributes and to overwrite existing.
    Use `Remove Element Attribute` or `Remove Element Attributes` for
    removing them.

    Examples using ``${XML}`` structure from `Example`:
    | Set Element Attribute       | ${XML} | attr | value |
    | Element Attribute Should Be | ${XML} | attr | value |
    | Set Element Attribute       | ${XML} | id   | new   | xpath=first |
    | Element Attribute Should Be | ${XML} | id   | new   | xpath=first |

    Can only set an attribute of a single element. Use `Set Elements
    Attribute` to set an attribute of multiple elements in one call.

Definition at line 1051 of file XML.py.

◆ set_element_tag()

def robot.libraries.XML.XML.set_element_tag	(	self,
		source,
		tag,
		xpath = `'.'`
	)

Sets the tag of the specified element.

    The element whose tag to set is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    Examples using ``${XML}`` structure from `Example`:
    | Set Element Tag      | ${XML}     | newTag     |
    | Should Be Equal      | ${XML.tag} | newTag     |
    | Set Element Tag      | ${XML}     | xxx        | xpath=second/child |
    | Element Should Exist | ${XML}     | second/xxx |
    | Element Should Not Exist | ${XML} | second/child |

    Can only set the tag of a single element. Use `Set Elements Tag` to set
    the tag of multiple elements in one call.

Definition at line 971 of file XML.py.

◆ set_element_text()

def robot.libraries.XML.XML.set_element_text	(	self,
		source,
		text = `None`,
		tail = `None`,
		xpath = `'.'`
	)

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

    The element whose text to set is specified using ``source`` and
    ``xpath``. They have exactly the same semantics as with `Get Element`
    keyword. The resulting XML structure is returned, and if the ``source``
    is an already parsed XML structure, it is also modified in place.

    Element's text and tail text are changed only if new ``text`` and/or
    ``tail`` values are given. See `Element attributes` section for more
    information about `text` and `tail` in general.

    Examples using ``${XML}`` structure from `Example`:
    | Set Element Text       | ${XML} | new text | xpath=first    |
    | Element Text Should Be | ${XML} | new text | xpath=first    |
    | Set Element Text       | ${XML} | tail=&   | xpath=html/p/b |
    | Element Text Should Be | ${XML} | Text with bold&italics. | xpath=html/p  | normalize_whitespace=yes |
    | Set Element Text       | ${XML} | slanted  | !! | xpath=html/p/i |
    | Element Text Should Be | ${XML} | Text with bold&slanted!! | xpath=html/p  | normalize_whitespace=yes |

    Can only set the text/tail of a single element. Use `Set Elements Text`
    to set the text/tail of multiple elements in one call.

Definition at line 1010 of file XML.py.

◆ set_elements_attribute()

def robot.libraries.XML.XML.set_elements_attribute	(	self,
		source,
		name,
		value,
		xpath = `'.'`
	)

Sets attribute name of the specified elements to value.

    Like `Set Element Attribute` but sets the attribute of all elements
    matching the given ``xpath``.

Definition at line 1063 of file XML.py.

◆ set_elements_tag()

def robot.libraries.XML.XML.set_elements_tag	(	self,
		source,
		tag,
		xpath = `'.'`
	)

Sets the tag of the specified elements.

    Like `Set Element Tag` but sets the tag of all elements matching
    the given ``xpath``.

Definition at line 981 of file XML.py.

◆ set_elements_text()

def robot.libraries.XML.XML.set_elements_text	(	self,
		source,
		text = `None`,
		tail = `None`,
		xpath = `'.'`
	)

Sets text and/or tail text of the specified elements.

    Like `Set Element Text` but sets the text or tail of all elements
    matching the given ``xpath``.

Definition at line 1025 of file XML.py.

Member Data Documentation

◆ _ns_stripper

robot.libraries.XML.XML._ns_stripper

private

Definition at line 489 of file XML.py.

◆ _xml_declaration

robot.libraries.XML.XML._xml_declaration

staticprivate

Definition at line 462 of file XML.py.

◆ etree

robot.libraries.XML.XML.etree

Definition at line 479 of file XML.py.

◆ lxml_etree

robot.libraries.XML.XML.lxml_etree

Definition at line 481 of file XML.py.

◆ modern_etree

robot.libraries.XML.XML.modern_etree

Definition at line 480 of file XML.py.

◆ ROBOT_LIBRARY_SCOPE

string robot.libraries.XML.XML.ROBOT_LIBRARY_SCOPE = 'GLOBAL'

static

Definition at line 457 of file XML.py.

◆ ROBOT_LIBRARY_VERSION

robot.libraries.XML.XML.ROBOT_LIBRARY_VERSION = get_version()

static

Definition at line 458 of file XML.py.

The documentation for this class was generated from the following file:

src/robot/libraries/XML.py

Public Member Functions

Public Attributes

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ _compare_elements()

◆ _find_parent()

◆ _normalize_whitespace()

◆ _preserve_tail()

◆ _raise_wrong_number_of_matches()

◆ _remove_element()

◆ _wrong_number_of_matches()

◆ _yield_texts()

◆ add_element()

◆ clear_element()

◆ copy_element()

◆ element_attribute_should_be()

◆ element_attribute_should_match()

◆ element_should_exist()

◆ element_should_not_exist()

◆ element_should_not_have_attribute()

◆ element_text_should_be()

◆ element_text_should_match()

◆ element_to_string()

◆ elements_should_be_equal()

◆ elements_should_match()

◆ evaluate_xpath()

◆ get_child_elements()

◆ get_element()

◆ get_element_attribute()

◆ get_element_attributes()

◆ get_element_count()

◆ get_element_text()

◆ get_elements()

◆ get_elements_texts()

◆ log_element()

◆ parse_xml()

◆ remove_element()

◆ remove_element_attribute()

◆ remove_element_attributes()

◆ remove_elements()

◆ remove_elements_attribute()

◆ remove_elements_attributes()

◆ save_xml()

◆ set_element_attribute()

◆ set_element_tag()

◆ set_element_text()

◆ set_elements_attribute()

◆ set_elements_tag()

◆ set_elements_text()

Member Data Documentation

◆ _ns_stripper

◆ _xml_declaration

◆ etree

◆ lxml_etree

◆ modern_etree

◆ ROBOT_LIBRARY_SCOPE

◆ ROBOT_LIBRARY_VERSION

◆ init()