Implement test automation plan (Phases A–D) and update documentation

[Copilot]

Implements Phases A–D of the test automation plan (doc/test-automation-plan.md), raising automated coverage from 63% to 79% (85/107 manual tests). Updates all project documentation to reflect completion.

Phase A — Test Data Generation

• tests/generate_test_data.py: 10 deterministic datasets (TD-001–TD-010) with fixed seeds

Phase B — C/CLI/JPIP Test Gaps

• MT-API-009: Error callback test in test_roundtrip.c — wired up DECODE_MSG macro in opj_jp3d_decode() so the callback parameter is actually invoked on decode errors (previously accepted but (void)-cast)
• MT-CLI-011/014/016–018: 5 new tests in test_cli.c — verbose output content, missing-file error, decompress/dump/transcode --version
• MT-JPIP-002: test_server_lifecycle() in test_jpip3d.c — full create→load→handle→destroy cycle

/* DECODE_MSG macro added to opj_jp3d_decode — example usage: */
if (err || marker != (uint16_t)OPJ_CS3D_SOC) {
    DECODE_MSG(OPJ_JP3D_MSG_ERROR, "decode: missing SOC marker");
    return NULL;
}

Phase C — CI Jobs

• build-minimal: core-only build with all optional features OFF
• packaging: install → pkg-config → find_package(OpenJP3D) → CPack source tarball
• tests/find_package_test/: minimal external project for find_package validation

Phase D — GUI Smoke Test

• tests/test_gui.sh: headless L1 (launch/exit) + L2 (screenshot) under Xvfb
• gui-smoke CI job and CMake gui_smoke test target (Linux only)

Documentation

• doc/test-automation-plan.md: phases A–D marked ✅, traceability tables updated
• milestone.md: Phase 15 added (12 deliverables)
• CHANGELOG.md: entry under [Unreleased]
• README.md: project status updated

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[SureshKViswanathan]

@copilot how to test on Mac?

[Copilot]

@copilot how to test on Mac?

On macOS, the core library and CLI tests work out of the box — this is already covered by the macOS Apple Clang CI matrix entry. To run locally:

# Build & run all core/CLI tests
cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON -DBUILD_CLI_TOOLS=ON -DBUILD_JPIP_3D=ON
cmake --build build
ctest --test-dir build --output-on-failure

This runs all 13 CTest targets including the new Phase 15 tests (error callback, CLI verbose/version/missing-file, JPIP lifecycle).

GUI testing on Mac requires SDL2 (brew install sdl2), then:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_GUI_TOOLS=ON -DBUILD_TESTING=ON -DBUILD_CLI_TOOLS=ON
cmake --build build
# Launch GUI manually (no Xvfb on macOS):
./build/bin/opj_jp3d_gui

The headless test_gui.sh script is Linux-only (requires Xvfb/xwd). On macOS, GUI testing is manual — launch the app, verify it renders, and close with ⌘Q. The gui_smoke CMake test is intentionally skipped on Apple (UNIX AND NOT APPLE guard in tests/CMakeLists.txt:119).

Packaging validation (pkg-config, find_package, CPack) also works on macOS:

cmake --install build --prefix /tmp/openjp3d_install
export PKG_CONFIG_PATH=/tmp/openjp3d_install/lib/pkgconfig
pkg-config --modversion openjp3d
cmake -B /tmp/fptest -S tests/find_package_test -DCMAKE_PREFIX_PATH=/tmp/openjp3d_install
cmake --build /tmp/fptest