Test Suite Overview

Relevant source files

The following files were used as context for generating this wiki page:

• tests/test-defs.sh
• tests/test_parse.c
• tests/test_cast.c
• tests/test_charcase.c
• tests/test_printbuf.c
• tests/test_parse_int64.c
• CONTRIBUTING.md
• CI/check_codestyle.sh

The libfastjson test suite is a comprehensive verification framework designed to ensure the library's performance, stability, and correctness. It employs a mix of functional C-based unit tests, shell-based test drivers, and Continuous Integration (CI) checks to validate JSON parsing, object manipulation, and string buffering.

The testbench is a mandatory part of the development workflow. All pull requests must pass CI tests, and new functionality or bug fixes are required to include related tests to prevent regressions. Sources: CONTRIBUTING.md:1-12

Test Architecture and Infrastructure

The testing infrastructure relies on a combination of compiled binary tests and shell scripts that manage the execution environment and output validation.

Test Driver (test-defs.sh)

The test-defs.sh script serves as the primary utility for running output-based tests. It standardizes how test binaries are invoked and how their results are verified against expected baselines.

• Working Directory Management: Tests are executed in dedicated subdirectories (e.g., testSubDir/<testname>) to prevent interference. Sources: tests/test-defs.sh:31-37
• Result Comparison: The function run_output_test() executes a command, captures its standard output to a .out file, and compares it to a .expected file using the cmp utility. Sources: tests/test-defs.sh:62-116
• Valgrind Integration: The driver supports memory leak detection by wrapping test execution in Valgrind if the VALGRIND variable is set. Sources: tests/test-defs.sh:84-104

The diagram shows the logic flow within test-defs.sh for executing and validating a test case. Sources: tests/test-defs.sh:1-125

Core Functional Tests

The suite includes specific C programs targeting different modules of the library.

Parsing and Tokenization

test_parse.c validates the fjson_tokener implementation, covering basic, verbose, and incremental parsing scenarios.

• Basic Parsing: Tests literals (null, true, NaN, Infinity), strings with escape sequences, and complex nested objects. Sources: tests/test_parse.c:32-108
• Incremental Parsing: Simulates streaming data by passing fragments of JSON to fjson_tokener_parse_ex and checking for fjson_tokener_continue or fjson_tokener_success states. Sources: tests/test_parse.c:166-267
• Strict Mode: test_charcase.c ensures that in strict mode, JSON literals like true or null are rejected if they contain uppercase characters. Sources: tests/test_charcase.c:31-50

Type Casting and Object Inspection

test_cast.c verifies the behavior of the fjson_object_get_* and fjson_object_is_type functions. It ensures that the library correctly handles type conversions (e.g., a string of digits being retrieved as an integer) and correctly identifies object types. Sources: tests/test_cast.c:1-105

String Buffer Management

test_printbuf.c targets the internal printbuf module used for constructing JSON strings.

Test Function	Target Feature	Description
test_basic_printbuf_memset	printbuf_memset	Tests filling buffer with specific characters.
test_printbuf_memappend	printbuf_memappend_fast	Validates buffer resizing logic during large appends.
test_sprintbuf	sprintbuf	Tests formatted string appending and resizing.

Sources: tests/test_printbuf.c:15-165

Integer Handling and Edge Cases

The library provides robust parsing for 64-bit integers, including workarounds for broken sscanf implementations. test_parse_int64.c validates:

• Standard integers and zero.
• Boundary values (INT32_MAX, INT64_MAX, INT64_MIN).
• Overflow conditions and strings with leading/trailing non-numeric characters. Sources: tests/test_parse_int64.c:1-105

The sequence shows how the library handles integer parsing, including safety checks for platform-specific sscanf behavior. Sources: tests/test_parse_int64.c:85, json_util.c:157-235

Static Analysis and Style Checks

Beyond functional logic, the suite includes automated checks for code quality and consistency.

• Code Style: check_codestyle.sh uses a custom stylecheck tool to enforce indentation via tabs, prohibit trailing whitespaces, and limit line length to 130 characters. Sources: CI/check_codestyle.sh:1-7, CONTRIBUTING.md:25-30
• Sanitizers: Integration scripts exist to run tests with Clang sanitizers for detecting undefined behavior and memory issues. Sources: CI/try_merge.sh:31

Summary

The libfastjson test suite is structured to provide high confidence in the library's core parsing and string generation logic. By combining C unit tests that target specific APIs with a robust shell-based verification system and style enforcement, the project maintains high code quality even during rapid development and refactoring. Sources: CONTRIBUTING.md:1-10, README.md:52-54