tree: 2e0874203b0859ba33fb3f04699aff55aec24927 [path history] [tgz]

keyboards/test/README.md

Technical Preview: CLDR Keyboard Test Data

Contents of CLDR Keyboard Test Data

Keyboard Test Data
Copyright and License

Keyboard Test Data

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

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

Sample test data files are located in the keyboards/test subdirectory.

The following describes the structure of a keyboard test file.

Test Doctype

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE keyboardTest3 SYSTEM "../dtd/ldmlKeyboardTest3.dtd">

The top level element is named keyboardTest.

Test Element: keyboardTest

This is the top level element.

Attribute: conformsTo (required)

The conformsTo attribute value here is a fixed value of techpreview, because the test data is a Technical Preview.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE keyboardTest3 SYSTEM "../dtd/ldmlKeyboardTest3.dtd">
<keyboardTest3 conformsTo="techpreview">
    …
</keyboardTest3>

Test Element: info

Attribute: author

This freeform attribute value allows for description of the author or authors of this test file.

Attribute: keyboard (required)

This attribute value specifies the keyboard’s file name, such as fr-t-k0-azerty.xml.

Attribute: name (required)

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

Example

<info keyboard="fr-t-k0-azerty.xml" author="Team Keyboard" name="fr-test" />

Test Element: repertoire

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

Attribute: name (required)

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

Attribute: type

This attribute value is one of the following:

type	Meaning
default	This is the default, indicates that any gesture or keystroke may be used to generate each character
simple	Each of the characters must be typeable by simple single keystrokes without needing any gestures.
gesture	The characters are typeable by use of any gestures such as flicks, long presses, or multiple taps.
flick	The characters are typeable by use of any `flick` element.
longPress	The characters are typeable by use of any `longPress` value.
multiTap	The characters are typeable by use of any `multiTap` value.
hardware	The characters are typeable by use of any simple keystrokes on any hardware layout.

Attribute: chars (required)

This attribute value specifies a list of characters in UnicodeSet format, which is specified in UTS #35 Part One.

Example

<repertoire chars="[a b c d e \u{22}]" type="default" />

<!-- taken from CLDR's common/main/fr.xml main exemplars - indicates that all of these characters should be reachable without requiring a gesture.
Note that the 'name' is arbitrary. -->
<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" />

<!-- 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.-->
<repertoire name="cldr-fr-auxiliary" chars="[á å ä ã ā ć ē í ì ī ĳ ñ ó ò ö õ ø ř š ſ ß ú ǔ]" type="gesture" />

Note: CLDR’s extensive exemplar set 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.

Test Element: tests

This element specifies a particular suite of <test> elements.

Attribute: name (required)

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

Example

<tests name="key-tests">
    <test name="key-test">
        …
    </test>
    <test name="gestures-test">
        …
    </test>
</tests>
<tests name="transform tests">
    <test name="transform test">
        …
    </test>
</tests>

Test Element: test

This attribute value specifies a specific isolated regression test. Multiple test elements do not interact with each other.

The order of child elements is significant, with cumulative effects: they must be processed from first to last.

Attribute: name (required)

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

Example

<info keyboard="fr-t-k0-azerty.xml" author="Team Keyboard" name="fr-test" />

Test Element: startContext

This 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 ("").

Attribute: to (required)

Specifies the starting context. This text may be escaped with \u notation, see Escaping.

Example

<startContext to="abc\u{0022}"/>

Test Element: keystroke

This element contains a single keystroke or other gesture event, identified by a particular key element.

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

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

When a key is found, processing continues with the transform and other elements before updating the test output buffer.

Attribute: key (required)

This attribute value specifies a key by means of the key’s id attribute.

Attribute: flick

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

Attribute: longPress

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

Attribute: tapCount

This 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>. The minimum tapCount is 2.

Example

<keystroke key="q"/>
<keystroke key="doublequote"/>
<keystroke key="s" flick="nw se"/>
<keystroke key="e" longPress="1"/>
<keystroke key="E" tapCount="2"/>

Test Element: emit

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

Processing of the specified text continues with the transform and other elements before updating the test output buffer.

Attribute: to (required)

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

This attribute value may be escaped with \u notation, see Escaping.

Example

<emit to="s"/>

Test Element: backspace

This element contains a backspace action, as if the user typed the backspace key

Example

<backspace/>

Test Element: check

This element contains a check on the current output buffer.

Attribute: result (required)

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

Example

<check result="abc\u{0022}s\u{0022}•éÈ"/>

Test Examples


<test name="spec-sample">
    <startContext to="abc\u{0022}"/>
    <!-- simple, key specified by to -->
    <emit to="s"/>
    <check result="abc\u{0022}s"/>
    <!-- simple, key specified by id -->
    <keystroke key="doublequote"/>
    <check result="abc\u{0022}s\u{0022}"/>
    <!-- flick -->
    <keystroke key="s" flick="nw se"/>
    <check result="abc\u{0022}s\u{0022}•"/>
    <!-- longPress -->
    <keystroke key="e" longPress="1"/>
    <check result="abc\u{0022}s\u{0022}•é"/>
    <!-- multiTap -->
    <keystroke key="E" tapCount="2"/>
    <check result="abc\u{0022}s\u{0022}•éÈ"/>
</test>

Copyright and License

See the top level README.md