Testing

Unit tests are to be run from the source distribution.

The most comfortable method is to run the tests via make. The provided Makefile is a BSD-style makefile. GNU make probably does not work.

Note

For Windows see this section.

Targets:

test

Run all the “normal” unit tests.

Runs with the user’s current locale; some test scripts are called with some additional locales also.

test-extra

Run a test script that generates message digests for a file that has an invalid UTF-8 byte sequence. This file is created and removed dynamically and not part of the test data in the source distribution.

This script is run several times with most available locales on the system. Ignored are only codesets that are not available as Python codecs.

test-locale-props

Check some assumptions and observations with regard to Python and locales.

test-all

All of the above tests in a single target

Environment variables that affect tests:

PYTHON

The command to run the Python executable that is used for all tests.

Default: python

SKIP-LONG-TESTS

If this variable is set then all test scripts skip long-running tests.

TEST-TMPDIR

This directory will be created and destroyed for each test. Its parent directory must exist already.

Default: tests/data/_tmp

Windows

Currently all tests are targeted to POSIX systems. Test data in the tests/data/ folder contains (POSIX) symbolic links.

Running all or some test scripts on Windows using the make targets is not supported.

See also

• https://docs.python.org/3/library/locale.html

• https://vstinner.github.io/python3-locales-encodings.html

• https://en.wikipedia.org/wiki/Locale_(computer_software)

• https://learn.microsoft.com/en-us/windows/win32/Intl/code-page-identifiers

Some single test scripts should work with Windows.

• To test basic assumptions about codepages, locales with Python:

  setlocal
  set LC_ALL=C
  python tests/ltest__C.py -v
  set LC_ALL=.1252
  python tests/ltest__en_US_ISO8859_1.py -v
  set LC_ALL=.65001
  python tests/ltest__C_UTF_8.py -v
  set LC_ALL=.20127
  python tests/ltest__en_US_US_ASCII.py -v
  endlocal
  

• A subset of “normal” unit tests:

  python tests/test_shasum.py -v
  python tests/test_crc32.py -v
  python tests/test_crcmod.py -v
  python tests/test_misc.py
  python tests/test_match.py -v
  python tests/test_encodings.py -v
  python tests/test_walk.py -v
  python tests/test_treesum.py -v
  

• The special test script with invalid UTF-8 names:

  setlocal
  @REM Using the default locale
  python tests/test_treesum_invalid_filenames.py -v
  @REM An all other interesting locales
  set LC_ALL=.1252
  python tests/test_treesum_invalid_filenames.py -v
  set LC_ALL=.65001
  python tests/test_treesum_invalid_filenames.py -v
  set LC_ALL=.20127
  python tests/test_treesum_invalid_filenames.py -v
  @REM ...
  endlocal
  

Warning

These assumptions and script proposals are not yet tested.

Todo

More Windows specific tests