Testing and Code Coverage¶

This document provides comprehensive information about testing infrastructure, coverage reporting, and contribution guidelines for the Hakka JSON library.

Overview¶

Hakka JSON maintains a comprehensive test suite with code coverage reporting to ensure reliability and quality. The project uses:

Testing Framework: Google Test (GTest) with GMock
Coverage Tools: gcov (GCC/Clang built-in) + lcov 2.3.2+
Build System: CMake 3.20+
Test Organization: Separated into core library tests and C API tests

Running Tests¶

Prerequisites¶

Ensure you have the required tools installed:

# Check GCC/Clang version (gcov included)
gcc --version  # or clang --version

# Install lcov for coverage reporting
# Arch Linux
sudo pacman -S lcov

# Ubuntu/Debian
sudo apt-get install lcov

# macOS
brew install lcov

Building Tests¶

Configure the build with testing enabled:

mkdir build && cd build
cmake .. -DHAKKA_JSON_BUILD_TESTS=ON
make

Running Tests¶

Execute all tests using CTest:

# Run all tests with output
ctest --output-on-failure

# Run specific test suite
ctest -R t_hakka_json_array --verbose

# List all available tests
ctest -N

Run individual test executables directly:

# Core library tests
./tests/core/t_hakka_json_array
./tests/core/t_hakka_json_object
./tests/core/t_hakka_json_string
# ... and more

# C API tests
./tests/capi/capi_hakka_json_array
./tests/capi/capi_hakka_json_object
# ... and more

Generating Coverage Reports¶

Enable Coverage¶

Configure the build with both testing and coverage enabled:

mkdir build && cd build
cmake .. -DHAKKA_JSON_BUILD_TESTS=ON -DHAKKA_JSON_ENABLE_COVERAGE=ON
make

Generate Coverage Report¶

Use the provided CMake target to generate HTML coverage reports:

# Clean previous coverage data, run tests, and generate report
make coverage

# Or run steps individually:
make coverage_clean      # Clean old coverage data
make coverage_generate   # Run tests to generate .gcda files
make coverage_report     # Generate HTML report from coverage data

View Coverage Report¶

Open the generated HTML report in your browser:

# Linux
xdg-open coverage/html/index.html

# macOS
open coverage/html/index.html

# Or manually navigate to:
# build/coverage/html/index.html

The report provides:

Line Coverage: Percentage of executed lines
Function Coverage: Percentage of called functions
Branch Coverage: Percentage of executed conditional branches
Directory-Level Breakdown: Coverage metrics per source directory
File-Level Detail: Line-by-line execution visualization

Current Coverage Status¶

Last Updated: 2025-10-02 14:43:12 Generated by: LCOV version 2.3.2-1

Overall Metrics¶

Metric	Coverage	Hit	Total
Lines	67.4%	2,733	4,056
Functions	70.7%	698	987
Branches	35.4%	2,272	6,418

Directory Breakdown¶

Directory	Line Coverage	Function Coverage	Branch Coverage
src/handles/	96.5% (355/368)	96.5% (55/57)	59.9% (254/424)
include/handles/	92.0% (23/25)	70.0% (14/20)	50.0% (6/12)
build/icu-install/include/unicode/	95.0% (38/40)	100.0% (16/16)	50.0% (9/18)
include/	88.7% (275/310)	66.8% (256/383)	21.7% (216/994)
capi/	61.8% (833/1,348)	73.3% (148/202)	34.1% (665/1,948)
src/	61.5% (1,209/1,965)	67.6% (209/309)	37.1% (1,122/3,022)

Coverage Rating Classification¶

High Coverage (e 90%): Excellent test coverage
Medium Coverage (75% - 89%): Good test coverage
Low Coverage (< 75%): Needs improvement

Contributing to the Project¶

We welcome contributions to improve Hakka JSON! Whether you're fixing bugs, adding features, improving tests, or enhancing documentation, your contributions are valued.

Areas for Contribution¶

Test Coverage Improvement
Add tests for uncovered code paths
Improve branch coverage with edge case testing
Add integration tests for complex scenarios
Feature Development
Implement new JSON operations
Enhance C API functionality
Optimize performance-critical paths
Bug Fixes
Fix reported issues
Improve error handling
Enhance edge case handling
Documentation
Improve API documentation
Add usage examples
Translate documentation to other languages

Contribution Workflow¶

Fork and Clone

git clone https://github.com/cycraft-corp/hakka_json.git
cd hakka_json

Create a Feature Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

Make Your Changes
Write clean, maintainable code
Follow existing code style and conventions
Add tests for new functionality
Update documentation as needed

Run Tests and Coverage

mkdir build && cd build
cmake .. -DHAKKA_JSON_BUILD_TESTS=ON -DHAKKA_JSON_ENABLE_COVERAGE=ON
make
ctest --output-on-failure
make coverage

Commit Your Changes

git add .
git commit -m "feat: Add your feature description"
# or
git commit -m "fix: Fix issue description"

Commit Message Convention:

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions or modifications
refactor: Code refactoring
perf: Performance improvements
chore: Build process or tooling changes

Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub with: - Clear description of changes - Reference to related issues (if applicable) - Screenshots or examples (if applicable) - Test coverage report (if adding new code)

Quality Standards¶

Before submitting a pull request, ensure:

All tests pass (ctest --output-on-failure)
New code has corresponding tests
Code coverage does not decrease
Code follows existing style conventions
Documentation is updated
Commit messages are clear and descriptive

Getting Help¶

Issues: Report bugs or request features via GitHub Issues
Discussions: Ask questions or discuss ideas in GitHub Discussions
Code Review: Participate in code reviews to learn and improve

Code of Conduct¶

We are committed to providing a welcoming and inclusive environment. Please:

Be respectful and constructive in all interactions
Focus on what is best for the community and project
Show empathy towards other community members
Accept constructive criticism gracefully

Test Structure¶

Core Library Tests (`tests/core/`)¶

Test executables for C++ core library:

t_hakka_json_array - Array operations and manipulation
t_hakka_json_bool - Boolean value handling
t_hakka_json_float - Floating-point operations
t_hakka_json_int - Integer operations
t_hakka_json_invalid - Invalid input handling
t_hakka_json_null - Null value handling
t_hakka_json_object - Object operations and manipulation
t_hakka_json_string - String handling and Unicode support

C API Tests (`tests/capi/`)¶

Test executables for C API:

capi_hakka_json_array - C API array operations
capi_hakka_json_complex - Complex nested structures
capi_hakka_json_object - C API object operations
capi_hakka_json_primitive - Primitive types in C API

Performance Tests (`tests/perf/`)¶

Benchmark tests for performance validation and optimization.

Additional Resources¶

Architecture Documentation: See other documents in docs/content/Architecture/
API Reference: C++ API in docs/content/API/C++/, C API in docs/content/API/CAPI/
Build System: See root CMakeLists.txt and cmake/ directory
Source Code: Browse src/ (C++ core) and capi/ (C API wrapper)

Thank you for contributing to Hakka JSON!

Testing and Code Coverage¶

Overview¶

Running Tests¶

Prerequisites¶

Building Tests¶

Running Tests¶

Generating Coverage Reports¶

Enable Coverage¶

Generate Coverage Report¶

View Coverage Report¶

Current Coverage Status¶

Overall Metrics¶

Directory Breakdown¶

Coverage Rating Classification¶

Contributing to the Project¶

Areas for Contribution¶

Contribution Workflow¶

Quality Standards¶

Getting Help¶

Code of Conduct¶

Test Structure¶

Core Library Tests (tests/core/)¶

C API Tests (tests/capi/)¶

Performance Tests (tests/perf/)¶

Additional Resources¶

Core Library Tests (`tests/core/`)¶

C API Tests (`tests/capi/`)¶

Performance Tests (`tests/perf/`)¶