Share this page
Description
An object representing an XML block.
IMPORTANT
All XMLData objects, methods, and properties are compatible with the namespace and XPath standards.
Therefore, when including a namespace in an XPath value, ensure that the namespace is defined at the same level in which the XPath is evaluated.
For more details on XML, namespace, and XPath standards, see the World Wide Web Consortium (W3C) website.
This object can be accessed using one of the following methods:
Methods and Properties
 AddCDataSection | An object representing an XML block. |
| AddComment | Adds a comment to the XMLData document.. |
| AddNamespace | Adds the specified namespace to the namespace collection used by the XMLData object. |
 CDATASections | Returns the document's CDATA sections as a collection |
| Check | Executes a checkpoint on an XML object return value supplied by a Web service. |
| ChildElementsByPath | Returns all of the child elements that reside in the specified path. |
| Clone | Returns an exact copy of the XMLData object. |
| Comments | Returns the document comments in a collection. |
| Compare | Compares the specified XML document with the current XMLData object and creates a new XMLData object containing the differences. |
| CreateDocument | Creates a new, empty XML document with a specified root name. |
| GetRootElement | Returns an XMLElement object, representing the block's root element. |
| GetValidationError | Retrieves the description of the specified error from the most recent schema validation. |
| GetValidationErrorsNumber | Returns the total number of errors that occurred in the most recent schema validation. |
| GetVersion | Returns the XML version of the block. |
| Load | Initializes an XML object using the specified XML string. |
| LoadFile | Initializes an XML object using the specified XML file. |
| Output | Inserts the value of an XML object return value supplied by a Web service into an output value column. |
| RemoveCDATASection | Removes the specified CDATA section from the XMLData document. |
| RemoveComment | Removes the specified comment section from the XMLData document. |
| SaveFile | Saves the XMLData document to the specified file. |
| SetRootElement | Sets the specified XMLElement object as the root element of the XMLData object and returns the newly set element root. |
| ToString | Returns a string representation of the XML object. |
| Validate | Checks whether the XMLData object conforms to the specified schema file. |
AddCDATASection Method
Description
Adds a CDATA section to the XMLData document.
Syntax
XMLData.AddCDATASection CDataSectionString
Argument | Type | Description |
|---|---|---|
CDataSectionString | String | The CDATA section to add. |
ExampleThe following example uses the AddCDataSection method to add a new CData section to the XML document.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set dataSections = doc.CDataSections()
msg = "First I had " & dataSections.Count() & " CDataSections."
newSection = "These characters <> are only allowed in CDATASections"
doc.AddCDATASection newSection
msg = msg + "Now I have " & dataSections.Count() & " CDataSections."
doc.RemoveCDATASection newSection
msg = msg + "Again I have " & dataSections.Count() & " CDataSections."
msgbox msg
AddComment Method
Description
Adds a comment to the XMLData document.
Syntax
XMLData.AddComment CommentString
Argument | Type | Description |
|---|---|---|
CommentString | String | The comment to add. |
ExampleThe following example uses the AddComment method to add a new comment to the XML document.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set comments = doc.Comments()
msg = "First I had " & comments.Count() & " comments."
comment = "UFT One is probably the best testing tool in the world!"
doc.AddComment comment
msg = msg + "Now I have " & comments.Count() & " comments."
doc.RemoveComment comment
msg = msg + "Again I have " & comments.Count() & " comments."
msgbox msg
AddNamespace Method
Description
Adds the specified namespace to the namespace collection used by the XMLData object.
Syntax
XMLData.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).
ExampleThe following example validates that the XML document has the expected number of ISBN elements. Because the XML document uses the default namespace, the AddNamespace method must be used to resolve the XPath expression in the ChildElementsByPath method call.
Set doc = XMLUtil.CreateXML()
doc.Load "<Bookstore xmlns="urn:newbooks-schema“><Book><ISBN>1234</ISBN></Book><Book><ISBN>4321</ISBN></Book><Book><ISBN>6584</ISBN></Book></Bookstore>"
doc.AddNamespace("bk", "urn:newbooks-schema");
Set children = doc.ChildElementsByPath("/bk:Bookstore/bk:Book/bk:ISBN")
numOfDescendants = doc.GetRootElement().GetNumDescendantElemByName("ISBN")
If children.Count() <> numOfDescendants then
msgbox "Problem with XML structure"
End if
CDATASections Property
Description
Returns the document's CDATA sections as a collection.
Syntax
XMLData.CDATASections
Return Value
IMPORTANT
The returned item collection is a copy of the collection of the document's CDATA sections. Therefore, any changes you make to a document'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.
ExampleThe following example uses the CDataSections property to compile a list of the CData sections in the XML document to count them.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set dataSections = doc.CDataSections()
msgbox "I have " & dataSections.Count() & " CDataSections."
Check Method
Description
Executes a checkpoint on an XML object return value supplied by a Web service.
Note: This method is only available with the UFT One Web Services Add-in. You insert a checkpoint on an XML object return value using the Step Generator. For more details, see the Web Services section in the UFT One Help Center.
Syntax
XMLData(description).Check CheckPoint(Name)
Argument | Type | Description |
|---|---|---|
CheckPoint (Name) | Variant | The checkpoint object, which contains the expected values to be compared and verified during the test run. |
Note: If you want to retrieve the return value of a checkpoint, you must add parentheses around the name of the checkpoint in the statement. For example:
a = Browser("MyBrowser").Page("MyPage").Check (CheckPoint("MyProperty"))Return Value
Boolean
ExampleThe following example creates a checkpoint for a SOAPWebService object with the name FlightWebService.
SOAPWebService("FlightWebService").Check CheckPoint("FlightWebService")
ChildElementsByPath Property
Description
Returns all of the child elements that reside in the specified path.
Syntax
XMLData.ChildElementsByPath(XMLPath)
Argument | Type | Description |
|---|---|---|
XMLPath | String | The path containing the child element from which you want to retrieve the child element set. You can use the XPath or a UNIX-style file system path. For example: To return child elements of the current element node, use "." |
Return Value
IMPORTANT
The returned item collection is a copy of the collection of the selected child elements. Therefore, any changes you make to these 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.
ExampleThe following example uses the ChildElementsByPath property to validate that the document has the expected number of ISBN elements
Set doc = XMLUtil.CreateXML()
doc.Load "<Bookstore><Book><ISBN>1234</ISBN></Book><Book><ISBN>4321</ISBN></Book><Book><ISBN>6584</ISBN></Book></Bookstore>"
Set children = doc.ChildElementsByPath("/Bookstore/Book/ISBN")
Set child = doc.GetRootElement().ChildElements().Item(1)
Set relatives = child.ChildElementsByPath("../Book/ISBN")
if children.Count() <> relatives.Count() then
msgbox "Problem with XML structure"
end if
numOfDescendants = doc.GetRootElement().GetNumDescendantElemByName("ISBN")
if children.Count() <> numOfDescendants then
msgbox "Problem with XML structure"
end if
Clone Method
Description
Returns an exact copy of the XMLData object.
Syntax
XMLData.Clone
Return Value
ExampleThe following example loads an XML file and duplicates it using the Load method. Then it clones the file again using the Clone method and compares the two files. The files are expected to match.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set doc1 = XMLUtil.CreateXML()
doc1.Load doc.ToString
Set doc2 = doc.Clone()
res = doc1.Compare(doc2,resultDoc)
if res = 1 then
msgbox "Documents match :-)"
else
msgbox "Documents do not match :-("
end if
Comments Property
Description
Returns the document comments in a collection.
Syntax
XMLData.Comments
Return Value
IMPORTANT
The returned item collection is a copy of the collection of document comments. Therefore, any changes you make to a document comment 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.
ExampleThe following example uses the Comments property to compile a collection of comments to count them.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set comments = doc.Comments()
msgbox "I have " & comments.Count() & " comments."
Compare Method
Description
Compares the specified XML document with the current XMLData object and creates a new XMLData object containing the differences. This method returns a boolean value indicating whether or not the two files are equal.
You can choose to compare all or some of the following DOM nodes: Document Type Declaration, Elements, Attributes, #text nodes, and CDATA sections. Comments are ignored.
For more details about the format of the resulting document, see Understanding the Resulting Document of an XMLData.Compare Statement.
Syntax
XMLData.Compare(XMLDocument, ResultXMLDocument, [Filter])
Argument | Type | Description |
|---|---|---|
XMLDocument | XMLData | The XML document object that you want to compare to this XMLData object. |
ResultXMLDocument | XMLData | An XMLData object containing the differences between the XMLData object and the XML document specified in the XMLDocument argument, according to the specified Filter argument (if any). |
Filter | Number or pre-defined constant | Optional. The XML DOM node information to be compared: 0 or micXMLNone: Compares the elements and document type declaration of the specified XML documents. 1 or micXMLAttributes: Compares the attributes of the specified XML documents, in addition to their elements and document type declaration. 2 or micXMLCDataSections: Compares the CDATA sections of the specified XML documents, in addition to their elements and document type declaration. 4 or micXMLValues: Compares the #text nodes of the specified XML documents, in addition to their elements and document type declaration. Note: If you do not use this parameter, the Document Type Declaration, Elements, Attributes, #text nodes, and CDATA sections are all compared. |
Return Value
Boolean
ExampleThe following example uses the Compare method to compare the elements, document type declaration, attributes, and #text nodes of two XML documents that are expected to be exact duplicates. The files are copies of an XML file. One copy is created using the Load method, and the other is created using the Clone method. The files are expected to match.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set doc1 = xmlutil.CreateXML()
doc1.Load doc.ToString
Set doc2 = doc.Clone()
res = doc1.Compare(doc2,resultDoc,micXMLValues+micXMLCDataSections)
if res = 1 then
msgbox "Documents match :-)"
else
msgbox do not match :-("
end if
CreateDocument Method
Description
Creates a new, empty XML document with a specified root name.
Syntax
XMLData.CreateDocument(RootName)
Argument | Type | Description |
|---|---|---|
RootName | String | The root name for the new XMLData object. |
Return Value
ExampleThe following example uses the CreateDocument method to create a new XML document with a root element named Papa and then adds a new child element to the Papa root element.
Set doc = XMLUtil.CreateXML()
doc.CreateDocument "Papa"
Set root = doc.GetRootElement()
root.AddChildElementByName "Bambino","Valuable"
GetRootElement Method
Description
Returns an XMLElement object, representing the block's root element.
Syntax
XMLData.GetRootElement
Return Value
ExampleThe following example loads an XML document and then uses the GetRootElement method to print the number of children of the root element named Cartman.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
Set child = children.ItemByName("Cartman")
numOfChildren = 0
While Not child Is nothing
numOfChildren = numOfChildren+1
Set child = children.ItemByName("Cartman",numOfChildren+1)
Wend
msgbox "The number of children named Cartman is " & numOfChildren
GetValidationError Method
Description
Retrieves the description of the specified error from the most recent schema validation.
Syntax
XMLData.GetValidationError(ErrorNumberIndex)
Argument | Type | Description |
|---|---|---|
ErrorNumberIndex | Number | The index number corresponding to the error you want to retrieve. Index values begin with 1. |
Return Value
String. The string containing the error description.
IMPORTANT
This method is often used in conjunction with the GetValidationErrorsNumber Method, which enables you to retrieve the total number of errors in the list.
ExampleThe following example checks whether an XML file conforms to a schema file. If it does, a message box indicates success. Otherwise, each of the validation errors is displayed in a separate message box.
Set doc = XMLUtil.CreateXML()
'Load the XML file for validation
doc.LoadFile "c:\Temp\calc2.xml"
'Validate the file against C:\temp\ObjectRepository.xsd XML schema
ans = doc.Validate ("C:\temp\ObjectRepository.xsd")
'Check if the validation was successful
'if the validation is successful, display a success message
If ans Then
MsgBox "The checked XML file matches the specified XML schema."
'otherwise, if the validation is not successful, display each of the returned
'error messages in a separate message box
else
'retrieve the count of validation errors
errNo = doc.GetValidationErrorsNumber
'retrieve each error message and display it
For i = 1 to errNo
errStr = doc.GetValidationError(i)
MsgBox errStr
Next
End If
GetValidationErrorsNumber Method
Description
Returns the total number of errors that occurred in the most recent schema validation.
Syntax
XMLData.GetValidationErrorsNumber
Return Value
Number. The total number of errors in the validation error list.
IMPORTANT
This method is often used in conjunction with the GetValidationError Method, which enables you to retrieve the error description of a specified error (index).
ExampleThe following example checks whether an XML file conforms to a schema file. If it does, a message box indicates success. Otherwise, each of the validation errors is displayed in a separate message box.
Set doc = XMLUtil.CreateXML()
'Load the XML file for validation
doc.LoadFile "c:\Temp\calc2.xml"
'Validate the file against C:\temp\ObjectRepository.xsd XML schema
ans = doc.Validate ("C:\temp\ObjectRepository.xsd")
'Check if the validation was successful
'if the validation is successful, display a success message
If ans Then
MsgBox "The checked XML file matches the specified XML schema."
'otherwise, if the validation is not successful, display each of the returned
'error messages in a separate message box
else
'retrieve the count of validation errors
errNo = doc.GetValidationErrorsNumber
'retrieve each error message and display it
For i = 1 to errNo
errStr = doc.GetValidationError(i)
MsgBox errStr
Next
End If
GetVersion Method
Description
Returns the XML version of the block.
XMLData.GetVersion
Return Value
String
ExampleThe following example uses the GetVersion method to display the document version of the XML document.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
msgbox "The document version of this XML file is " & doc.GetVersion()
Load Method
Description
Initializes an XML object using the specified XML string.
XMLData.Load (XMLString)
Argument | Type | Description |
|---|---|---|
XMLString | String | The XML string containing the initialization information. |
ExampleThe following example loads an XML file and duplicates it using the Load method. Then it clones the file again using the Clone method and compares the two files. The files are expected to match.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set doc1 = xmlutil.CreateXML()
doc1.Load doc.ToString
Set doc2 = doc.Clone()
res = doc1.Compare(doc2,resultDoc)
if res = 1 then
msgbox "Documents match :-)"
else
msgbox "Documents do not match :-("
end if
LoadFile Method
Description
Initializes an XML object using the specified XML file. You can specify an XML file either from your file system or from ALM.
Syntax
XMLData.LoadFile (FilePath)
Argument | Type | Description |
|---|---|---|
FilePath | String | The XML string containing the path or URL of the XML file to load. If you enter a relative path, UFT One searches for the file in the current test's directory, and then in the folders listed in the Folders pane of the Options dialog box (Tools > Options > GUI Testing tab > Folders node). For more details, see the UFT One User Guide. |
ExampleThe following example loads an XML file and then prints the number of children of the root element named Cartman.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set root = doc.GetRootElement()
Set children = root.ChildElements()
Set child = children.ItemByName("Cartman")
numOfChildren = 0
While Not child Is nothing
numOfChildren = numOfChildren+1
Set child = children.ItemByName("Cartman",numOfChildren+1)
Wend
msgbox "The number of children named Cartman is " & numOfChildren
Output Method
Description
Inserts the value of an XML object return value supplied by a Web service into an output value column.
Note: This method is only available with the UFT One Web Services Add-in. You insert an output value supplied by an XML object return value using the Step Generator.
Syntax
XMLData(description).Output CheckPoint(Name)
Argument | Type | Description |
|---|---|---|
Checkpoint (Name) | Variant | The output object, which contains the name(s) of the column(s) to which to output the data. |
ExampleThe following example creates an output value called FlightWebService for the SOAPWebService object.
SOAPWebService("FlightWebService").Output CheckPoint("FlightWebService")
RemoveCDATASection Method
Description
Removes the specified CDATA section from the XMLData document.
Syntax
XMLData.RemoveCDATASection CDataSectionString
Argument | Type | Description |
|---|---|---|
CDataSectionString | String | The CDATA string to remove. |
ExampleThe following example uses the RemoveCDataSections method to remove the new CData section from the XML document.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set dataSections = doc.CDataSections()
msg = "First I had " & dataSections.Count() & " CDataSections."
newSection = "These characters <> are only allowed in CDATASections"
doc.AddCDATASection newSection
msg = msg + "Now I have " & dataSections.Count() & " CDataSections."
doc.RemoveCDATASection newSection
msg = msg + "Again I have " & dataSections.Count() & " CDataSections."
msgbox msg
RemoveComment Method
Description
Removes the specified comment section from the XMLData document.
XMLData.RemoveComment CommentString
Argument | Type | Description |
|---|---|---|
CommentString | String | The comment string to remove. |
ExampleThe following example uses the RemoveComment method to remove the new comment from the XML document.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
Set comments = doc.Comments()
msg = "First I had " & comments.Count() & " comments."
comment = "UFT One is probably the best testing tool in the world!"
doc.AddComment comment
msg = msg + "Now I have " & comments.Count() & " comments."
doc.RemoveComment comment
msg = msg + "Again I have " & comments.Count() & " comments."
msgbox msg
SaveFile Method
Description
Saves the XMLData document to the specified file.
Syntax
XMLData.SaveFile FilePath
Argument | Type | Description |
|---|---|---|
CommentString | String | The full path of the file to which you want to save the XMLData document. |
ExampleThe following example uses the SaveFile method to create a copy of d:\example.xml as d:\example1.xml.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "d:\example.xml"
doc.SaveFile "d:\example1.xml"
SetRootElement Method
Description
Sets the specified XMLElement object as the root element of the XMLData object and returns the newly set element root.
Note: This method copies the specified XMLElement and sets the copied object as the new XML root (replacing the previous root element).
Syntax
XMLData.SetRootElement XMLElement
Argument | Type | Description |
|---|---|---|
XMLElement | The XMLElement that you want to set as the XMLData object's root element. |
Return Value
ExampleThe following example uses the SetRootElement method to replace the dummyRoot in the doc2 XMLData object with the root element from the doc XMLData object (example.xml).
Set doc = XMLUtil.CreateXML()
doc.LoadFile d:\example.xml"
doc.SaveFile "d:\example1.xml"
Set doc1 = XMLUtil.CreateXML()
doc1.LoadFile "d:\example1.xml"
Set doc2 = XMLUtil.CreateXML("dummyRoot")
doc2.SetRootElement doc.GetRootElement
res = doc1.Compare(doc2,resultDoc)
if res = 1 then
msgbox "Documents match :-)"
else
msgbox "Documents do not match :-("
end if
ToString Method
Description
Returns a string representation of the XML object.
Syntax
XMLData.ToString
Return Value
String
ExampleThe following example uses the ToString function to initialize a copy of the XML file.
Set doc = XMLUtil.CreateXML()
doc.LoadFile "c:\example.xml"
Set doc1 = xmlutil.CreateXML()
doc1.Load doc.ToString
Set doc2 = doc.Clone()
res = doc1.Compare(doc2,resultDoc)
if res = 1 then
msgbox "Documents match :-)"
else
msgbox "Documents do not match :-("
end if
Validate Method
Description
Checks whether the XMLData object conforms to the specified schema file.
Syntax
XMLData.Validate ([SchemaLocation])
Argument | Type | Description |
|---|---|---|
SchemaLocation | String | Optional. The URL or path (file system or ALM) of the schema upon which to validate the document. If no value is specified and the XMLData object has an internal schema reference or declaration, the internal schema is used. Otherwise the method does not perform a validation, and it returns TRUE. |
Return Value
Boolean. Returns TRUE if the XMLData object conforms to the schema (or if the validation was not performed) and FALSE if it does not.
IMPORTANT
If the method returns FALSE, you can retrieve the number and text of each validation error using the GetValidationError Method and the GetValidationErrorsNumber Method.
ExampleThe following example checks whether an XML file conforms to a schema file. If it does, a message box indicates success. Otherwise, each of the validation errors is displayed in a separate message box.
Set doc = XMLUtil.CreateXML()
'Load the XML file for validation
doc.LoadFile "c:\Temp\calc2.xml"
'Validate the file against C:\temp\ObjectRepository.xsd XML schema
isValidated = doc.Validate ("C:\temp\ObjectRepository.xsd")
'Check if the validation was successful
'if the validation is successful, display a success message
If isValidated Then
MsgBox "The checked XML file matches the specified XML schema."
'otherwise, if the validation is not successful, display each of the returned
'error messages in a separate message box
else
'retrieve the count of validation errors
errNo = doc.GetValidationErrorsNumber
'retrieve each error message and display it
For i = 1 to errNo
errStr = doc.GetValidationError(i)
MsgBox errStr
Next
End If
