This file is indexed.

/usr/share/doc/i3-wm/testsuite.html is in i3-wm 4.14.1-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  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
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.9" />
<title>i3 testsuite</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install(2);
/*]]>*/
</script>
</head>
<body class="article">
<div id="header">
<h1>i3 testsuite</h1>
<span id="author">Michael Stapelberg</span><br />
<span id="email"><code>&lt;<a href="mailto:michael@i3wm.org">michael@i3wm.org</a>&gt;</code></span><br />
<span id="revdate">September 2012</span>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>This document explains how the i3 testsuite works, how to use it and extend it.
It is targeted at developers who not necessarily have been doing testing before
or have not been testing in Perl before. In general, the testsuite is not of
interest for end users.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_introduction">1. Introduction</h2>
<div class="sectionbody">
<div class="paragraph"><p>The i3 testsuite is a collection of files which contain testcases for various
i3 features. Some of them test if a certain workflow works correctly (moving
windows, focus behaviour, …). Others are regression tests and contain code
which previously made i3 crash or lead to unexpected behaviour. They then check
if i3 still runs (meaning it did not crash) and if it handled everything
correctly.</p></div>
<div class="paragraph"><p>The goal of having these tests is to automatically find problems and to
automatically get a feel for whether a change in the source code breaks any
existing feature. After every modification of the i3 sourcecode, the developer
should run the full testsuite. If one of the tests fails, the corresponding
problem should be fixed (or, in some cases, the testcase has to be modified).
For every bugreport, a testcase should be written to test the correct
behaviour. Initially, it will fail, but after fixing the bug, it will pass.
This ensures (or increases the chance) that bugs which have been fixed once
will never be found again.</p></div>
<div class="paragraph"><p>Also, when implementing a new feature, a testcase might be a good way to be
able to easily test if the feature is working correctly. Many developers will
test manually if everything works. Having a testcase not only helps you with
that, but it will also be useful for every future change.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_relevant_documentation">2. Relevant documentation</h2>
<div class="sectionbody">
<div class="paragraph"><p>Apart from this document, you should also have a look at:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
The "Modern Perl" book, which can be found at
   <a href="http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf">http://onyxneon.com/books/modern_perl/modern_perl_a4.pdf</a>
</p>
</li>
<li>
<p>
The latest Perl documentation of the "i3test" (general testcase setup) and
   "i3test::Test" (additional test instructions) modules:
   <a href="https://build.i3wm.org/docs/lib-i3test.html">https://build.i3wm.org/docs/lib-i3test.html</a> respectively
   <a href="https://build.i3wm.org/docs/lib-i3test-test.html">https://build.i3wm.org/docs/lib-i3test-test.html</a>
</p>
</li>
<li>
<p>
The latest documentation on i3’s IPC interface:
   <a href="https://build.i3wm.org/docs/ipc.html">https://build.i3wm.org/docs/ipc.html</a>
</p>
</li>
</ol></div>
</div>
</div>
<div class="sect1">
<h2 id="_implementation">3. Implementation</h2>
<div class="sectionbody">
<div class="paragraph"><p>For several reasons, the i3 testsuite has been implemented in Perl:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
Perl has a long tradition of testing. Every popular/bigger Perl module which
   you can find on CPAN will not only come with documentation, but also with
   tests. Therefore, the available infrastructure for tests is comprehensive.
   See for example the excellent <a href="http://search.cpan.org/perldoc?Test::More">http://search.cpan.org/perldoc?Test::More</a>
   and the referenced <a href="http://search.cpan.org/perldoc?Test::Tutorial">http://search.cpan.org/perldoc?Test::Tutorial</a>.
</p>
</li>
<li>
<p>
Perl is widely available and has a well-working package infrastructure.
</p>
</li>
<li>
<p>
The author is familiar with Perl :).
</p>
</li>
<li>
<p>
It is a good idea to use a different language for the tests than the
   implementation itself.
</p>
</li>
</ol></div>
<div class="paragraph"><p>Please do not start programming language flamewars at this point.</p></div>
<div class="sect2">
<h3 id="_installing_the_dependencies">3.1. Installing the dependencies</h3>
<div class="paragraph"><p>As usual with Perl programs, the testsuite ships with a <code>Makefile.PL</code>.
This file specifies which Perl modules the testsuite depends on and can be used
to install all of them.</p></div>
<div class="paragraph"><p>Perl modules are distributed via CPAN, and there is the official, standard CPAN
client, simply called <code>cpan</code>. It comes with every Perl installation and can be
used to install the testsuite. Many users prefer to use the more modern
<code>cpanminus</code> instead, though (because it asks no questions and just works):</p></div>
<div class="paragraph"><p>The tests additionally require <code>Xephyr(1)</code> to run a nested X server. Install
<code>xserver-xephyr</code> on Debian or <code>xorg-server-xephyr</code> on Arch Linux.</p></div>
<div class="listingblock">
<div class="title">Installing testsuite dependencies using cpanminus (preferred)</div>
<div class="content">
<pre><code>$ cd ~/i3/testcases
$ sudo apt-get install cpanminus
$ sudo cpanm .
$ cd ~/i3/AnyEvent-I3
$ sudo cpanm Module::Install
$ sudo cpanm .</code></pre>
</div></div>
<div class="paragraph"><p>If you don’t want to use cpanminus for some reason, the same works with cpan:</p></div>
<div class="listingblock">
<div class="title">Installing testsuite dependencies using cpan</div>
<div class="content">
<pre><code>$ cd ~/i3/testcases
$ sudo cpan .
$ cd ~/i3/AnyEvent-I3
$ sudo cpan Module::Install
$ sudo cpan .</code></pre>
</div></div>
<div class="paragraph"><p>In case you don’t have root permissions, you can also install into your home
directory, see <a href="https://michael.stapelberg.de/cpan/">https://michael.stapelberg.de/cpan/</a></p></div>
</div>
<div class="sect2">
<h3 id="_mechanisms">3.2. Mechanisms</h3>
<div class="sect3">
<h4 id="_script_complete_run">3.2.1. Script: complete-run</h4>
<div class="paragraph"><p>The testcases are run by a script called <code>complete-run.pl</code>. It runs all
testcases by default, but you can be more specific and let it only run one or
more testcases. Also, it takes care of starting up a separate instance of i3
with an appropriate configuration file and creates a folder for each run
containing the appropriate i3 logfile for each testcase. The latest folder can
always be found under the symlink <code>latest/</code>. Unless told differently, it will
run the tests on a separate X server instance (using Xephyr).</p></div>
<div class="paragraph"><p>Xephyr will open a window where you can inspect the running test. You can run
the tests without an X session with Xvfb, such as with <code>xvfb-run
./complete-run</code>. This will also speed up the tests significantly especially on
machines without a powerful video card.</p></div>
<div class="listingblock">
<div class="title">Example invocation of <code>complete-run.pl</code></div>
<div class="content">
<pre><code>$ cd ~/i3

$ autoreconf -fi

$ mkdir -p build &amp;&amp; cd build

$ ../configure

$ make -j8
# output omitted because it is very long

$ cd testcases

$ ./complete-run.pl
# output omitted because it is very long
All tests successful.
Files=78, Tests=734, 27 wallclock secs ( 0.38 usr  0.48 sys + 17.65 cusr  3.21 csys = 21.72 CPU)
Result: PASS

$ ./complete-run.pl t/04-floating.t
[:3] i3 startup: took 0.07s, status = 1
[:3] Running t/04-floating.t with logfile testsuite-2011-09-24-16-06-04-4.0.2-226-g1eb011a/i3-log-for-04-floating.t
[:3] t/04-floating.t finished
[:3] killing i3
output for t/04-floating.t:
ok 1 - use X11::XCB::Window;
ok 2 - The object isa X11::XCB::Window
ok 3 - Window is mapped
ok 4 - i3 raised the width to 75
ok 5 - i3 raised the height to 50
ok 6 - i3 did not map it to (0x0)
ok 7 - The object isa X11::XCB::Window
ok 8 - i3 let the width at 80
ok 9 - i3 let the height at 90
ok 10 - i3 mapped it to x=1
ok 11 - i3 mapped it to y=18
ok 12 - The object isa X11::XCB::Window
ok 13 - i3 let the width at 80
ok 14 - i3 let the height at 90
1..14

All tests successful.
Files=1, Tests=14,  0 wallclock secs ( 0.01 usr  0.00 sys +  0.19 cusr  0.03 csys =  0.23 CPU)
Result: PASS

$ less latest/i3-log-for-04-floating.t</code></pre>
</div></div>
<div class="paragraph"><p>If your attempt to run the tests with a bare call to ./complete-run.pl fails, try this:</p></div>
<div class="listingblock">
<div class="content">
<pre><code>$ ./complete-run.pl --parallel=1 --keep-xserver-output</code></pre>
</div></div>
<div class="paragraph"><p>This will show the output of Xephyr, which is the X server implementation we
use for testing.</p></div>
<div class="sect4">
<h5 id="_make_command_code_make_check_code">make command: <code>make check</code></h5>
<div class="paragraph"><p>Make check runs the i3 testsuite.
You can still use ./testcases/complete-run.pl to get the interactive progress output.</p></div>
<div class="listingblock">
<div class="title">Example invocation of <code>make check</code></div>
<div class="content">
<pre><code>$ cd ~/i3

$ autoreconf -fi

$ mkdir -p build &amp;&amp; cd build

$ ../configure

$ make -j8
# output omitted because it is very long

$ make check
# output omitted because it is very long
PASS: testcases/complete-run.pl
============================================================================
Testsuite summary for i3 4.13
============================================================================
# TOTAL: 1
# PASS:  1
# SKIP:  0
# XFAIL: 0
# FAIL:  0
# XPASS: 0
# ERROR: 0
============================================================================

$ less test-suite.log</code></pre>
</div></div>
</div>
</div>
<div class="sect3">
<h4 id="_coverage_testing">3.2.2. Coverage testing</h4>
<div class="paragraph"><p>Coverage testing is possible with <code>lcov</code>, the front-end for GCC&#8217;s coverage
testing tool <code>gcov</code>. The testcases can generate a nice html report that tells
you which functions and lines were covered during a run of the tests. You can
use this tool to judge how effective your tests are.</p></div>
<div class="paragraph"><p>To use test coverage tools, first compile with coverage enabled.</p></div>
<div class="listingblock">
<div class="content">
<pre><code>COVERAGE=1 make</code></pre>
</div></div>
<div class="paragraph"><p>Then run the tests with the <code>--coverage-testing</code> flag.</p></div>
<div class="listingblock">
<div class="content">
<pre><code>./complete-run.pl --coverage-testing</code></pre>
</div></div>
<div class="paragraph"><p>Then open <code>latest/i3-coverage/index.html</code> in your web browser.</p></div>
</div>
<div class="sect3">
<h4 id="_ipc_interface">3.2.3. IPC interface</h4>
<div class="paragraph"><p>The testsuite makes extensive use of the IPC (Inter-Process Communication)
interface which i3 provides. It is used for the startup process of i3, for
terminating it cleanly and (most importantly) for modifying and getting the
current state (layout tree).</p></div>
<div class="paragraph"><p>See [<a href="https://i3wm.org/docs/ipc.html">https://i3wm.org/docs/ipc.html</a>] for documentation on the IPC interface.</p></div>
</div>
<div class="sect3">
<h4 id="_x11_xcb">3.2.4. X11::XCB</h4>
<div class="paragraph"><p>In order to open new windows, change attributes, get events, etc., the
testsuite uses X11::XCB, a new (and quite specific to i3 at the moment) Perl
module which uses the XCB protocol description to generate Perl bindings to
X11. They work in a very similar way to libxcb (which i3 uses) and provide
relatively high-level interfaces (objects such as <code>X11::XCB::Window</code>) as well as
access to the low-level interface, which is very useful when testing a window
manager.</p></div>
</div>
</div>
<div class="sect2">
<h3 id="_filesystem_structure">3.3. Filesystem structure</h3>
<div class="paragraph"><p>In the git root of i3, the testcases live in the folder <code>testcases</code>. This
folder contains the <code>complete-run.pl</code> and a base configuration file which will
be used for the tests. The different testcases (their file extension is .t, not
.pl) themselves can be found in the conventionally named subfolder <code>t</code>:</p></div>
<div class="listingblock">
<div class="title">Filesystem structure</div>
<div class="content">
<pre><code>├── testcases
│   ├── complete-run.pl
│   ├── i3-test.config
│   ├── lib
│   │   ├── i3test.pm
│   │   ├── SocketActivation.pm
│   │   └── StartXDummy.pm
│   ├── t
│   │   ├── 00-load.t
│   │   ├── 01-tile.t
│   │   ├── 02-fullscreen.t
│   │   ├── ...
│   │   ├── omitted for brevity
│   │   ├── ...
│   │   └── 74-regress-focus-toggle.t</code></pre>
</div></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_anatomy_of_a_testcase">4. Anatomy of a testcase</h2>
<div class="sectionbody">
<div class="paragraph"><p>Learning by example is definitely a good strategy when you are wondering how to
write a testcase. Let&#8217;s take <code>t/11-goto.t</code> as an easy example and go through it
step by step:</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Boilerplate</div>
<div class="content">
<pre><code>#!perl
# vim:ts=4:sw=4:expandtab

use i3test;
use File::Temp;

my $x = X11::XCB::Connection-&gt;new;</code></pre>
</div></div>
<div class="paragraph"><p>This is what we call boilerplate. It exists at the top of every test file (to
some extent). The first line is the shebang, which specifies that this file is
a Perl script. The second line contains VIM specific settings on how to
edit/format this file (use spaces instead of tabs, indent using 4 spaces).
Afterwards, the <code>i3test</code> module is used. This module contains i3 testsuite
specific functions which you are strongly encouraged to use. They make writing
testcases a lot easier and will make it easier for other people to read your
tests.</p></div>
<div class="paragraph"><p>The next line uses the <code>File::Temp</code> module. This is specific to this testcase,
because it needs to generate a temporary name during the test. Many testcases
use only the <code>i3test</code> module.</p></div>
<div class="paragraph"><p>The last line opens a connection to X11. You might or might not need this in
your testcase, depending on whether you are going to open windows (etc.) or
only use i3 commands.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Setup</div>
<div class="content">
<pre><code>my $tmp = fresh_workspace;

cmd 'split h';</code></pre>
</div></div>
<div class="paragraph"><p>The first line calls i3test&#8217;s <code>fresh_workspace</code> function which looks for a
currently unused workspace, switches to it, and returns its name. The variable
<code>$tmp</code> will end up having a value such as <code>"/tmp/87kBVcHbA9"</code>. Note that this
is not (necessarily) a valid path, it&#8217;s just a random workspace name.</p></div>
<div class="paragraph"><p>So, now that we are on a new workspace, we ensure that the workspace uses
horizontal orientation by issuing the <code>split h</code> command (see the i3 User&#8217;s
Guide for a list of commands). This is not strictly necessary, but good style.
In general, the <code>cmd</code> function executes the specified i3 command by using the
IPC interface and returns once i3 acknowledged the command.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Setup</div>
<div class="content">
<pre><code>#####################################################################
# Create two windows and make sure focus switching works
#####################################################################

my $top = open_window($x);
my $mid = open_window($x);
my $bottom = open_window($x);</code></pre>
</div></div>
<div class="paragraph"><p>In every major section of a testcase, you should put a comment like the one
above. This makes it immediately clear how the file is structured.</p></div>
<div class="paragraph"><p>The <code>open_window</code> function opens a standard window, which will then be put into
tiling mode by i3. If you want a floating window, use the
<code>open_floating_window</code> function. These functions accept the same parameters as
<code>X11::XCB::Window&#8594;new</code>, see the i3test documentation at TODO.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Helper function</div>
<div class="content">
<pre><code>#
# Returns the input focus after sending the given command to i3 via IPC
# and syncing with i3
#
sub focus_after {
    my $msg = shift;

    cmd $msg;
    sync_with_i3 $x;
    return $x-&gt;input_focus;
}</code></pre>
</div></div>
<div class="paragraph"><p>This section defines a helper function which will be used over and over in this
testcase. If you have code which gets executed more than once or twice
(depending on the length of your test, use your best judgement), please put it
in a function. Tests should be short, concise and clear.</p></div>
<div class="paragraph"><p>The <code>focus_after</code> function executes a command and returns the X11 focus after
the command was executed. The <code>sync_with_i3</code> command makes sure that i3 could
push its state to X11. See <a href="#i3_sync">[i3_sync]</a> to learn how this works exactly.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test assumptions</div>
<div class="content">
<pre><code>$focus = $x-&gt;input_focus;
is($focus, $bottom-&gt;id, "Latest window focused");

$focus = focus_after('focus left');
is($focus, $mid-&gt;id, "Middle window focused");</code></pre>
</div></div>
<div class="paragraph"><p>Now, we run the first two real tests. They use <code>Test::More</code>'s <code>is</code> function,
which compares two values and prints the differences if they are not the same.
After the arguments, we supply a short comment to indicate what we are testing
here. This makes it vastly more easy for the developer to spot which testcase
is the problem in case one fails.</p></div>
<div class="paragraph"><p>The first test checks that the most recently opened window is focused.
Afterwards, the command <code>focus left</code> is issued and it is verified that the
middle window now has focus.</p></div>
<div class="paragraph"><p>Note that this is not a comprehensive test of the <code>focus</code> command&#8201;&#8212;&#8201;we would
have to test wrapping, focus when using a more complex layout, focusing the
parent/child containers, etc. But that is not the point of this testcase.
Instead, we just want to know if <code>$x&#8594;input_focus</code> corresponds with what we are
expecting. If not, something is completely wrong with the test environment and
this trivial test will fail.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test that the feature does not work (yet)</div>
<div class="content">
<pre><code>#####################################################################
# Now goto a mark which does not exist
#####################################################################

my $random_mark = mktemp('mark.XXXXXX');

$focus = focus_after(qq|[con_mark="$random_mark"] focus|);
is($focus, $mid-&gt;id, "focus unchanged");</code></pre>
</div></div>
<div class="paragraph"><p>Syntax hint: The qq keyword is the interpolating quote operator. It lets you
chose a quote character (in this case the <code>|</code> character, a pipe). This makes
having double quotes in our string easy.</p></div>
<div class="paragraph"><p>In this new major section, a random mark (mark is an identifier for a window,
see "VIM-like marks" in the i3 User’s Guide) will be generated. Afterwards, we
test that trying to focus that mark will not do anything. This is important: Do
not only test that using a feature has the expected outcome, but also test that
using it without properly initializing it does no harm. This command could for
example have changed focus anyways (a bug) or crash i3 (obviously a bug).</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test that the feature does work</div>
<div class="content">
<pre><code>cmd "mark $random_mark";

$focus = focus_after('focus left');
is($focus, $top-&gt;id, "Top window focused");

$focus = focus_after(qq|[con_mark="$random_mark"] focus|);
is($focus, $mid-&gt;id, "goto worked");</code></pre>
</div></div>
<div class="paragraph"><p>Remember: Focus was on the middle window (we verified that earlier in "Test
assumptions"). We now mark the middle window with our randomly generated mark.
Afterwards, we switch focus away from the middle window to be able to tell if
focusing it via its mark will work. If the test works, the goto command seems
to be working.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test corner case</div>
<div class="content">
<pre><code># check that we can specify multiple criteria

$focus = focus_after('focus left');
is($focus, $top-&gt;id, "Top window focused");

$focus = focus_after(qq|[con_mark="$random_mark" con_mark="$random_mark"] focus|);
is($focus, $mid-&gt;id, "goto worked");</code></pre>
</div></div>
<div class="paragraph"><p>Now we test the same feature, but specifying the mark twice in the command.
This should have no effect, but let’s be sure: test it and see if things go
wrong.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test second code path</div>
<div class="content">
<pre><code>#####################################################################
# Check whether the focus command will switch to a different
# workspace if necessary
#####################################################################

my $tmp2 = fresh_workspace;

is(focused_ws(), $tmp2, 'tmp2 now focused');

cmd qq|[con_mark="$random_mark"] focus|;

is(focused_ws(), $tmp, 'tmp now focused');</code></pre>
</div></div>
<div class="paragraph"><p>This part of the test checks that focusing windows by mark works across
workspaces. It uses i3test&#8217;s <code>focused_ws</code> function to get the current
workspace.</p></div>
<div class="listingblock">
<div class="title">t/11-goto.t: Test second code path</div>
<div class="content">
<pre><code>done_testing;</code></pre>
</div></div>
<div class="paragraph"><p>The end of every testcase has to contain the <code>done_testing</code> line. This tells
<code>complete-run.pl</code> that the test was finished successfully. If it does not
occur, the test might have crashed during execution&#8201;&#8212;&#8201;some of the reasons why
that could happen are bugs in the used modules, bugs in the testcase itself or
an i3 crash resulting in the testcase being unable to communicate with i3 via
IPC anymore.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="i3_sync">5. Appendix A: The i3 sync protocol</h2>
<div class="sectionbody">
<div class="paragraph"><p>Consider the following situation: You open two windows in your testcase, then
you use <code>focus left</code> and want to verify that the X11 focus has been updated
properly. Sounds simple, right? Let’s assume you use this straight-forward
implementation:</p></div>
<div class="listingblock">
<div class="title">Racey focus testcase</div>
<div class="content">
<pre><code>my $left = open_window($x);
my $right = open_window($x);
cmd 'focus left';
is($x-&gt;input_focus, $left-&gt;id, 'left window focused');</code></pre>
</div></div>
<div class="paragraph"><p>However, the test fails. Sometimes. Apparently, there is a race condition in
your test. If you think about it, this is because you are using two different
pieces of software: You tell i3 to update focus, i3 confirms that, and then you
ask X11 to give you the current focus. There is a certain time i3 needs to
update the X11 state. If the testcase gets CPU time before X11 processed i3&#8217;s
requests, the test will fail.</p></div>
<div class="imageblock">
<div class="content">
<img src="i3-sync.png" alt="Diagram of the race condition" />
</div>
<div class="title">Figure 1. Diagram of the race condition</div>
</div>
<div class="paragraph"><p>One way to "solve" this would be to add <code>sleep 0.5;</code> after the <code>cmd</code> call.
After 0.5 seconds it should be safe to assume that focus has been updated,
right?</p></div>
<div class="paragraph"><p>In practice, this usually works. However, it has several problems:</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
This is obviously not a clean solution, but a workaround. Ugly.
</p>
</li>
<li>
<p>
On very slow machines, this might not work. Unlikely, but in different
   situations (a delay to wait for i3 to startup) the necessary time is much
   harder to guess, even for fast machines.
</p>
</li>
<li>
<p>
This <strong>wastes a lot of time</strong>. Usually, your computer is much faster than 0.5s
   to update the status. However, sometimes, it might take 0.4s, so we can’t
   make it <code>sleep 0.1</code>.
</p>
</li>
</ol></div>
<div class="paragraph"><p>To illustrate how grave the problem with wasting time actually is: Before
removing all sleeps from the testsuite, a typical run using 4 separate X
servers took around 50 seconds on my machine. After removing all the sleeps,
we achieved times of about 25 seconds. This is very significant and influences
the way you think about tests&#8201;&#8212;&#8201;the faster they are, the more likely you are
to check whether everything still works quite often (which you should).</p></div>
<div class="paragraph"><p>What I am trying to say is: Delays adds up quickly and make the test suite
less robust.</p></div>
<div class="paragraph"><p>The real solution for this problem is a mechanism which I call "the i3 sync
protocol". The idea is to send a request (which does not modify state) via X11
to i3 which will then be answered. Due to the request&#8217;s position in the event
queue (<strong>after</strong> all previous events), you can be sure that by the time you
receive the reply, all other events have been dealt with by i3 (and, more
importantly, X11).</p></div>
<div class="imageblock">
<div class="content">
<img src="i3-sync-working.png" alt="Diagram of the i3 sync solution" />
</div>
<div class="title">Figure 2. Diagram of the i3 sync solution</div>
</div>
<div class="sect2">
<h3 id="_implementation_details">5.1. Implementation details</h3>
<div class="paragraph"><p>The client which wants to sync with i3 initiates the protocol by sending a
ClientMessage to the X11 root window:</p></div>
<div class="listingblock">
<div class="title">Send ClientMessage</div>
<div class="content">
<pre><code># Generate a ClientMessage, see xcb_client_message_t
my $msg = pack "CCSLLLLLLL",
    CLIENT_MESSAGE, # response_type
    32,     # format
    0,      # sequence
    $root,  # destination window
    $x-&gt;atom(name =&gt; 'I3_SYNC')-&gt;id,

    $_sync_window-&gt;id,    # data[0]: our own window id
    $myrnd, # data[1]: a random value to identify the request
    0,
    0,
    0;

# Send it to the root window -- since i3 uses the SubstructureRedirect
# event mask, it will get the ClientMessage.
$x-&gt;send_event(0, $root, EVENT_MASK_SUBSTRUCTURE_REDIRECT, $msg);</code></pre>
</div></div>
<div class="paragraph"><p>i3 will then reply with the same ClientMessage, sent to the window specified in
<code>data[0]</code>. In the reply, <code>data[0]</code> and <code>data[1]</code> are exactly the same as in the
request. You should use a random value in <code>data[1]</code> and check that you received
the same one when getting the reply.</p></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_appendix_b_socket_activation">6. Appendix B: Socket activation</h2>
<div class="sectionbody">
<div class="paragraph"><p>Socket activation is a mechanism which was made popular by systemd, an init
replacement. It basically describes creating a listening socket before starting
a program.  systemd will invoke the program only when an actual connection to
the socket is made, hence the term socket activation.</p></div>
<div class="paragraph"><p>The interesting part of this (in the i3 context) is that you can very precisely
detect when the program is ready (finished its initialization).</p></div>
<div class="sect2">
<h3 id="_preparing_the_listening_socket">6.1. Preparing the listening socket</h3>
<div class="paragraph"><p><code>complete-run.pl</code> will create a listening UNIX socket which it will then pass
to i3. This socket will be used by i3 as an additional IPC socket, just like
the one it will create on its own. Passing the socket happens implicitly
because children will inherit the parent’s sockets when fork()ing and sockets
will continue to exist after an exec() call (unless CLOEXEC is set of course).</p></div>
<div class="paragraph"><p>The only explicit things <code>complete-run.pl</code> has to do is setting the <code>LISTEN_FDS</code>
environment variable to the number of sockets which exist (1 in our case) and
setting the <code>LISTEN_PID</code> environment variable to the current process ID. Both
variables are necessary so that the program (i3) knows how many sockets it
should use and if the environment variable is actually intended for it. i3 will
then start looking for sockets at file descriptor 3 (since 0, 1 and 2 are used
for stdin, stdout and stderr, respectively).</p></div>
<div class="paragraph"><p>The actual Perl code which sets up the socket, fork()s, makes sure the socket
has file descriptor 3 and sets up the environment variables follows (shortened
a bit):</p></div>
<div class="listingblock">
<div class="title">Setup socket and environment</div>
<div class="content">
<pre><code>my $socket = IO::Socket::UNIX-&gt;new(
    Listen =&gt; 1,
    Local =&gt; $args{unix_socket_path},
);

my $pid = fork;
if ($pid == 0) {
    $ENV{LISTEN_PID} = $$;
    $ENV{LISTEN_FDS} = 1;

    # Only pass file descriptors 0 (stdin), 1 (stdout),
    # 2 (stderr) and 3 (socket) to the child.
    $^F = 3;

    # If the socket does not use file descriptor 3 by chance
    # already, we close fd 3 and dup2() the socket to 3.
    if (fileno($socket) != 3) {
        POSIX::close(3);
        POSIX::dup2(fileno($socket), 3);
    }

    exec "/usr/bin/i3";
}</code></pre>
</div></div>
</div>
<div class="sect2">
<h3 id="_waiting_for_a_reply">6.2. Waiting for a reply</h3>
<div class="paragraph"><p>In the parent process, we want to know when i3 is ready to answer our IPC
requests and handle our windows. Therefore, after forking, we immediately close
the listening socket (i3 will handle this side of the socket) and connect to it
(remember, we are talking about a named UNIX socket) as a client. This connect
call will immediately succeed because the kernel buffers it. Then, we send a
request (of type GET_TREE, but that is not really relevant). Writing data to
the socket will also succeed immediately because, again, the kernel buffers it
(only up to a certain amount of data of course).</p></div>
<div class="paragraph"><p>Afterwards, we just blockingly wait until we get an answer. In the child
process, i3 will setup the listening socket in its event loop. Immediately
after actually starting the event loop, it will notice a new client connecting
(the parent process) and handle its request. Since all initialization has been
completed successfully by the time the event loop is entered, we can now assume
that i3 is ready.</p></div>
</div>
<div class="sect2">
<h3 id="_timing_and_conclusion">6.3. Timing and conclusion</h3>
<div class="paragraph"><p>A beautiful feature of this mechanism is that it does not depend on timing. It
does not matter when the child process gets CPU time or when the parent process
gets CPU time. On heavily loaded machines (or machines with multiple CPUs,
cores or unreliable schedulers), this makes waiting for i3 much more robust.</p></div>
<div class="paragraph"><p>Before using socket activation, we typically used a <code>sleep(1)</code> and hoped that
i3 was initialized by that time. Of course, this breaks on some (slow)
computers and wastes a lot of time on faster computers. By using socket
activation, we decreased the total amount of time necessary to run all tests
(72 files at the time of writing) from &gt; 100 seconds to 16 seconds. This makes
it significantly more attractive to run the test suite more often (or at all)
during development.</p></div>
<div class="paragraph"><p>An alternative approach to using socket activation is polling for the existence
of the IPC socket and connecting to it. While this might be slightly easier to
implement, it wastes CPU time and is considerably uglier than this solution
:). After all, <code>lib/SocketActivation.pm</code> contains only 54 SLOC.</p></div>
</div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
 2017-09-24 19:21:26 CEST
</div>
</div>
</body>
</html>