Reftests (reference tests)

A reftest are one of the testing format used in W3C and browser vendors for testing features that add visual effects to a page such as CSS and SVG. A reftest are madte of two (or more) files: a test case made using features to test, and reference file(s) made using widely-implemented-and-deployed features (e.g. CSS2). On conforming implementation the reference and the test case will visually match.

For ease of testing, references often use simple geometric shapes such as green square.

The Ahem font

In order to test CSS features, it is required to install the Ahem font in a testing system. The Ahem font only contains simple geometric glyphs such as a square and rectangles. With those simple glyphs it is easy to craft references and test cases. Here's a design specification of Ahem quoting from the README file:

The font's em square is exactly square.
Its ascent and descent is exactly the size of the em square. This
means that the font's extent is exactly the same as its line-height,
meaning that it can be exactly aligned with padding, borders, margins,
and so forth.

The font's alphabetic baseline is 0.2em above its bottom, and 0.8em
below its top. The font has an x-height of 0.8em.

The font has four glyphs:

  'X' U+0058 A square exactly 1em in height and width.

  'p' U+0070 A rectangle exactly 0.2em high, 1em wide, and aligned so
             that its top is flush with the baseline.

  'É' U+00C9 A rectangle exactly 0.8em high, 1em wide, and aligned so
             that its bottom is flush with the baseline.

  ' ' U+0020 A transparent space exactly 1em high and wide.

Most other US-ASCII characters in the font have the same glyph as X.

Glyphs that can be used as an alternative to Ahem glyphs

In the prior section we demonstrate how we can test text-combine-upright using Ahem. In some cases tests can be written only using Ahem, but there are cases where we need additional glyphs.

• A black square is a 1em × 1em square glyph; it is pretty much the same as Ahem's glyph for x
• A blank of 1em × 1em

It might be okay with just using Ahem if tests needing black square only contain codepoints in ASCII-range.

Glyphs to check whether a character is rotated or not

text-combine-upright combines a span of text horizontally and make the resulting compression rendered upright, even when the element has just one character.

If the element contains two or more characters, Ahem can be used to check if user agents support composition effect. However, if it is just a single character, Ahem cannot be used since most character in Ahem is a 1em square and thus cannot figure out whether the resulting coposition is rendered upright or not.

Therefore, we need two glyphs where:

• their widths and heights are 1em
• one matches another visually when another rotated 90° counterclockwise

Yes, I stole the glyph idea from CSS Orientation Test font.

<style>
body {
  writing-mode: vertical-rl;
  font-family: SomeFont;
}
.test {
  text-combine-upright: all;
}
.reference {
  text-orientaiton: upright;
}
</style>

<p class="test">A</p>
<p class="reference">B</p>

These glyphs are not directly related to TCY so perhaps it should go to CSS Orientation Test font.

Glyph to check whether the composition has no text decoration inside it

In Section 9.1.2 Layout Rules it says:

When combining text as for text-combine-upright: all, the glyphs of the combined text are composed horizontally (ignoring letter-spacing and any forced line breaks, but using the specified font settings), similar to the contents of an inline-box with a horizontal writing mode and a line-height of 1em.

Later in the section it says:

For other text layout purposes, e.g. emphasis marks, text-decoration, spacing, etc. the resulting composition is treated as a single glyph representing the Object Replacement Character U+FFFC.

So we need to test if user agents ignore spacing, emphasis marks, decorations applied to each character inside the composition but rather apply those effects to the resulting composition, treating as if it were a single characeter.

The test should be written to check if there is no emphasis mark or ruby character inside the composition. To make this easy to observe, we need a glyph where:

• it does not overlap ruby text, emphasis mark, or any decoration

The following is an idea for such glyph: it draws overline and underline but does not do so in between them.

With such glyph, the test would be written as:

<style>
.test {
  writing-mode: vertical-rl;
  font-family: TCU-test;
}
.tcy {
  text-combine-upright: all;
  text-emphasis: sesame;
}
</style>

<p><span class="tcy">AB</span></p>

This will make the test reftestable.

This glyph cannot cover the assertion the resulting composition is treated as a single glyph representing the Object Replacement Character U+FFFC. Test authors are not sure if that will cause a visual effect that can be tested.

Glyphs that is larger than 1em square

In 9.1.2 Layout Rules the spec says:

The effective size of the composition is assumed to be 1em square; anything outside the square is not measured for layout purposes.

Hence, we need a glyph where:

• its size is greater than 1em square

By using this glyph with two square glyphs we can make a 3em square.

<style>
body {
  writing-mode: vertical-rl;
  font-family: SomeFont;
}
.tcy {
  text-combine-upright: all;
}
.reference {
  font-size: 3em;
  margin: 2em 0;
}
</style>

<div class="test">
  <p>x<span class="tcy">H</span>x</p>
  <p class="reference">x</p>
</div>

TBD

In 9.1.2 Layout Rules the spec says:

The UA should center the glyphs horizontally and vertically within the measured 1em square.

work in progress. test authors are struggling with the look of shape(s) to use to create a reftest

Glyphs to check whether nwid OpenType features are used

In 9.1.3 Compression Rules the spec says:

OpenType implementations must use width-specific variants (OpenType features hwid/twid/qwid; other glyph-width features such as fwid or pwid are not included) to compress text in cases where those variants are available for all characters in the composition.

In order to test this, we need glyphs for hwid, twid, and qwid; they need to be distinguishable from each other and also distinguishable from fwid/pwid glyphs. For the use in reference, we also need "extended" versions of hwid/twid/qwid glyphs; the widths of the extended version are all 1em.

A double stripe

Used for the hwid feature.

A triple stripe

Used for the twid feature.

A quadruple stripe

Used for the qwid feature.

There might be cases where a character inside TCY does not have all features, the font need to have characters that only have (or miss) hwid/twid/qwid feature. Tests need to check combination of characters with different feature sets.

Since the processing details of compression rules are up to User Agents, when the resulting glyphs from composition differs from each other, the test can only be verified using negative references.

Glyphs to check the optional processing regarding U+6C34

The last paragraph in 9.1.3 Compression Rules says:

In some fonts, the ideographic glyphs are given a compressed design such that they are 1em wide but shorter than 1em tall. To accommodate such fonts, the UA may vertically scale the the composition to match the advance height of 水 U+6C34.

We need two glyphs:

• a glyph of horizontal rectangle (e.g. 1em × .8em), mapping to 0x6C34
• a glyph of thinner horizontal rectangle (e.g. 1em × .3em), mapping to a certain codepoint

There is a spec issue.

Font A TODO: Name

Font A contains all glyphs except ones for checking width-related features.

Unless otherwise specified, glyphs are mapped to both in horizontal and in vetical (using the vert feature) modes.

Fonts to test width-variant features

These fonts test the width-related features. One font contains only hwid feature, and another contains all the five features (hwid, twid, qwid, fwid, and pwid).

Below is a table for the latter font; the former (only contains hwid feature) lacks other four features.