test/shaping/README.md

   1 Adding tests
   2 ============
   3
   4 You can test shaping of a unicode sequence against a font like this:
   5 ```sh
   6 $ ./hb-unicode-encode 41 42 43 627 | ../../util/hb-shape font.ttf
   7 ```
   8 assuming an in-tree build.  The 41 42 43 627 here is a sequence of
   9 Unicode codepoints: U+0041,0042,0043,0627.  When you are happy with
  10 the shape results, you can use the `record-test.sh` script to add
  11 this to the test suite.  `record-test.sh` requires `pyftsubset` to
  12 be installed.  You can get `pyftsubset` by installing
  13 FontTools from <https://github.com/behdad/fonttools>.
  14
  15 To use `record-test.sh`, just put it right before the `hb-shape` invocation:
  16 ```sh
  17 $ ./hb-unicode-encode 41 42 43 627 | ./record-test.sh ../../util/hb-shape font.ttf
  18 ```
  19 what this does is:
  20   * Subset the font for the sequence of Unicode characters requested,
  21   * Compare the `hb-shape` output of the original font versus the subset
  22     font for the input sequence,
  23   * If the outputs differ, perhaps it is because the font does not have
  24     glyph names; it then compares the output of `hb-view` for both fonts.
  25   * If the outputs differ, recording fails.  Otherwise, it will move the
  26     subset font file into `data/in-house/fonts` and name it after its
  27     hash, and print out the test case input, which you can then redirect
  28     to an existing or new test file in `data/in-house/tests` using `-o`,
  29     e.g.:
  30 ```sh
  31 $ ./hb-unicode-encode 41 42 43 627 | ./record-test.sh -o data/in-house/tests/test-name.test ../../util/hb-shape font.ttf
  32 ```
  33
  34 If you created a new test file, add it to `data/in-house/Makefile.sources`
  35 so it is run.  Check that `make check` does indeed run it, and that the
  36 test passes.  When everything looks good, `git add` the new font as well
  37 as the new test file if you created any.  You can see what new files are
  38 there by running `git status data/in-house`.  And commit!
  39
  40 *Note!*  Please only add tests using Open Source fonts, preferably under
  41 OFL or similar license.