Skip to content

JSON assertions

JSONPath navigation and JSON Schema validation (requires the json extra).

JSON path navigation and schema validation mixin.

at_json_path 

at_json_path(path: str) -> Self

Navigate to a JSON path and return a new builder with the matched value.

Uses JSONPath syntax (e.g. $.users[0].name). If multiple matches are found, the value is a list of all matches. If exactly one match is found, the value is unwrapped from the list.

Parameters:

Name Type Description Default
path str

JSONPath expression.

 required

Examples:

Usage:

data = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
assert_that(data).at_json_path("$.users[0].name").is_equal_to("Alice")
assert_that(data).at_json_path("$.users[*].name").is_equal_to(["Alice", "Bob"])

Returns:

Name Type Description
AssertionBuilder Self

a new instance with the extracted value

Raises:

Type Description
ValueError

if no match is found at the given path
Source code in assertpy2/json_mixin.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def at_json_path(self, path: str) -> Self:
    """Navigate to a JSON path and return a new builder with the matched value.

    Uses JSONPath syntax (e.g. ``$.users[0].name``). If multiple matches are found,
    the value is a list of all matches. If exactly one match is found, the value is
    unwrapped from the list.

    Args:
        path: JSONPath expression.

    Examples:
        Usage:

            data = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
            assert_that(data).at_json_path("$.users[0].name").is_equal_to("Alice")
            assert_that(data).at_json_path("$.users[*].name").is_equal_to(["Alice", "Bob"])

    Returns:
        AssertionBuilder: a new instance with the extracted value

    Raises:
        ValueError: if no match is found at the given path
    """
    jsonpath_ng_ext = _ensure_jsonpath_ng()
    expr = jsonpath_ng_ext.parse(path)
    matches = expr.find(self.val)
    if not matches:
        raise ValueError(f"Expected JSON path <{path}> to exist, but it did not.")
    if len(matches) == 1:
        return self.builder(matches[0].value, self.description, self.kind)
    return self.builder([match.value for match in matches], self.description, self.kind)

has_json_path 

has_json_path(path: str) -> Self

Assert that the given JSON path exists in val.

Parameters:

Name Type Description Default
path str

JSONPath expression.

 required

Examples:

Usage:

data = {"meta": {"total": 5}}
assert_that(data).has_json_path("$.meta.total")

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the path does not exist
Source code in assertpy2/json_mixin.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def has_json_path(self, path: str) -> Self:
    """Assert that the given JSON path exists in val.

    Args:
        path: JSONPath expression.

    Examples:
        Usage:

            data = {"meta": {"total": 5}}
            assert_that(data).has_json_path("$.meta.total")

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if the path does not exist
    """
    jsonpath_ng_ext = _ensure_jsonpath_ng()
    expr = jsonpath_ng_ext.parse(path)
    matches = expr.find(self.val)
    if not matches:
        return self.error(f"Expected JSON path <{path}> to exist, but it did not.")
    return self

does_not_have_json_path 

does_not_have_json_path(path: str) -> Self

Assert that the given JSON path does not exist in val.

Parameters:

Name Type Description Default
path str

JSONPath expression.

 required

Examples:

Usage:

data = {"status": "ok"}
assert_that(data).does_not_have_json_path("$.error")

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the path exists
Source code in assertpy2/json_mixin.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def does_not_have_json_path(self, path: str) -> Self:
    """Assert that the given JSON path does not exist in val.

    Args:
        path: JSONPath expression.

    Examples:
        Usage:

            data = {"status": "ok"}
            assert_that(data).does_not_have_json_path("$.error")

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if the path exists
    """
    jsonpath_ng_ext = _ensure_jsonpath_ng()
    expr = jsonpath_ng_ext.parse(path)
    matches = expr.find(self.val)
    if matches:
        return self.error(f"Expected JSON path <{path}> to not exist, but it did.")
    return self

matches_json_schema 

matches_json_schema(schema: dict[str, Any]) -> Self

Assert that val conforms to the given JSON Schema.

Parameters:

Name Type Description Default
schema dict[str, Any]

a JSON Schema as a dict.

 required

Examples:

Usage:

schema = {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}
assert_that({"name": "Alice"}).matches_json_schema(schema)

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not conform to the schema
Source code in assertpy2/json_mixin.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
def matches_json_schema(self, schema: dict[str, Any]) -> Self:
    """Assert that val conforms to the given JSON Schema.

    Args:
        schema: a JSON Schema as a dict.

    Examples:
        Usage:

            schema = {"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]}
            assert_that({"name": "Alice"}).matches_json_schema(schema)

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does not conform to the schema
    """
    jsonschema_mod = _ensure_jsonschema()
    try:
        jsonschema_mod.validate(self.val, schema)
    except jsonschema_mod.ValidationError as exc:
        return self.error(f"Expected val to match JSON schema, but validation failed: {exc.message}")
    return self

matches_json_schema_from_file 

matches_json_schema_from_file(path: str | Path) -> Self

Assert that val conforms to a JSON Schema loaded from a file.

Parameters:

Name Type Description Default
path str | Path

path to a JSON file containing the schema.

 required

Examples:

Usage:

assert_that(data).matches_json_schema_from_file("schemas/order.json")

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not conform to the schema
Source code in assertpy2/json_mixin.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
def matches_json_schema_from_file(self, path: str | Path) -> Self:
    """Assert that val conforms to a JSON Schema loaded from a file.

    Args:
        path: path to a JSON file containing the schema.

    Examples:
        Usage:

            assert_that(data).matches_json_schema_from_file("schemas/order.json")

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does not conform to the schema
    """
    schema = json.loads(Path(path).read_text(encoding="utf-8"))
    return self.matches_json_schema(schema)