Skip to content

XML

XML

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 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 it 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.

= 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.

| | text | | | | | more text | | | | |

| Text with bold and italics. |

| |

| ${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 a 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:

| | | | |

| ${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:

| | | | |

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:

| | |

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

== 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.

Source code in src/robot/libraries/XML.py 
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
class XML:
    """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 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 it 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.

    = 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 a 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.   |

    == 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.
    """
    ROBOT_LIBRARY_SCOPE = 'GLOBAL'
    ROBOT_LIBRARY_VERSION = get_version()

    def __init__(self, use_lxml=False):
        """Import library with optionally lxml mode enabled.

        This library uses Python's standard
        [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree]
        module for parsing XML by default. If ``use_lxml`` argument is given
        a true value (see `Boolean arguments`), the [http://lxml.de|lxml] module
        is used instead. See the `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
        emits a warning and reverts back to using the standard ElementTree.
        """
        if use_lxml and lxml_etree:
            self.etree = lxml_etree
            self.modern_etree = True
            self.lxml_etree = True
        else:
            self.etree = ET
            self.modern_etree = ET.VERSION >= '1.3'
            self.lxml_etree = False
        if use_lxml and not lxml_etree:
            logger.warn('XML library reverted to use standard ElementTree '
                        'because lxml module is not installed.')
        self._ns_stripper = NameSpaceStripper(self.etree, self.lxml_etree)

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

        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.
        """
        if isinstance(source, os.PathLike):
            source = str(source)
        with ETSource(source) as source:
            tree = self.etree.parse(source)
        if self.lxml_etree:
            strip = (lxml_etree.Comment, lxml_etree.ProcessingInstruction)
            lxml_etree.strip_elements(tree, *strip, **dict(with_tail=False))
        root = tree.getroot()
        if not keep_clark_notation:
            self._ns_stripper.strip(root, preserve=not strip_namespaces)
        return root

    def 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.
        """
        elements = self.get_elements(source, xpath)
        if len(elements) != 1:
            self._raise_wrong_number_of_matches(len(elements), xpath)
        return elements[0]

    def _raise_wrong_number_of_matches(self, count, xpath, message=None):
        if not message:
            message = self._wrong_number_of_matches(count, xpath)
        raise AssertionError(message)

    def _wrong_number_of_matches(self, count, xpath):
        if not count:
            return f"No element matching '{xpath}' found."
        if count == 1:
            return f"One element matching '{xpath}' found."
        return f"Multiple elements ({count}) matching '{xpath}' found."

    def 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} |        |             |
        """
        if isinstance(source, (str, bytes, os.PathLike)):
            source = self.parse_xml(source)
        finder = ElementFinder(self.etree, self.modern_etree, self.lxml_etree)
        return finder.find_all(source, xpath)

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

        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}        |        |             |
        """
        return list(self.get_element(source, xpath))

    def 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`.
        """
        count = len(self.get_elements(source, xpath))
        logger.info(f"{count} element{s(count)} matched '{xpath}'.")
        return count

    def 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.
        """
        count = self.get_element_count(source, xpath)
        if not count:
            self._raise_wrong_number_of_matches(count, xpath, message)

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

        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.
        """
        count = self.get_element_count(source, xpath)
        if count:
            self._raise_wrong_number_of_matches(count, xpath, message)

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

        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`.
        """
        element = self.get_element(source, xpath)
        text = ''.join(self._yield_texts(element))
        if normalize_whitespace:
            text = self._normalize_whitespace(text)
        return text

    def _yield_texts(self, element, top=True):
        if element.text:
            yield element.text
        for child in element:
            for text in self._yield_texts(child, top=False):
                yield text
        if element.tail and not top:
            yield element.tail

    def _normalize_whitespace(self, text):
        return ' '.join(text.split())

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

        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}  |             |
        """
        return [self.get_element_text(elem, normalize_whitespace=normalize_whitespace)
                for elem in self.get_elements(source, xpath)]

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

        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 |
        """
        text = self.get_element_text(source, xpath, normalize_whitespace)
        should_be_equal(text, expected, message, values=False)

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

        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 |
        """
        text = self.get_element_text(source, xpath, normalize_whitespace)
        should_match(text, pattern, message, values=False)

    @keyword(types=None)
    def get_element_attribute(self, source, name, xpath='.', default=None):
        """Returns the named attribute of the specified element.

        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`.
        """
        return self.get_element(source, xpath).get(name, default)

    def 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.
        """
        return dict(self.get_element(source, xpath).attrib)

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

        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`.
        """
        attr = self.get_element_attribute(source, name, xpath)
        should_be_equal(attr, expected, message, values=False)

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

        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 |
        """
        attr = self.get_element_attribute(source, name, xpath)
        if attr is None:
            raise AssertionError(f"Attribute '{name}' does not exist.")
        should_match(attr, pattern, message, values=False)

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

        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`.
        """
        attr = self.get_element_attribute(source, name, xpath)
        if attr is not None:
            raise AssertionError(message or
                                 f"Attribute '{name}' exists and has value '{attr}'.")

    def elements_should_be_equal(self, source, expected, exclude_children=False,
                                 normalize_whitespace=False, sort_children=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`). Child elements are expected to
        be in the same order, but that can be changed by giving ``sort_children``
        a true value. Notice that elements are sorted solely based on tag names.

        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`.

        ``sort_children`` is new in Robot Framework 7.0.
        """
        self._compare_elements(source, expected, should_be_equal, exclude_children,
                               sort_children, normalize_whitespace)

    def elements_should_match(self, source, expected, exclude_children=False,
                              normalize_whitespace=False, sort_children=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.
        """
        self._compare_elements(source, expected, should_match, exclude_children,
                               sort_children, normalize_whitespace)

    def _compare_elements(self, source, expected, comparator, exclude_children,
                          sort_children, normalize_whitespace):
        normalizer = self._normalize_whitespace if normalize_whitespace else None
        sorter = self._sort_children if sort_children else None
        comparator = ElementComparator(comparator, normalizer, sorter, exclude_children)
        comparator.compare(self.get_element(source), self.get_element(expected))

    def _sort_children(self, element):
        tails = [child.tail for child in element]
        element[:] = sorted(element, key=lambda child: child.tag)
        for child, tail in zip(element, tails):
            child.tail = tail

    def 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.
        """
        source = self.get_element(source)
        self.get_element(source, xpath).tag = tag
        return source

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

        Like `Set Element Tag` but sets the tag of all elements matching
        the given ``xpath``.
        """
        source = self.get_element(source)
        for elem in self.get_elements(source, xpath):
            self.set_element_tag(elem, tag)
        return source

    @keyword(types=None)
    def 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.
        """
        source = self.get_element(source)
        element = self.get_element(source, xpath)
        if text is not None:
            element.text = text
        if tail is not None:
            element.tail = tail
        return source

    @keyword(types=None)
    def 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``.
        """
        source = self.get_element(source)
        for elem in self.get_elements(source, xpath):
            self.set_element_text(elem, text, tail)
        return source

    def 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.
        """
        if not name:
            raise RuntimeError('Attribute name can not be empty.')
        source = self.get_element(source)
        self.get_element(source, xpath).attrib[name] = value
        return source

    def 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``.
        """
        source = self.get_element(source)
        for elem in self.get_elements(source, xpath):
            self.set_element_attribute(elem, name, value)
        return source

    def 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.
        """
        source = self.get_element(source)
        attrib = self.get_element(source, xpath).attrib
        if name in attrib:
            attrib.pop(name)
        return source

    def 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``.
        """
        source = self.get_element(source)
        for elem in self.get_elements(source, xpath):
            self.remove_element_attribute(elem, name)
        return source

    def 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.
        """
        source = self.get_element(source)
        self.get_element(source, xpath).attrib.clear()
        return source

    def 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``.
        """
        source = self.get_element(source)
        for elem in self.get_elements(source, xpath):
            self.remove_element_attributes(elem)
        return source

    def 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.
        """
        source = self.get_element(source)
        parent = self.get_element(source, xpath)
        element = self.copy_element(element)
        if index is None:
            parent.append(element)
        else:
            parent.insert(int(index), element)
        return source

    def 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 |
        """
        source = self.get_element(source)
        self._remove_element(source, self.get_element(source, xpath), remove_tail)
        return source

    def 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  |
        """
        source = self.get_element(source)
        for element in self.get_elements(source, xpath):
            self._remove_element(source, element, remove_tail)
        return source

    def _remove_element(self, root, element, remove_tail=False):
        parent = self._find_parent(root, element)
        if not remove_tail:
            self._preserve_tail(element, parent)
        parent.remove(element)

    def _find_parent(self, root, element):
        for parent in root.iter():
            for child in parent:
                if child is element:
                    return parent
        raise RuntimeError('Cannot remove root element.')

    def _preserve_tail(self, element, parent):
        if not element.tail:
            return
        index = list(parent).index(element)
        if index == 0:
            parent.text = (parent.text or '') + element.tail
        else:
            sibling = parent[index-1]
            sibling.tail = (sibling.tail or '') + element.tail

    def 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.
        """
        source = self.get_element(source)
        element = self.get_element(source, xpath)
        tail = element.tail
        element.clear()
        if not clear_tail:
            element.tail = tail
        return source

    def 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 afterward, 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>     |
        """
        return copy.deepcopy(self.get_element(source, xpath))

    def 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.

        The string is returned as Unicode by default. 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`.
        """
        source = self.get_element(source, xpath)
        if self.lxml_etree:
            source = self._ns_stripper.unstrip(source)
        string = self.etree.tostring(source, encoding='UTF-8').decode('UTF-8')
        string = re.sub(r'^<\?xml .*\?>', '', string).strip()
        if encoding:
            string = string.encode(encoding)
        return string

    def 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.
        """
        string = self.element_to_string(source, xpath)
        logger.write(string, level)
        return string

    def 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.
        """
        path = os.path.abspath(str(path) if isinstance(path, os.PathLike)
                               else path.replace('/', os.sep))
        elem = self.get_element(source)
        tree = self.etree.ElementTree(elem)
        config = {'encoding': encoding}
        if self.modern_etree:
            config['xml_declaration'] = True
        if self.lxml_etree:
            elem = self._ns_stripper.unstrip(elem)
            # https://bugs.launchpad.net/lxml/+bug/1660433
            if tree.docinfo.doctype:
                config['doctype'] = tree.docinfo.doctype
            tree = self.etree.ElementTree(elem)
        with open(path, 'wb') as output:
            if 'doctype' in config:
                output.write(self.etree.tostring(tree, **config))
            else:
                tree.write(output, **config)
        logger.info(f'XML saved to <a href="file://{path}">{path}</a>.', html=True)

    def 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.
        """
        if not self.lxml_etree:
            raise RuntimeError("'Evaluate Xpath' keyword only works in lxml mode.")
        return self.get_element(source, context).xpath(expression)

__init__(use_lxml=False)

Import library with optionally lxml mode enabled.

This library uses Python's standard [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree] module for parsing XML by default. If use_lxml argument is given a true value (see Boolean arguments), the [http://lxml.de|lxml] module is used instead. See the 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 emits a warning and reverts back to using the standard ElementTree.

Source code in src/robot/libraries/XML.py 
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
def __init__(self, use_lxml=False):
    """Import library with optionally lxml mode enabled.

    This library uses Python's standard
    [http://docs.python.org/library/xml.etree.elementtree.html|ElementTree]
    module for parsing XML by default. If ``use_lxml`` argument is given
    a true value (see `Boolean arguments`), the [http://lxml.de|lxml] module
    is used instead. See the `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
    emits a warning and reverts back to using the standard ElementTree.
    """
    if use_lxml and lxml_etree:
        self.etree = lxml_etree
        self.modern_etree = True
        self.lxml_etree = True
    else:
        self.etree = ET
        self.modern_etree = ET.VERSION >= '1.3'
        self.lxml_etree = False
    if use_lxml and not lxml_etree:
        logger.warn('XML library reverted to use standard ElementTree '
                    'because lxml module is not installed.')
    self._ns_stripper = NameSpaceStripper(self.etree, self.lxml_etree)

add_element(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} | | | Add Element | ${XML} | | xpath=new | | Add Element | ${XML} | | index=1 | xpath=new | | ${new} = | Get Element | ${XML} | new | | Elements Should Be Equal | ${new} | |

Use Remove Element or Remove Elements to remove elements.

Source code in src/robot/libraries/XML.py 
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
def 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.
    """
    source = self.get_element(source)
    parent = self.get_element(source, xpath)
    element = self.copy_element(element)
    if index is None:
        parent.append(element)
    else:
        parent.insert(int(index), element)
    return source

clear_element(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} | | | 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} | |

Use Remove Element to remove the whole element.

Source code in src/robot/libraries/XML.py 
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
def 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.
    """
    source = self.get_element(source)
    element = self.get_element(source, xpath)
    tail = element.tail
    element.clear()
    if not clear_tail:
        element.tail = tail
    return source

copy_element(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 afterward, 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} | new text | | Elements Should Be Equal | ${copy1} | text | | Elements Should Be Equal | ${copy2} | text |

Source code in src/robot/libraries/XML.py 
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
def 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 afterward, 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>     |
    """
    return copy.deepcopy(self.get_element(source, xpath))

element_attribute_should_be(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.

Source code in src/robot/libraries/XML.py 
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
def 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`.
    """
    attr = self.get_element_attribute(source, name, xpath)
    should_be_equal(attr, expected, message, values=False)

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

Source code in src/robot/libraries/XML.py 
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
def 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 |
    """
    attr = self.get_element_attribute(source, name, xpath)
    if attr is None:
        raise AssertionError(f"Attribute '{name}' does not exist.")
    should_match(attr, pattern, message, values=False)

element_should_exist(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.

Source code in src/robot/libraries/XML.py 
616
617
618
619
620
621
622
623
624
625
626
627
628
629
def 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.
    """
    count = self.get_element_count(source, xpath)
    if not count:
        self._raise_wrong_number_of_matches(count, xpath, message)

element_should_not_exist(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.

Source code in src/robot/libraries/XML.py 
631
632
633
634
635
636
637
638
639
640
641
642
643
644
def 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.
    """
    count = self.get_element_count(source, xpath)
    if count:
        self._raise_wrong_number_of_matches(count, xpath, message)

element_should_not_have_attribute(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.

Source code in src/robot/libraries/XML.py 
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
def 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`.
    """
    attr = self.get_element_attribute(source, name, xpath)
    if attr is not None:
        raise AssertionError(message or
                             f"Attribute '{name}' exists and has value '{attr}'.")

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

Source code in src/robot/libraries/XML.py 
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
def 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 |
    """
    text = self.get_element_text(source, xpath, normalize_whitespace)
    should_be_equal(text, expected, message, values=False)

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

Source code in src/robot/libraries/XML.py 
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
def 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 |
    """
    text = self.get_element_text(source, xpath, normalize_whitespace)
    should_match(text, pattern, message, values=False)

element_to_string(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.

The string is returned as Unicode by default. 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.

Source code in src/robot/libraries/XML.py 
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
def 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.

    The string is returned as Unicode by default. 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`.
    """
    source = self.get_element(source, xpath)
    if self.lxml_etree:
        source = self._ns_stripper.unstrip(source)
    string = self.etree.tostring(source, encoding='UTF-8').decode('UTF-8')
    string = re.sub(r'^<\?xml .*\?>', '', string).strip()
    if encoding:
        string = string.encode(encoding)
    return string

elements_should_be_equal(source, expected, exclude_children=False, normalize_whitespace=False, sort_children=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). Child elements are expected to be in the same order, but that can be changed by giving sort_children a true value. Notice that elements are sorted solely based on tag names.

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} | text | | ${p} = | Get Element | ${XML} | html/p | | Elements Should Be Equal | ${p} |

Text with bold and italics.

| normalize_whitespace=yes | | Elements Should Be Equal | ${p} |

Text with

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

sort_children is new in Robot Framework 7.0.

Source code in src/robot/libraries/XML.py 
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
def elements_should_be_equal(self, source, expected, exclude_children=False,
                             normalize_whitespace=False, sort_children=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`). Child elements are expected to
    be in the same order, but that can be changed by giving ``sort_children``
    a true value. Notice that elements are sorted solely based on tag names.

    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`.

    ``sort_children`` is new in Robot Framework 7.0.
    """
    self._compare_elements(source, expected, should_be_equal, exclude_children,
                           sort_children, normalize_whitespace)

elements_should_match(source, expected, exclude_children=False, normalize_whitespace=False, sort_children=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} | * |

See Elements Should Be Equal for more examples.

Source code in src/robot/libraries/XML.py 
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
def elements_should_match(self, source, expected, exclude_children=False,
                          normalize_whitespace=False, sort_children=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.
    """
    self._compare_elements(source, expected, should_match, exclude_children,
                           sort_children, normalize_whitespace)

evaluate_xpath(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.

Source code in src/robot/libraries/XML.py 
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
def 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.
    """
    if not self.lxml_etree:
        raise RuntimeError("'Evaluate Xpath' keyword only works in lxml mode.")
    return self.get_element(source, context).xpath(expression)

get_child_elements(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} | | |

Source code in src/robot/libraries/XML.py 
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
def 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}        |        |             |
    """
    return list(self.get_element(source, xpath))

get_element(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.

Source code in src/robot/libraries/XML.py 
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
def 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.
    """
    elements = self.get_elements(source, xpath)
    if len(elements) != 1:
        self._raise_wrong_number_of_matches(len(elements), xpath)
    return elements[0]

get_element_attribute(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.

Source code in src/robot/libraries/XML.py 
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
@keyword(types=None)
def 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`.
    """
    return self.get_element(source, xpath).get(name, default)

get_element_attributes(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.

Source code in src/robot/libraries/XML.py 
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
def 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.
    """
    return dict(self.get_element(source, xpath).attrib)

get_element_count(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.

Source code in src/robot/libraries/XML.py 
604
605
606
607
608
609
610
611
612
613
614
def 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`.
    """
    count = len(self.get_elements(source, xpath))
    logger.info(f"{count} element{s(count)} matched '{xpath}'.")
    return count

get_element_text(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.

Source code in src/robot/libraries/XML.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
def 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`.
    """
    element = self.get_element(source, xpath)
    text = ''.join(self._yield_texts(element))
    if normalize_whitespace:
        text = self._normalize_whitespace(text)
    return text

get_elements(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} | | |

Source code in src/robot/libraries/XML.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
def 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} |        |             |
    """
    if isinstance(source, (str, bytes, os.PathLike)):
        source = self.parse_xml(source)
    finder = ElementFinder(self.etree, self.modern_etree, self.lxml_etree)
    return finder.find_all(source, xpath)

get_elements_texts(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} | |

Source code in src/robot/libraries/XML.py 
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
def 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}  |             |
    """
    return [self.get_element_text(elem, normalize_whitespace=normalize_whitespace)
            for elem in self.get_elements(source, xpath)]

log_element(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.

Source code in src/robot/libraries/XML.py 
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
def 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.
    """
    string = self.element_to_string(source, xpath)
    logger.write(string, level)
    return string

parse_xml(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 | | | ${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.

Source code in src/robot/libraries/XML.py 
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
def 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.
    """
    if isinstance(source, os.PathLike):
        source = str(source)
    with ETSource(source) as source:
        tree = self.etree.parse(source)
    if self.lxml_etree:
        strip = (lxml_etree.Comment, lxml_etree.ProcessingInstruction)
        lxml_etree.strip_elements(tree, *strip, **dict(with_tail=False))
    root = tree.getroot()
    if not keep_clark_notation:
        self._ns_stripper.strip(root, preserve=not strip_namespaces)
    return root

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

Source code in src/robot/libraries/XML.py 
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
def 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 |
    """
    source = self.get_element(source)
    self._remove_element(source, self.get_element(source, xpath), remove_tail)
    return source

remove_element_attribute(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.

Source code in src/robot/libraries/XML.py 
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
def 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.
    """
    source = self.get_element(source)
    attrib = self.get_element(source, xpath).attrib
    if name in attrib:
        attrib.pop(name)
    return source

remove_element_attributes(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.

Source code in src/robot/libraries/XML.py 
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
def 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.
    """
    source = self.get_element(source)
    self.get_element(source, xpath).attrib.clear()
    return source

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

Source code in src/robot/libraries/XML.py 
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
def 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  |
    """
    source = self.get_element(source)
    for element in self.get_elements(source, xpath):
        self._remove_element(source, element, remove_tail)
    return source

remove_elements_attribute(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.

Source code in src/robot/libraries/XML.py 
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
def 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``.
    """
    source = self.get_element(source)
    for elem in self.get_elements(source, xpath):
        self.remove_element_attribute(elem, name)
    return source

remove_elements_attributes(source, xpath='.')

Removes all attributes from the specified elements.

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

Source code in src/robot/libraries/XML.py 
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
def 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``.
    """
    source = self.get_element(source)
    for elem in self.get_elements(source, xpath):
        self.remove_element_attributes(elem)
    return source

save_xml(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.

Source code in src/robot/libraries/XML.py 
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def 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.
    """
    path = os.path.abspath(str(path) if isinstance(path, os.PathLike)
                           else path.replace('/', os.sep))
    elem = self.get_element(source)
    tree = self.etree.ElementTree(elem)
    config = {'encoding': encoding}
    if self.modern_etree:
        config['xml_declaration'] = True
    if self.lxml_etree:
        elem = self._ns_stripper.unstrip(elem)
        # https://bugs.launchpad.net/lxml/+bug/1660433
        if tree.docinfo.doctype:
            config['doctype'] = tree.docinfo.doctype
        tree = self.etree.ElementTree(elem)
    with open(path, 'wb') as output:
        if 'doctype' in config:
            output.write(self.etree.tostring(tree, **config))
        else:
            tree.write(output, **config)
    logger.info(f'XML saved to <a href="file://{path}">{path}</a>.', html=True)

set_element_attribute(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.

Source code in src/robot/libraries/XML.py 
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
def 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.
    """
    if not name:
        raise RuntimeError('Attribute name can not be empty.')
    source = self.get_element(source)
    self.get_element(source, xpath).attrib[name] = value
    return source

set_element_tag(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.

Source code in src/robot/libraries/XML.py 
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
def 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.
    """
    source = self.get_element(source)
    self.get_element(source, xpath).tag = tag
    return source

set_element_text(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.

Source code in src/robot/libraries/XML.py 
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
@keyword(types=None)
def 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.
    """
    source = self.get_element(source)
    element = self.get_element(source, xpath)
    if text is not None:
        element.text = text
    if tail is not None:
        element.tail = tail
    return source

set_elements_attribute(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.

Source code in src/robot/libraries/XML.py 
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
def 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``.
    """
    source = self.get_element(source)
    for elem in self.get_elements(source, xpath):
        self.set_element_attribute(elem, name, value)
    return source

set_elements_tag(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.

Source code in src/robot/libraries/XML.py 
973
974
975
976
977
978
979
980
981
982
def 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``.
    """
    source = self.get_element(source)
    for elem in self.get_elements(source, xpath):
        self.set_element_tag(elem, tag)
    return source

set_elements_text(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.

Source code in src/robot/libraries/XML.py 
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
@keyword(types=None)
def 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``.
    """
    source = self.get_element(source)
    for elem in self.get_elements(source, xpath):
        self.set_element_text(elem, text, tail)
    return source