Testing and CI¶
How the driver is checked: host unit tests against a register model of both chips, compiled documentation, ESP32 builds and static analysis, on every pull request.
Host unit tests¶
The tests build the real driver against a model of the chip behind the I2C interface. The model holds every register with its datasheet power-up value, NACKs the Agile I/O bank when it plays a PCA9555, applies polarity inversion to the Input Port registers, raises interrupts for unmasked inputs and clears them when the Input Port is read. It records every transfer, so tests check exactly what went over the bus.
cmake -S . -B build-host -DHF_PCAL95555_BUILD_TESTS=ON
cmake --build build-host
ctest --test-dir build-host --output-on-failure
| File | Covers |
|---|---|
tests/test_driver.cpp |
Variant detection, address mapping and clamping, port-register bit placement, drive-strength encoding, pull / latch / output-mode registers, ResetToDefault(), interrupt callbacks on both parts, multi-pin calls, error flags, inconclusive detection, ReadPin(pin, level), empty masks, independent driver objects |
tests/test_kconfig.cpp |
InitFromConfig() with an ESP-IDF style sdkconfig.h, including bools set to n |
tests/install/ |
CTest hf_pcal95555_install: cmake --install into a scratch prefix, then a find_package(hf_pcal95555) consumer builds and runs against it |
tests/mock_pcal95555.hpp |
The PCA9555 / PCAL9555A register model, with fault injection (failed reads, a bus stuck after the probe NACK, code run mid-transfer) |
tests/test_harness.hpp, tests/test_main.cpp |
A dependency-free test registry and runner |
Documentation snippets¶
Every C++ block on this site is included from tests/docs/, which the host build compiles
(target hf_pcal95555_doc_snippets, -Wall -Wextra, with HF_PCAL95555_NO_GLOBAL_ALIASES so the pages use the
namespaced names) with the driver instantiated over the documented port. A change to the API that breaks a page breaks
the build first. The README's example is a copy of the Quickstart snippet that hardfoc-docs check keeps in step.
CI workflows¶
| Workflow | What it checks |
|---|---|
| Host unit tests | GCC and Clang build and run the tests and the doc snippets |
| ESP32 examples build | Every app in examples/esp32/app_config.yml, for each listed ESP-IDF version and build type |
| C++ lint, C++ analysis | clang-format, clang-tidy and cppcheck |
| Docs | Strict site build, figure and generated-table drift, Doxygen, link check, Lighthouse budget |
| Markdown lint, YAML lint, link check | Repository text files |
The workflows call the shared, versioned workflows of hf-general-ci-tools and hf-espidf-ci-tools.
On hardware¶
The ESP32 examples are the hardware test suite: pcal95555_comprehensive_test runs 17 sections
and prints a pass / fail summary over the serial monitor, skipping the PCAL9555A-only sections on a PCA9555.