test_parsing.py

Overview

The `test_parsing.py` file contains automated test cases designed to verify the correctness and robustness of JSON parsing functionality using the `orjson` library. It primarily ensures that JSON inputs from a wide variety of sources and conditions either successfully parse or correctly raise parsing errors when invalid.

This test suite leverages the pytest framework and executes JSON parsing tests on numerous JSON fixtures, validating both positive cases (valid JSON parsing) and negative cases (invalid JSON inputs that should raise exceptions). It is structured as a single test class with many test methods, each targeting a different JSON fixture file.

Detailed Explanation

Imports

• pytest: The testing framework used for defining and running tests.

• orjson: The JSON parsing library under test.

• .util:

  • needs_data: A decorator to conditionally enable tests, likely dependent on data availability.

  • read_fixture_bytes: A utility function that reads JSON test fixture files as bytes from a specific directory/category.

Class: TestJSONTestSuiteParsing

This class encapsulates all JSON parsing test cases. It is decorated with `@needs_data`, indicating tests only run if the required test data is present.

Purpose:

• Run comprehensive parsing tests on JSON files categorized as passing or failing inputs.

• Validate that orjson.loads() correctly parses valid JSON and raises orjson.JSONDecodeError on invalid JSON.

Methods

_run_fail_json(filename: str, exc=orjson.JSONDecodeError) -> None

**Description:** Helper method to test that parsing a JSON file fails and raises the expected exception.

**Parameters:**

• filename (str): The name of the JSON fixture file to test.

• exc (Exception class, optional): The expected exception type. Defaults to orjson.JSONDecodeError.

**Behavior:**

• Reads the JSON data as bytes from the "parsing" fixtures directory.

• Attempts to parse the data using orjson.loads() in four forms: bytes, bytearray, memoryview, and UTF-8 decoded string.

• Asserts that each parsing attempt raises the expected exception.

• If data cannot be decoded as UTF-8, it skips the string parsing check.

**Example Usage:**

self._run_fail_json("n_array_just_comma.json")

_run_pass_json(filename: str, match: str = "") -> None

**Description:** Helper method to test that parsing a JSON file succeeds without raising exceptions.

**Parameters:**

• filename (str): The name of the JSON fixture file to test.

• match (str, optional): Unused parameter in current implementation; possibly reserved for future use.

**Behavior:**

• Reads the JSON data as bytes from the "parsing" fixtures directory.

• Parses the JSON data successfully using orjson.loads() in four forms: bytes, bytearray, memoryview, and UTF-8 decoded string.

• No exceptions should be raised.

**Example Usage:**

self._run_pass_json("y_object_simple.json")

Test Methods

The class defines a large number of test methods following the pattern:

def test_<filename_without_extension>(self):
    """
    <filename>.json
    """
    self._run_pass_json("<filename>.json")

or

def test_<filename_without_extension>(self):
    """
    <filename>.json
    """
    self._run_fail_json("<filename>.json")

Each method corresponds to a specific JSON fixture file located in the "parsing" fixtures directory. The prefix in the filename indicates the expected outcome:

• y_ prefix: JSON files that should pass parsing tests.

• n_ prefix: JSON files that should fail parsing tests.

• i_ prefix: JSON files that are implementation-dependent, sometimes passing or failing depending on parser specifics.

These test methods ensure `orjson` correctly handles a variety of JSON edge cases, including:

• Arrays and objects with various structures and whitespace.

• Numbers with different formats and exponents.

• Strings with escape sequences, surrogate pairs, and unicode.

• Invalid JSON syntax cases such as missing commas, trailing commas, incomplete structures.

• Invalid characters, invalid UTF-8 sequences, and malformed UTF-16 sequences.

• Deeply nested structures and BOM markers.

Important Implementation Details

• Multiple input types tested: Each JSON input is parsed in several data representations: raw bytes, bytearray, memoryview, and UTF-8 decoded string to ensure consistent behavior across data types.

• Exception handling: The test expects orjson.JSONDecodeError for invalid JSON inputs, which is the standard exception for decode errors from orjson.

• Use of fixtures: The test inputs are external JSON files stored in a fixtures directory under the "parsing" category, abstracted by read_fixture_bytes.

• Conditional test execution: The class is decorated with @needs_data, which likely skips tests if fixtures are missing, preventing false failures.

• Handling of UTF-8 decoding errors: For fail tests, if the raw bytes cannot be decoded to UTF-8 (raising UnicodeDecodeError), the UTF-8 string parsing test is skipped since it is not applicable.

• Handling special cases: A few tests in the i_ prefix category include try-except blocks or comments noting parser behavior differences, reflecting real-world parsing ambiguities.

Interaction with Other System Components

• orjson library: This file directly tests JSON parsing functionality provided by the orjson library. It calls orjson.loads() to parse JSON data.

• Test fixtures and utilities: The tests rely heavily on external JSON fixture files (not included here) which provide input data for testing. They use utility functions from .util to load data and conditionally run tests.

• pytest framework: The test class and methods are designed to run under the pytest framework, using its assertion and exception handling mechanisms.

This file forms the core of the JSON parsing correctness validation in the test suite, assuring that JSON parsing meets expected standards and handles edge cases properly.

Usage Example

To run the tests:

pytest test_parsing.py

This will execute all test methods in the `TestJSONTestSuiteParsing` class, validating JSON parsing against the provided fixtures.

Visual Diagram

classDiagram
    class TestJSONTestSuiteParsing {
        +_run_fail_json(filename: str, exc=orjson.JSONDecodeError)
        +_run_pass_json(filename: str, match: str="")
        +test_y_array_arraysWithSpace()
        +test_y_array_empty_string()
        +test_y_array_empty()
        +... (many test_y_* methods)
        +test_n_array_1_true_without_comma()
        +... (many test_n_* methods)
        +test_i_number_double_huge_neg_exp()
        +... (many test_i_* methods)
    }

**Diagram Explanation:**

• The class contains two main helper methods for running pass/fail JSON parsing tests.

• It contains a large set of test methods named according to the JSON fixture tested, grouped by expected pass (y_), fail (n_), and implementation-dependent (i_) cases.

Summary

`test_parsing.py` is a comprehensive pytest test suite that validates JSON parsing correctness and error handling of the `orjson` library using a rich set of JSON fixtures. It systematically tests many JSON edge cases by loading test files as bytes and strings, ensuring consistent parser behavior. This file is essential for maintaining the quality and stability of JSON parsing in the overall system.