test_memory.c

Overview

The test_memory.c file contains unit test code that focuses on verifying the correctness and memory management of JSON parsing and serialization functionality. It ensures that JSON data can be parsed into an internal representation, re-serialized back to a string, and compared for structural equality without memory leaks or errors. The test validates the integrity and lifecycle of json_value objects, which represent parsed JSON structures, and confirms that memory is correctly allocated and freed.

This file primarily interacts with JSON parsing and stringifying functions, memory management utilities, and testing framework macros that handle assertions and test lifecycle management.

Detailed Explanation

Included Headers

• ../test/test.h: Provides testing macros and functions such as TEST, ASSERT_PTR_NOT_NULL, ASSERT_TRUE, END_TEST, and test lifecycle macros (TEST_INITIALIZE, TEST_SUITE, TEST_FINALIZE).

Function: test_memory_leaks

TEST(test_memory_leaks, char *json)

• Purpose: Runs a test case to check for memory leaks and correctness in JSON parsing and serialization.

• Parameters:

  • char *json: A pointer used to hold the serialized JSON string output.

• Return: None (void test macro function).

• Functionality:

  1. Defines a JSON string source representing a simple JSON array with one object: [{"key": "value"}].

  2. Declares a json_value struct v and zero-initializes it using memset.

  3. Parses the JSON string into the json_value structure using json_parse(source, &v).

  4. Asserts that the pointer &v is not null (indicating successful parsing).

  5. Serializes the internal JSON representation back to a string using json_stringify(&v), storing the result in both out and json.

  6. Asserts that both serialized strings are not null.

  7. Frees the allocated memory for the internal JSON value with json_free(&v).

  8. Compares the serialized JSON string json with the original source string for structural equality (order-insensitive) using utils_test_json_equal.

  9. Outputs the serialized JSON string using utils_output.

  10. Frees the internal JSON value again (likely redundant) and the serialized JSON string to avoid memory leaks.

  11. Ends the test with END_TEST.

• Usage Example:
  This function is called within the main() function as part of the test suite execution, verifying that JSON parsing and serialization do not leak memory and produce structurally equivalent JSON.

Function: main

int main(void)

• Purpose: Entry point for running the unit test suite.

• Parameters: None.

• Return: int (exit code).

• Functionality:

  1. Initializes the testing framework using TEST_INITIALIZE.

  2. Declares a test suite named "unit tests" using TEST_SUITE.

  3. Calls the test_memory_leaks() function to execute the memory leak and correctness test.

  4. Finalizes the testing framework using TEST_FINALIZE.

  5. Returns 0 to indicate successful execution.

• Usage: This function runs the test defined in the file and manages the overall test lifecycle.

Important Implementation Details

• Memory Management: The test carefully allocates and frees memory for both internal JSON representations (json_value) and serialized strings to prevent leaks.

• Structural JSON Comparison: The test uses a utility function utils_test_json_equal that performs an order-insensitive comparison of JSON strings, ensuring the parsing and serialization processes preserve the JSON structure.

• Redundant Calls: The json_free(&v) function is called twice; the second call after the comparison and output is redundant but does not cause harm in this context.

• Testing Framework Integration: The file uses macros for assertions and test management, indicating integration with a custom or third-party testing framework.

Interaction with Other Components

• JSON Parsing and Serialization:

  • json_parse(source, &v): Parses a JSON string into a json_value structure.

  • json_stringify(&v): Converts a json_value structure back into a JSON string.

  • json_free(&v): Frees memory associated with a json_value.

• Utilities:

  • utils_test_json_equal(json, source): Tests for structural equality between two JSON strings.

  • utils_output(json): Outputs JSON to console or log.

• Testing Framework:

  • Macros like TEST, ASSERT_PTR_NOT_NULL, ASSERT_TRUE, END_TEST, TEST_INITIALIZE, TEST_SUITE, and TEST_FINALIZE are used to organize and validate tests.

Mermaid Diagram: Function Workflow in test_memory.c

flowchart TD
A["main()"] --> B[TEST_INITIALIZE]
B --> C["TEST_SUITE("unit tests")"]
C --> D["test_memory_leaks()"]
D --> E[Initialize json_value v]
E --> F["json_parse(source, &v)"]
F --> G{Is &v not NULL?}
G -- Yes --> H["json_stringify(&v) -> out"]
H --> I{Is out not NULL?}
I -- Yes --> J["json_stringify(&v) -> json"]
J --> K{Is json not NULL?}
K -- Yes --> L["json_free(&v)"]
L --> M["utils_test_json_equal(json, source)"]
M --> N["utils_output(json)"]
N --> O["json_free(&v)"]
O --> P["free(json)"]
P --> Q[END_TEST]
Q --> R[TEST_FINALIZE]
R --> S[Return 0]

This flowchart depicts the sequential execution order of the main function and the test function, highlighting key operations such as parsing, serialization, assertions, memory freeing, and test lifecycle management.