XMLElement Object

Description

An object representing an XML element.

IMPORTANT

An XMLElement object must have an opening and closing tag. An XMLElement may have attributes, a value, and/or one or more children, all of type XMLElement. If an XMLElement object has a value, its node's value must include all of its character data, including CDATA sections.

An XMLElement object can be accessed using one of the following methods or properties:

Methods and Properties

Method AddAttributeAdds a new XMLAttribute item with the specified name and value to the element.
Method AddCDATASectionAdds a CDATA section to the XMLElement.
AddChildElementCopies the specified XMLElement object, adds it as a child element, and returns the new child object.
AddChildElementByNameAdds a child element initialized with a tag and a value.
AddCommentAdds a comment to the element.
AddNamespaceAdds the specified namespace to the namespace collection used by the XMLElement object.
AttributesReturns the all of the attributes in the element in an attribute collection.
CDATASectionsReturns the element's CDATA sections as a collection.
CheckAttributeCompares the actual attribute value of the specified XML attribute (of the current XML Element) to a specified value.
CheckValueCompares the actual value of the XML element to a specified value.
CheckXMLPathValueCompares the actual value of the XML element (specified by XPath) to a specified value.
ChildElementsByPathReturns all of the child elements that reside in the specified path.
ClearClears selected elements from the XML.
CommentsReturns the element's comments in a collection.
ElementNameReturns the element object's tag name.
GetNumDescendantElemByNameReturns the quantity of the element's descendants that have the specified name.
GetValueByXPathReturns the value of the first child node that matches the specified XPath.
NamespaceReturns the element's namespace.
NextSiblingReturns the next sibling element in the XML document.
ParentReturns the XMLElement's parent element.
RemoveAttributeRemoves the specified attribute from the XMLElement.
RemoveCDATASectionRemoves the specified CDATA section from the XMLElement.
RemoveChildElementRemoves the specified ChildElement from the XMLElement.
RemoveCommentRemoves the specified comment section from the XMLElement.
RootElementReturns the root element of the element's document.
SetValueSets a new value (character data) for the XMLElement.
ToStringReturns the inner XML of the element.
ValueReturns the element's value (character data, including the CData section).

Back to top

AddAttribute Method

Description

Adds a new XMLAttribute item with the specified name and value to the element.

Note: If an attribute with the specified name already exists, its value is overwritten with the specified value.

Syntax

XMLElement.AddAttribute (Name,Value)

Argument

Type

Description

Name

String

The attribute name.

Value

String

The attribute value.

Return Value

XMLAttribute Object

Back to top

AddCDATASection Method

Description

Adds a CDATA section to the XMLElement.

Syntax

XMLElement.AddCDATASection CDataSectionString

Argument

Type

Description

CDataSectionString

String

The CDATA section to add.

Back to top

AddChildElement Method

Description

Copies the specified XMLElement object, adds it as a child element, and returns the new child object.

Syntax

XMLElement.AddChildElement ChildXMLElement

Argument

Type

Description

ChildXMLElement

XMLElement

The object representing the child XML element to add.

Return Value

XMLElement Object

Back to top

AddChildElementByName Method

Adds a child element initialized with a tag and a value.

Description

Adds a child element initialized with a tag and a value.

Syntax

XMLElement.AddChildElementByName (Tag, Value)

Argument

Type

Description

Tag

String

The element tag name.

Value

String

The element value.

Return Value

None

Back to top

AddChildElementByName Method

Description

Adds a comment to the element.

Syntax

XMLElement.AddComment CommentString

Argument

Type

Description

CommentString

String

The comment to add.

Back to top

AddChildElementByName Method

Description

Adds the specified namespace to the namespace collection used by the XMLElement object.

Syntax

XMLElement.AddNamespace Prefix, URI

Argument

Type

Description

Prefix

String

The prefix to associate with the namespace you are adding

URI

String

The namespace to add.

IMPORTANT

After using this method to add a namespace, you must add the namespace prefix to any XPATH expressions used in subsequent steps. If an XPATH expression does not include a prefix, the namespace URI (uniform resource identifier) will be an empty namespace (and not the default namespace).

Back to top

Attributes Property

Description

Returns the all of the attributes in the element in an attribute collection.

Syntax

XMLElement.Attributes

Return Value

XMLAttributesColl Object

IMPORTANT

The returned item collection is a copy of the collection of the element's attributes. Therefore, any changes you make to the element's attributes after retrieving the collection (such as adding or removing an attributes) will not be included. For example, if you use the Count property on the returned item collection, the returned value will be the same before and after adding or removing CDATA sections to or from the actual XML document. To ensure that the collection is up-to-date after changes are made, use the CDATASections property again to retrieve the updated collection.

Back to top

CDATASections Property

Description

Returns the element's CDATA sections as a collection.

Syntax

XMLElement.CDATASections

Return Value

XMLItemColl Object

IMPORTANT

The returned item collection is a copy of the collection of the element's CDATA sections. Therefore, any changes you make to the element's CDATA section after retrieving the collection (such as adding or removing a CDATA section) will not be included. For example, if you use the Count property on the returned item collection, the returned value will be the same before and after adding or removing CDATA sections to or from the actual XML document. To ensure that the collection is up-to-date after changes are made, use the CDATASections property again to retrieve the updated collection.

Back to top

CheckAttribute Method

Description

Compares the actual attribute value of the specified XML attribute (of the current XML Element) to a specified value. If the values do not match, the step fails.

Syntax

XMLElement.CheckAttribute (AttributeName,Value)

Argument

Type

Description

AttributeName

String

The name of the element attribute you want to check.

Value

Variant

The expected value of the attribute.

Return Value

Boolean. Returns TRUE if the values match, and FALSE if the values do not match.

A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.

Back to top

CheckValue Method

Description

Compares the actual value of the XML element to a specified value. If the values do not match, the step fails.

Syntax

XMLElement.CheckValue (Value)

Argument

Type

Description

Value

Variant

The expected value of the element.

Return Value

Boolean. Returns TRUE if the values match, and FALSE if the values do not match.

A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.

Back to top

CheckXMLPathValue Method

Description

Compares the actual value of the XML element (specified by XPath) to a specified value. If the values do not match, the step fails.

Syntax

XMLElement.CheckXPath (XPath,Value)

Argument

Type

Description

XPath

Variant

The XPath value of the element you want to check relative to the current element node.

To check the current element node, use "."

For more details on XPath standards, see the World Wide Web Consortium (W3C) website.

Value

Variant

The expected value of the element.

Return Value

Boolean. Returns TRUE if the values match, and FALSE if the values do not match.

A TRUE return value reports a Passed step to the run results; a FALSE return value reports a Failed step to the run results.

Back to top

ChildElements Property

Description

Returns a collection of XMLElement objects, representing the immediate child nodes of the element.

Syntax

XMLElement.ChildElements

Return Value

XMLElementsColl Object

IMPORTANT

The returned element collection is a copy of the collection of the document's child elements. Therefore, any changes you make to a document's elements after retrieving the collection (such as adding or removing an element) will not be included. For example, if you use the Count property on the returned item collection, the returned value will be the same before and after adding or removing CDATA sections to or from the actual XML document. To ensure that the collection is up-to-date after changes are made, use the ChildElements property again to retrieve the updated collection.

Back to top

ChildElementsByPath Property

Description

Returns all of the child elements that reside in the specified path.

Syntax

XMLElement.ChildElementsByPath (XPath)

Argument

Type

Description

XPath

String

The XPath value of the element you want to check relative to the current element node.

To check the current element node, use "."

For more details on XPath standards, see the World Wide Web Consortium (W3C) website.

Note: In QuickTest 8.2 and earlier, this method accepted only XML paths in the format /elem1/elem2/../elem3.

This format is a valid XPath format and can thus continue to be used. However, if your data contains namespaces, you must add them to any tests using this method. Otherwise, this step will fail.

Return Value

XMLElementsColl Object

IMPORTANT

The returned item collection is a copy of the collection of the selected child elements. Therefore, any changes you make to these child elements after retrieving the collection (such as adding or removing an element) will not be included. For example, if you use the Count property on the returned item collection, the returned value will be the same before and after adding or removing elements to or from the actual XML document. To ensure that the collection is up-to-date after changes are made, use the ChildElementsByPath property again to retrieve the updated collection.

Back to top

Clear Method

Description

You can choose to clear all or some of the following information from the XMLElement object: attributes, values, CDATA sections, and comments. This method does not affect the element's child elements.

Syntax

XMLElement.Clear(Filter)

Argument

Type

Description

Filter

Number or pre-defined constant

Optional. The XML information to be cleared:

1 or micXMLAttributes: Clears only the attributes of the specified XML document.

2 or micXMLCDataSections: Clears only the CDATA sections of the specified XML document.

4 or micXMLValues: Clears only the values of the specified XML document.

Note: If you do not use this parameter, the attributes, values, comments, and CDATA sections are all cleared.
You can specify more than one filter, separated by a plus (+) symbol. For example, micXMLValues+micXMLAttributes.

Back to top

Comments Property

Description

Returns the element's comments in a collection.

Syntax

XMLElement.Comments

Return Value

XMLItemColl Object

IMPORTANT

The returned item collection is a copy of the collection of document comments. Therefore, any changes you make to the document comments after retrieving the collection (such as adding or removing a comment) will not be included. For example, if you use the Count property on the returned item collection, the returned value will be the same before and after adding or removing comments to or from the actual XML document. To ensure that the collection is up-to-date after changes are made, use the Comments property again to retrieve the updated collection.

Back to top

ElementName Property

Description

Returns the element object's tag name.

Syntax

XMLElement.ElementName

Return Value

String

Back to top

GetNumDescendantElemByName Method

Description

Returns the quantity of the element's descendants that have the specified name.

Syntax

XMLElement.GetNumDescendantElemByName (Name)

Argument

Type

Description

Name

String

The name to find.

Return Value

Number

Back to top

GetValueByXPath Method

Description

Returns the value of the first child node that matches the specified XPath.

Syntax

XMLElement.GetValueByXPath (XPath)

Argument

Type

Description

XPath

String

The XPath value of the element whose value you want to return.

To check the current element node, use "."

For more details on XPath standards, see the World Wide Web Consortium (W3C) website.

Return Value

Number. The value of the element.

Back to top

Namespace Property

Description

Returns the element's namespace.

Syntax

XMLElement.Namespace

Return Value

String

Back to top

NextSibling Property

Description

Returns the next sibling element in the XML document.

Syntax

XMLElement.NextSibling

Return Value

XMLElement Object

Back to top

Parent Property

Description

Returns the XMLElement's parent element.

Syntax

XMLElement.Parent

Return Value

XMLElement Object

Back to top

RemoveAttribute Method

Description

Removes the specified attribute from the XMLElement.

Syntax

XMLElement.RemoveAttribute Name

Argument

Type

Description

Name

String

The attribute name.

Back to top

RemoveCDATASection Method

Description

Removes the specified CDATA section from the XMLElement.

Syntax

XMLElement.RemoveCDATASection CDataSectionString

Argument

Type

Description

CDataSectionString

String

The CDATA string to remove.

Back to top

RemoveChildElement Method

Description

Removes the specified ChildElement from the XMLElement.

Syntax

XMLElement.RemoveChildElement ChildElement

Argument

Type

Description

ChildElement

XMLElement

The name of the child element to remove.

Back to top

RemoveComment Method

Description

Removes the specified comment section from the XMLElement.

Syntax

XMLElement.RemoveComment CommentString

Argument

Type

Description

CommentString

String

The comment string to remove.

Back to top

RootElement Property

Description

Returns the root element of the element's document.

Syntax

XMLElement.RootElement

Return Value

XMLElement Object

Back to top

SetValue Method

Description

Sets a new value (character data) for the XMLElement.

Note: If the element already had a value, the new value replaces it.

Syntax

XMLElement.SetValue (ValueString)

Back to top

ToString Method

Description

Returns the inner XML of the element.

Syntax

XMLElement.ToString

Back to top

Value Property

Description

Returns the element's value (character data, including the CData section).

IMPORTANT

Prior to QuickTest Professional 9.0, this property did not return the CData section. You may need to update your steps to account for this change.

Syntax

XMLElement.Value

Return Value

String

Back to top