Fonts Tests
===========

Common test repository for Fedora fonts packages.
Use ``tmt`` to run tests easily:

        tmt run

How to create
-------------

1. ``tmt init`` at a package repository
2. ``tmt plan create -t mini /plans/<sub package name>``
3. Create ``plans/<sub package name>.fmf`` with the following template

or

1. ``dnf install fontrpmspec``
2. ``fontrpmspec-gentmt <path to package repository>``
3. Review generated fmf plan files under ``<path to package repository>/plans``

Template
--------

::

  summary: Fonts related tests
  discover:
    how: fmf
    url: https://src.fedoraproject.org/tests/fonts
  execute:
    how: tmt
  environment:
    PACKAGE: <package name to test>
    FONT_ALIAS: <generic alias to test such as sans-serif, serif, monospace>
    FONT_FAMILY: <family name for this font>
    FONT_LANG: <comma-separated list of language identifier>
    FONT_WIDTH: <width name to test>

Available test cases
--------------------

- Default fonts

  A test case to check if the targeted font package affects various default
  generic alias selection.
  The following parameters are used in this test:

  - DEFAULT_SANS (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for sans-serif on a certain language.
    set ``2`` if the result isn't yet determined. it may be helpful to deal with
    minor languages.

  - DEFAULT_SERIF (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for serif on a certain language.
    set ``2`` if the result isn't yet determined. it may be helpful to deal with
    minor languages.

  - DEFAULT_MONO (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for monospace on a certain language.
    set ``2`` if the result isn't yet determined. it may be helpful to deal with
    minor languages.

  - DEFAULT_EMOJI (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for emoji.

  - DEFAULT_MATH (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for math.

  - DEFAULT_SYSTEMUI (optional)

    default value is ``0``. set ``1`` if the targeted font package is supposed to
    be a default font for system-ui.

  - FONT_FAMILY
  - FONT_LANG (optional)

    default value is ``en``. en will be used for ``und-zsye`` (emoji) and ``und-zmth`` (math).
    If you set ``-`` (hyphen) as a language, ``en`` will be used instead.

- Generic alias

  A test case to check if the expected generic alias is properly assigned.
  The following parameters are used in this test:

  - PACKAGE
  - FONT_ALIAS (optional)

    default value is ``sans-serif``

  - FONT_FAMILY
  - FONT_LANG (optional)

    default value is ``en``.
    If you set ``-`` (hyphen) as a language, this test will be skipped.
    This may be somewhat useful when you don't want to test a specific font only.

  - FONT_WIDTH (optional)

    default value is ``normal``.

  - FONT_CONF_EXCLUDE_FILES (optional)

    Set a regular expression [1]_ to skip some bogus fontconfig config files::

      Example

        FONT_CONF_EXCLUDE_FILES: .*-bad  # to skip all fontconfig files containing -bad word in a filename

- Language coverage

  A test case to check if a font in PACKAGE has sufficient coverage for FONT_LANG.
  The following parameters are used in this test:

  - PACKAGE
  - FONT_LANG (optional)

    default value is ``en``.
    If you set ``-`` (hyphen) as a language, this test will be skipped.
    This may be somewhat useful when you don't want to test a specific font only.

  - FONT_LANG_EXCLUDE_FILES (optional)

    Set a regular expression [1]_ to skip some bogus font files::

      Example

        FONT_LANG_EXCLUDE_FILES: .*-Bold  # to skip all font files containing -Bold word in a filename

  - FONT_LANG_INDEXES (optional)

    A comma-separated list of index numbers to check the language coverage for a specific face only.

- Validate family name

  A test case to check if a given FONT_FAMILY is really valid for this package.
  This is to prevent some human error.
  The following parameters are used in this test:

  - PACKAGE
  - FONT_FAMILY
  - FONT_VALIDATE_EXCLUDE_FILES (optional)

    Set a regular expression [1]_ to skip some bogus font files::

      Example

        FONT_VALIDATE_EXCLUDE_FILES: .*-Bold  # to skip all font files containing -Bold word in a filename

  - FONT_VALIDATE_INDEXES (optional)

    A comma-separated list of index numbers to validate a specific face only.

.. [1] compatible with Extended Regular Expression in grep. see grep(1) for more details.

FAQ
---

- My font package doesn't have an own config.

  You can add ``generic_alias`` into ``exclude`` at ``discover`` section like::

    discover:
      how: fmf
      url: https://src.fedoraproject.org/tests/fonts
      exclude:
        - generic_alias

- My font package doesn't have particular language coverage.

  You can add ``lang_coverage`` and ``default_fonts`` into ``exclude`` at ``discover`` section like::

    discover:
      how: fmf
      url: https://src.fedoraproject.org/tests/fonts
      exclude:
        - lang_coverage
        - default_fonts

- Unable to run ``tmt run`` locally.

  prepare install plugin in tmt support installing local rpms:

	tmt run --all prepare --insert --how install --package /path/to/the/package.rpm

  or

	tmt run --all prepare --insert --how install --directory /path/to/the/directory/with/packages

- How to deal with TrueType/OpenType Collection format?

  This test sets are basically supposed to have one plan per sub-packages.
  However, for some limitation in the implementation, it can't be done for
  TTC/OTC. So you may want to have separate plan file per faces in TTC/OTC.
  See `adobe-source-han-mono-fonts package <https://src.fedoraproject.org/rpms/adobe-source-han-mono-fonts/blob/rawhide/f/plans>`_ for example.

- I saw ``No space left on device`` error during testing.
- Too many sub packages. How can this be simplified?

  You can put required variables into a file on plans directory like the following format::

    # comment
    # version=2
    PACKAGE;FONT_ALIAS;FONT_LANG;FONT_WIDTH;FONT_FAMILY;DEFAULT_SANS;DEFAULT_SERIF;DEFAULT_MONO;DEFAULT_EMOJI;DEFAULT_MATH;DEFAULT_SYSTEMUI;FONT_LANG_EXCLUDE_FILES;FONT_VALIDATE_EXCLUDE_FILES;FONT_CONF_EXCLUDE_FILES;FONT_VALIDATE_INDEXES;FONT_LANG_INDEXES;
    ...

  And then set a filename to VARLIST like::

    environment:
      - VARLIST: <srpm-name>.list

  Note that the line of ``# version=2`` is a magic word. If you drop it, the format will be different with the above.

  See `google-noto-fonts package <https://src.fedoraproject.org/rpms/google-noto-fonts/blob/rawhide/f/plans>`_ for example.