Home

Awesome

AceTime Validation

This project consists of 2 sets of validation tests for the various libraries in the AceTime family:

Both of them use the scripts and binaries in tools directory:

Version: v1.8.0 (2024-12-13, TZDB 2024b)

Changelog: CHANGELOG.md

Table of Contents

Overview

Tests

The primary purpose of tests/ is to test the 2 algorithms implemented in the AceTime Arduino library by the following classes:

They are tested against 3 other libraries, which are assumed to be accurate:

These 3 were chosen because they have the capacity to update their zone database directly from the TZDB, so their unit tests will likely pass when a new TZDB release is created. The other 3rd party libraries depend on a release cycle, so will often be pegged to an older version of TZDB, which will cause the tests to fail.

These tests are written as AUnit unit tests running on a Linux box using the EpoxyDuino framework.

Validation

The tests under validation/ allow general peer-to-peer comparisons between any 2 timezone libraries. In practice, it's easier to select one of the libraries as the "baseline" or "golden" data set, and compare the others against it.

The timezone libraries supported are:

Tools

Each supported timezone library is represented by an associated compare_xxx tool under the ./tools/ directory:

The purpose of the compare_xxx scripts is to produce a list of all DST transitions over the given year range, for the requested timezones. These transitions are saved as a JSON file usually named validation_data.json. These JSON files are consumed by the various scripts in ./tests and ./validation.

Compiling the Tools

See tools to compile and prepare the various scripts and binaries. Basically:

$ cd tools
$ make clean
$ make

Running the Tests

To run the "tests":

$ cd tests
$ make clean
$ make -j2 tests
$ make runtests

The make tests target runs only a subset of the integration tests which validate against libraries that are known to work when a new TZDB version is released:

The other libraries instead rely on the TZDB version that is installed on the underlying OS, but when a new TZDB version is released, these libraries usually break because the OS version becomes outdated.

See additional information in tests/README.md.

Running the Validation

To run the peer-to-peer validations:

$ cd validation
$ vi Makefile # update TZDB_VERSION
$ make clean
$ make -j2 validation

The "baseline" is selected to be the acetime_complete.json target which comes from the AceTime library, from the year 1800 to 2200.

The validation target runs the following against the baseline:

See additional information in validation/README.md.

License

MIT License

Feedback and Support

If you have any questions, comments, or feature requests for this library, please use the GitHub Discussions for this project. If you have bug reports, please file a ticket in GitHub Issues. Feature requests should go into Discussions first because they often have alternative solutions which are useful to remain visible, instead of disappearing from the default view of the Issue tracker after the ticket is closed.

Please refrain from emailing me directly unless the content is sensitive. The problem with email is that I cannot reference the email conversation when other people ask similar questions later.

Authors