• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Technical Preview: CLDR Keyboard Test Data
2
3## <a name="Contents" href="#Contents">Contents of CLDR Keyboard Test Data</a>
4
5* [Keyboard Test Data](#keyboard-test-data)
6  * [Test Doctype](#test-doctype)
7  * [Test Element: keyboardTest](#test-element-keyboardtest)
8  * [Test Element: info](#test-element-info)
9  * [Test Element: repertoire](#test-element-repertoire)
10  * [Test Element: tests](#test-element-tests)
11  * [Test Element: test](#test-element-test)
12  * [Test Element: startContext](#test-element-startcontext)
13  * [Test Element: keystroke](#test-element-keystroke)
14  * [Test Element: emit](#test-element-emit)
15  * [Test Element: backspace](#test-element-backspace)
16  * [Test Element: check](#test-element-check)
17  * [Test Examples](#test-examples)
18* [Copyright and License](#copyright-and-license)
19
20## Keyboard Test Data
21
22> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
23
24Keyboard Test Data allows the keyboard author to provide regression test data to validate the repertoire and behavior of a keyboard. Tooling can run these regression tests against an implementation, and can also be used as part of the development cycle to validate that keyboard changes do not deviate from expected behavior.  In the interest of complete coverage, tooling could also indicate whether all keys and gestures in a layout are exercised by the test data.
25
26Test data files have a separate DTD, named `ldmlKeyboardTest3.dtd`.  Note that multiple test data files can refer to the same keyboard. Test files should be named similarly to the keyboards which they test, such as `fr_test.xml` to test `fr.xml`.
27
28Sample test data files are located in the `keyboards/test` subdirectory.
29
30The following describes the structure of a keyboard test file.
31
32### Test Doctype
33
34> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
35
36```xml
37<?xml version="1.0" encoding="UTF-8"?>
38<!DOCTYPE keyboardTest3 SYSTEM "../dtd/ldmlKeyboardTest3.dtd">
39```
40
41The top level element is named `keyboardTest`.
42
43### Test Element: keyboardTest
44
45> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
46
47> <small>
48>
49> Children: [info](#test-element-info), [repertoire](#test-element-repertoire), [_special_](tr35.md#special), [tests](#test-element-tests)
50> </small>
51
52This is the top level element.
53
54_Attribute:_ `conformsTo` (required)
55
56The `conformsTo` attribute value here is a fixed value of `techpreview`, because the test data is a Technical Preview.
57
58```xml
59<?xml version="1.0" encoding="UTF-8"?>
60<!DOCTYPE keyboardTest3 SYSTEM "../dtd/ldmlKeyboardTest3.dtd">
61<keyboardTest3 conformsTo="techpreview">
62    …
63</keyboardTest3>
64```
65
66### Test Element: info
67
68> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
69
70> <small>
71>
72> Parents: [keyboardTest](#test-element-keyboardtest)
73>>
74> Occurrence: Required, Single
75> </small>
76
77_Attribute:_ `author`
78
79This freeform attribute value allows for description of the author or authors of this test file.
80
81_Attribute:_ `keyboard` (required)
82
83This attribute value specifies the keyboard’s file name, such as `fr-t-k0-azerty.xml`.
84
85_Attribute:_ `name` (required)
86
87This attribute value specifies a name for this overall test file. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components.
88
89**Example**
90
91```xml
92<info keyboard="fr-t-k0-azerty.xml" author="Team Keyboard" name="fr-test" />
93```
94
95### Test Element: repertoire
96
97> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
98
99> <small>
100>
101> Parents: [keyboardTest](#test-element-keyboardtest)
102>
103> Children: _none_
104>
105> Occurrence: Optional, Multiple
106> </small>
107
108This element contains a repertoire test, to validate the available characters and their reachability. This test ensures that each of the specified characters is somehow typeable on the keyboard, after transforms have been applied. The characters in the repertoire will be matched against the complete set of possible generated outputs, post-transform, of all keys on the keyboard.
109
110_Attribute:_ `name` (required)
111
112This attribute value specifies a unique name for this repertoire test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components.
113
114_Attribute:_ `type`
115
116This attribute value is one of the following:
117
118|  type     | Meaning                                                                                                  |
119|-----------|----------------------------------------------------------------------------------------------------------|
120| default   | This is the default, indicates that _any_ gesture or keystroke may be used to generate each character    |
121| simple    | Each of the characters must be typeable by simple single keystrokes without needing any gestures.        |
122| gesture   | The characters are typeable by use of any gestures such as flicks, long presses, or multiple taps.       |
123| flick     | The characters are typeable by use of any `flick` element.                                               |
124| longPress | The characters are typeable by use of any `longPress` value.                                             |
125| multiTap  | The characters are typeable by use of any `multiTap` value.                                              |
126| hardware  | The characters are typeable by use of any simple keystrokes on any hardware layout.                      |
127
128_Attribute:_ `chars` (required)
129
130This attribute value specifies a list of characters in UnicodeSet format, which is specified in [UTS #35 Part One](tr35.md#Unicode_Sets).
131
132**Example**
133
134```xml
135<repertoire chars="[a b c d e \u{22}]" type="default" />
136
137<!-- taken from CLDR's common/main/fr.xml main exemplars - indicates that all of these characters should be reachable without requiring a gesture.
138Note that the 'name' is arbitrary. -->
139<repertoire name="cldr-fr-main" chars="[a à â æ b c ç d e é è ê ë f g h i î ï j k l m n o ô œ p q r s t u ù û ü v w x y ÿ z]" type="simple" />
140
141<!-- taken from CLDR's common/main/fr.xml auxiliary exemplars - indicates that all of these characters should be reachable even if a gesture is required.-->
142<repertoire name="cldr-fr-auxiliary" chars="[á å ä ã ā ć ē í ì ī ij ñ ó ò ö õ ø ř š ſ ß ú ǔ]" type="gesture" />
143
144```
145
146Note: CLDR’s extensive [exemplar set](tr35-general.md#Character_Elements) data may be useful in validating a language’s repertoire against a keyboard. Tooling may wish to make use of this data in order to suggest recommended repertoire values for a language.
147
148### Test Element: tests
149
150> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
151
152
153> <small>
154>
155> Parents: [keyboardTest](#test-element-keyboardtest)
156>
157> Children: [_special_](tr35.md#special), [test](#test-element-test)
158>
159> Occurrence: Optional, Multiple
160> </small>
161
162This element specifies a particular suite of `<test>` elements.
163
164_Attribute:_ `name` (required)
165
166This attribute value specifies a unique name for this suite of tests. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components.
167
168**Example**
169
170```xml
171<tests name="key-tests">
172    <test name="key-test">
173        …
174    </test>
175    <test name="gestures-test">
176        …
177    </test>
178</tests>
179<tests name="transform tests">
180    <test name="transform test">
181        …
182    </test>
183</tests>
184```
185
186### Test Element: test
187
188> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
189
190
191> <small>
192>
193> Parents: [tests](#test-element-tests)
194>
195> Children: [startContext](#test-element-startcontext), [emit](#test-element-emit), [keystroke](#test-element-keystroke), [backspace](#test-element-backspace), [check](#test-element-check), [_special_](tr35.md#special)
196>
197> Occurrence: Required, Multiple
198> </small>
199
200This attribute value specifies a specific isolated regression test. Multiple test elements do not interact with each other.
201
202The order of child elements is significant, with cumulative effects: they must be processed from first to last.
203
204_Attribute:_ `name` (required)
205
206This attribute value specifies a unique name for this particular test. These names could be output to the user during test execution, used to summarize success and failure, or used to select or deselect test components.
207
208**Example**
209
210```xml
211<info keyboard="fr-t-k0-azerty.xml" author="Team Keyboard" name="fr-test" />
212```
213
214### Test Element: startContext
215
216> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
217
218This element specifies pre-existing text in a document, as if prior to the user’s insertion point. This is useful for testing transforms and reordering. If not specified, the startContext can be considered to be the empty string ("").
219
220> <small>
221>
222> Parents: [test](#test-element-test)
223>
224> Children: _none_
225>
226> Occurrence: Optional, Single
227> </small>
228
229_Attribute:_ `to` (required)
230
231Specifies the starting context. This text may be escaped with `\u` notation, see [Escaping](#escaping).
232
233**Example**
234
235```xml
236<startContext to="abc\u{0022}"/>
237```
238
239
240### Test Element: keystroke
241
242> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
243
244
245> <small>
246>
247> Parents: [test](#test-element-test)
248>
249> Children: _none_
250>
251> Occurrence: Optional, Multiple
252> </small>
253
254This element contains a single keystroke or other gesture event, identified by a particular key element.
255
256Optionally, one of the gesture attributes, either `flick`, `longPress`, or `tapCount` may be specified. If none of the gesture attribute values are specified, then a regular keypress is effected on the key.  It is an error to specify more than one gesture attribute.
257
258If a key is not found, or a particular gesture has no definition, the output should be behave as if the user attempted to perform such an action.  For example, an unspecified `flick` would result in no output.
259
260When a key is found, processing continues with the transform and other elements before updating the test output buffer.
261
262_Attribute:_ `key` (required)
263
264This attribute value specifies a key by means of the key’s `id` attribute.
265
266_Attribute:_ `flick`
267
268This attribute value specifies a flick gesture to be performed on the specified key instead of a keypress, such as `e` or `nw se`. This value corresponds to the `directions` attribute value of the [`<flickSegment>`](#element-flicksegment) element.
269
270_Attribute:_ `longPress`
271
272This attribute value specifies that a long press gesture should be performed on the specified key instead of a keypress. For example, `longPress="2"` indicates that the second character in a longpress series should be chosen. `longPress="0"` indicates that the `longPressDefault` value, if any, should be chosen. This corresponds to `longPress` and `longPressDefault` on [`<key>`](#element-key).
273
274_Attribute:_ `tapCount`
275
276This attribute value specifies that a multi-tap gesture should be performed on the specified key instead of a keypress. For example, `tapCount="3"` indicates that the key should be tapped three times in rapid succession. This corresponds to `multiTap` on [`<key>`](#element-key). The minimum tapCount is 2.
277
278**Example**
279
280```xml
281<keystroke key="q"/>
282<keystroke key="doublequote"/>
283<keystroke key="s" flick="nw se"/>
284<keystroke key="e" longPress="1"/>
285<keystroke key="E" tapCount="2"/>
286```
287
288### Test Element: emit
289
290> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
291
292
293> <small>
294>
295> Parents: [test](#test-element-test)
296>
297> Children: _none_
298>
299> Occurrence: Optional, Multiple
300> </small>
301
302This element also contains an input event, except that the input is specified in terms of textual value rather than key or gesture identity. This element is particularly useful for testing transforms.
303
304Processing of the specified text continues with the transform and other elements before updating the test output buffer.
305
306_Attribute:_ `to` (required)
307
308This attribute value specifies a string of output text representing a single keystroke or gesture. This string is intended to match the output of a `key`, `flick`, `longPress` or `multiTap` element or attribute.
309Tooling should give a hint if this attribute value does not match at least one keystroke or gesture. Note that the specified text is not injected directly into the output buffer.
310
311This attribute value may be escaped with `\u` notation, see [Escaping](#escaping).
312
313**Example**
314
315```xml
316<emit to="s"/>
317```
318
319
320### Test Element: backspace
321
322> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
323
324
325> <small>
326>
327> Parents: [test](#test-element-test)
328>
329> Children: _none_
330>
331> Occurrence: Optional, Multiple
332> </small>
333
334This element contains a backspace action, as if the user typed the backspace key
335
336**Example**
337
338```xml
339<backspace/>
340```
341
342### Test Element: check
343
344> **NOTE**: The Keyboard Test Data format is a technical preview, it is subject to revision in future versions of CLDR.
345
346
347> <small>
348>
349> Parents: [test](#test-element-test)
350>
351> Children: _none_
352>
353> Occurrence: Optional, Multiple
354> </small>
355
356This element contains a check on the current output buffer.
357
358_Attribute:_ `result` (required)
359
360This attribute value specifies the expected resultant text in a document after processing this event and all prior events, and including any `startContext` text.  This text may be escaped with `\u` notation, see [Escaping](#escaping).
361
362**Example**
363
364```xml
365<check result="abc\u{0022}s\u{0022}•éÈ"/>
366```
367
368
369### Test Examples
370
371```xml
372
373<test name="spec-sample">
374    <startContext to="abc\u{0022}"/>
375    <!-- simple, key specified by to -->
376    <emit to="s"/>
377    <check result="abc\u{0022}s"/>
378    <!-- simple, key specified by id -->
379    <keystroke key="doublequote"/>
380    <check result="abc\u{0022}s\u{0022}"/>
381    <!-- flick -->
382    <keystroke key="s" flick="nw se"/>
383    <check result="abc\u{0022}s\u{0022}•"/>
384    <!-- longPress -->
385    <keystroke key="e" longPress="1"/>
386    <check result="abc\u{0022}s\u{0022}•é"/>
387    <!-- multiTap -->
388    <keystroke key="E" tapCount="2"/>
389    <check result="abc\u{0022}s\u{0022}•éÈ"/>
390</test>
391```
392
393## Copyright and License
394
395See the top level [README.md](../../README.md#copyright--licenses)
396