pytest-loco-json 1.3.1__tar.gz

pytest_loco_json-1.3.1/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Loco
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pytest_loco_json-1.3.1/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: pytest-loco-json
+Version: 1.3.1
+Summary: JSON support for pytest-loco
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Author: Mikhalev Oleg
+Author-email: mhalairt@gmail.com
+Requires-Python: >3.13,<4
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Plugins
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Requires-Dist: orjson (>=3.11.7,<4.0.0)
+Requires-Dist: pytest-loco (>=1.3.1)
+Requires-Dist: python-jsonpath (>=2.0.2,<3.0.0)
+Project-URL: Issues, https://github.com/pytest-loco/pytest-loco-json/issues
+Project-URL: Source, https://github.com/pytest-loco/pytest-loco-json
+Description-Content-Type: text/markdown
+
+# pytest-loco-json
+
+JSON extension for `pytest-loco`.
+
+The `pytest-loco-json` extension adds first-class JSON support to the
+`pytest-loco` DSL. It provides facilities for decoding, encoding, and
+querying JSON data as part of test execution.
+
+This extension is designed to integrate seamlessly with the `pytest-loco`
+plugin system and can be enabled by registering the `json` plugin.
+Once enabled, JSON becomes a native data format within the DSL, suitable
+for validation, transformation, and data-driven testing scenarios.
+
+## Encode
+
+The **dump** feature serializes a value from the execution context into a
+JSON string using the high-performance `orjson` backend.
+
+Encoding is typically used when preparing request payloads, exporting
+structured data, or normalizing values for comparison. The encoder
+accepts an optional `sortKeys` parameter that controls serialization
+behavior and enables deterministic key ordering.
+
+Encoded values are returned as UTF-8 JSON strings and can be passed
+directly to actions (for example, HTTP requests) or stored in the
+execution context.
+
+For example:
+
+```yaml
+---
+spec: case
+title: Example of encoding a value
+vars:
+  value:
+    name: Molecule Man
+    secretIdentity: Dan Jukes
+    age: 29
+
+---
+action: pass
+export:
+  jsonText: !dump
+    source: !var value
+    format: json
+```
+
+The result of executing this case will be the assignment of the
+following value (without indentation) to the variable `jsonText`:
+
+```json
+{
+  "name": "Molecule Man",
+  "age": 29,
+  "secretIdentity": "Dan Jukes"
+}
+```
+
+Optionally, you can use the `sortKeys` option:
+
+```yaml
+...
+action: pass
+export:
+  jsonText: !dump
+    source: !var value
+    format: json
+    sortKeys: yes
+```
+
+In this case, the keys will be sorted alphabetically:
+
+```json
+{
+  "age": 29,
+  "name": "Molecule Man",
+  "secretIdentity": "Dan Jukes"
+}
+```
+
+## Decode
+
+The **load** feature parses a JSON string into native Python objects and
+stores them as values in the execution context.
+
+Decoding allows JSON payloads to become fully addressable within the
+DSL execution context. Once decoded, values can be inspected, exported,
+validated, or transformed by subsequent steps.
+
+Decoder parameters are intentionally minimal: decoding focuses on
+correctness and performance, while transformation logic is handled
+separately.
+
+For example:
+
+```yaml
+---
+spec: case
+title: Example of decoding a value
+
+---
+action: pass
+title: Read JSON content from file
+export:
+  jsonText: !textFile test.json
+
+---
+action: pass
+title: Try to decode JSON
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+```
+
+The result of executing this case will be the assignment of the decoded
+JSON object to the variable `jsonValue`.
+
+## Transform by JSONPath
+
+The **load** feature can be extended with an optional transformer that
+enables extracting data from decoded JSON structures using JSONPath
+expressions.
+
+Transforms are applied after decoding and allow selecting either a
+single value or multiple values from complex, deeply nested documents.
+Behavior is configurable to return the first match, the last match, or
+a full list of matches.
+
+This makes it possible to work with large or variable JSON payloads
+without hard-coding structural assumptions into the test logic.
+
+Use the following `test.json` file contents as an example:
+
+```json
+[
+  {
+    "name": "Molecule Man",
+    "age": 29,
+    "secretIdentity": "Dan Jukes",
+    "powers": [
+      "Radiation resistance",
+      "Turning tiny",
+      "Radiation blast"
+    ]
+  },
+  {
+    "name": "Madame Uppercut",
+    "age": 39,
+    "secretIdentity": "Jane Wilson",
+    "powers": [
+      "Million tonne punch",
+      "Damage resistance",
+      "Superhuman reflexes"
+    ]
+  }
+]
+```
+
+Optionally, you can use the `query` transformer with **load**:
+
+```yaml
+...
+
+action: pass
+title: Decode JSON and select the first match
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+    query: '$[*].name'
+expect:
+- title: Check first selected name
+  value: !var jsonValue
+  match: Molecule Man
+```
+
+By default, the first match of the JSONPath query is selected.
+This behavior can be controlled using the `exactOne` parameter
+(`true` or `false`; when `false`, the query returns a full list of
+matches) and the `exactMode` parameter (`first` or `last` on a
+single mode querying).
+
+For example:
+
+```yaml
+...
+
+action: pass
+title: Try to decode JSON and select all
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+    query: '$[?(@.age<30)].powers[*]'
+    exactOne: no
+expect:
+- title: Check result is list of powers
+  value: !var jsonValue
+  match:
+  - Radiation resistance
+  - Turning tiny
+  - Radiation blast
+```
+
+## Inline querying
+
+Inline querying allows JSONPath expressions to be defined directly
+inside the DSL using the dedicated `!jsonpath` instruction.
+
+Inline queries are compiled during schema loading rather than at runtime,
+which improves error reporting and ensures invalid paths fail early.
+Compiled queries can be stored in variables and reused across steps.
+
+This feature is especially useful for complex test suites where the
+same JSONPath expressions appear in multiple places, or when clarity
+and reuse are more important than brevity.
+
+For example:
+
+```yaml
+---
+action: pass
+title: Try to select from context by instruction
+export:
+  resultValues: !jsonpath jsonValue $[?(@.age<_.ageLimit)].powers[*]
+expect:
+- title: Check result is list of powers
+  value: !var resultValues
+  match:
+  - Radiation resistance
+  - Turning tiny
+  - Radiation blast
+```
+
+The result is always a list.
+

pytest_loco_json-1.3.1/README.md

@@ -0,0 +1,236 @@
+# pytest-loco-json
+
+JSON extension for `pytest-loco`.
+
+The `pytest-loco-json` extension adds first-class JSON support to the
+`pytest-loco` DSL. It provides facilities for decoding, encoding, and
+querying JSON data as part of test execution.
+
+This extension is designed to integrate seamlessly with the `pytest-loco`
+plugin system and can be enabled by registering the `json` plugin.
+Once enabled, JSON becomes a native data format within the DSL, suitable
+for validation, transformation, and data-driven testing scenarios.
+
+## Encode
+
+The **dump** feature serializes a value from the execution context into a
+JSON string using the high-performance `orjson` backend.
+
+Encoding is typically used when preparing request payloads, exporting
+structured data, or normalizing values for comparison. The encoder
+accepts an optional `sortKeys` parameter that controls serialization
+behavior and enables deterministic key ordering.
+
+Encoded values are returned as UTF-8 JSON strings and can be passed
+directly to actions (for example, HTTP requests) or stored in the
+execution context.
+
+For example:
+
+```yaml
+---
+spec: case
+title: Example of encoding a value
+vars:
+  value:
+    name: Molecule Man
+    secretIdentity: Dan Jukes
+    age: 29
+
+---
+action: pass
+export:
+  jsonText: !dump
+    source: !var value
+    format: json
+```
+
+The result of executing this case will be the assignment of the
+following value (without indentation) to the variable `jsonText`:
+
+```json
+{
+  "name": "Molecule Man",
+  "age": 29,
+  "secretIdentity": "Dan Jukes"
+}
+```
+
+Optionally, you can use the `sortKeys` option:
+
+```yaml
+...
+action: pass
+export:
+  jsonText: !dump
+    source: !var value
+    format: json
+    sortKeys: yes
+```
+
+In this case, the keys will be sorted alphabetically:
+
+```json
+{
+  "age": 29,
+  "name": "Molecule Man",
+  "secretIdentity": "Dan Jukes"
+}
+```
+
+## Decode
+
+The **load** feature parses a JSON string into native Python objects and
+stores them as values in the execution context.
+
+Decoding allows JSON payloads to become fully addressable within the
+DSL execution context. Once decoded, values can be inspected, exported,
+validated, or transformed by subsequent steps.
+
+Decoder parameters are intentionally minimal: decoding focuses on
+correctness and performance, while transformation logic is handled
+separately.
+
+For example:
+
+```yaml
+---
+spec: case
+title: Example of decoding a value
+
+---
+action: pass
+title: Read JSON content from file
+export:
+  jsonText: !textFile test.json
+
+---
+action: pass
+title: Try to decode JSON
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+```
+
+The result of executing this case will be the assignment of the decoded
+JSON object to the variable `jsonValue`.
+
+## Transform by JSONPath
+
+The **load** feature can be extended with an optional transformer that
+enables extracting data from decoded JSON structures using JSONPath
+expressions.
+
+Transforms are applied after decoding and allow selecting either a
+single value or multiple values from complex, deeply nested documents.
+Behavior is configurable to return the first match, the last match, or
+a full list of matches.
+
+This makes it possible to work with large or variable JSON payloads
+without hard-coding structural assumptions into the test logic.
+
+Use the following `test.json` file contents as an example:
+
+```json
+[
+  {
+    "name": "Molecule Man",
+    "age": 29,
+    "secretIdentity": "Dan Jukes",
+    "powers": [
+      "Radiation resistance",
+      "Turning tiny",
+      "Radiation blast"
+    ]
+  },
+  {
+    "name": "Madame Uppercut",
+    "age": 39,
+    "secretIdentity": "Jane Wilson",
+    "powers": [
+      "Million tonne punch",
+      "Damage resistance",
+      "Superhuman reflexes"
+    ]
+  }
+]
+```
+
+Optionally, you can use the `query` transformer with **load**:
+
+```yaml
+...
+
+action: pass
+title: Decode JSON and select the first match
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+    query: '$[*].name'
+expect:
+- title: Check first selected name
+  value: !var jsonValue
+  match: Molecule Man
+```
+
+By default, the first match of the JSONPath query is selected.
+This behavior can be controlled using the `exactOne` parameter
+(`true` or `false`; when `false`, the query returns a full list of
+matches) and the `exactMode` parameter (`first` or `last` on a
+single mode querying).
+
+For example:
+
+```yaml
+...
+
+action: pass
+title: Try to decode JSON and select all
+export:
+  jsonValue: !load
+    source: !var jsonText
+    format: json
+    query: '$[?(@.age<30)].powers[*]'
+    exactOne: no
+expect:
+- title: Check result is list of powers
+  value: !var jsonValue
+  match:
+  - Radiation resistance
+  - Turning tiny
+  - Radiation blast
+```
+
+## Inline querying
+
+Inline querying allows JSONPath expressions to be defined directly
+inside the DSL using the dedicated `!jsonpath` instruction.
+
+Inline queries are compiled during schema loading rather than at runtime,
+which improves error reporting and ensures invalid paths fail early.
+Compiled queries can be stored in variables and reused across steps.
+
+This feature is especially useful for complex test suites where the
+same JSONPath expressions appear in multiple places, or when clarity
+and reuse are more important than brevity.
+
+For example:
+
+```yaml
+---
+action: pass
+title: Try to select from context by instruction
+export:
+  resultValues: !jsonpath jsonValue $[?(@.age<_.ageLimit)].powers[*]
+expect:
+- title: Check result is list of powers
+  value: !var resultValues
+  match:
+  - Radiation resistance
+  - Turning tiny
+  - Radiation blast
+```
+
+The result is always a list.

pytest_loco_json-1.3.1/pyproject.toml

@@ -0,0 +1,164 @@
+[project]
+name = "pytest-loco-json"
+version = "1.3.1"
+description = "JSON support for pytest-loco"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Plugins",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Utilities",
+]
+authors = [
+    {name = "Mikhalev Oleg", email = "mhalairt@gmail.com"}
+]
+license = "BSD-2-Clause"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">3.13,<4"
+dependencies = [
+    "orjson (>=3.11.7,<4.0.0)",
+    "pytest-loco (>=1.3.1)",
+    "python-jsonpath (>=2.0.2,<3.0.0)",
+]
+
+[project.urls]
+"Source" = "https://github.com/pytest-loco/pytest-loco-json"
+"Issues" = "https://github.com/pytest-loco/pytest-loco-json/issues"
+
+[project.entry-points.loco_plugins]
+pytest_loco_json = "pytest_loco_json.plugin:json"
+
+[tool.poetry]
+packages = [{include = "pytest_loco_json", from = "src"}]
+
+[tool.poetry.group.dev]
+optional = true
+
+[tool.poetry.group.dev.dependencies]
+mypy = {extras = ["mypyc", "reports", "stubgen"], version = "^1.19.1"}
+pre-commit = "^4.5.1"
+ruff = ">=0.14.11,<0.15.0"
+
+[tool.poetry.group.test]
+optional = true
+
+[tool.poetry.group.test.dependencies]
+pytest = "^9.0.2"
+pytest-cov = "^7.0.0"
+
+[tool.ruff]
+target-version = "py313"
+line-length = 120
+
+[tool.ruff.format]
+docstring-code-format = true
+quote-style = "single"
+
+[tool.ruff.lint]
+select = [
+    "ANN",     # flake8-annotations
+    "ASYNC",   # flake8-async
+    "S",       # flake8-bandit
+    "A",       # flake8-builtins
+    "B",       # flake8-bugbear
+    "COM",     # flake8-commas
+    "C4",      # flake8-comprehensions
+    "T20",     # flake8-print
+    "Q",       # flake8-quotes
+    "RSE",     # flake8-raise
+    "SLF",     # flake8-self
+    "SIM",     # flake8-simplify
+    "TC",      # flake8-type-checking
+    "ARG",     # flake8-unused-arguments
+    "I",       # isort
+    "E", "W",  # pycodestyle
+    "D",       # pydocstyle
+    "F",       # pyflakes
+    "PL",      # pylint
+    "UP",      # pyupgrade
+    "RUF",     # ruff
+]
+
+[tool.ruff.lint.isort]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "loco",
+    "first-party",
+    "local-folder",
+]
+known-first-party = ["pytest_loco_json"]
+
+[tool.ruff.lint.isort.sections]
+loco = ["pytest_loco"]
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "single"
+multiline-quotes = "single"
+
+[tool.ruff.lint.flake8-type-checking]
+quote-annotations = true
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.mypy]
+python_version = "3.13"
+mypy_path = ["src"]
+packages = ["pytest_loco_json"]
+strict = true
+exclude_gitignore = true
+explicit_package_bases = true
+pretty = true
+show_error_codes = true
+color_output = true
+
+[[tool.mypy.overrides]]
+module = "yaml.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "9.0.0"
+testpaths = ["tests"]
+addopts = [
+    "-q",
+    "--cov=pytest_loco_json",
+    "--cov-report=term",
+    "--cov-report=html",
+    "--strict-markers",
+    "--strict-config",
+]
+
+[tool.coverage.run]
+source = ["pytest_loco_json"]
+branch = true
+parallel = true
+concurrency = ["multiprocessing"]
+
+[tool.coverage.paths]
+source = [
+    "src/pytest_loco_json",
+    "**/site-packages/pytest_loco_json"
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if typing.TYPE_CHECKING:",
+    "if TYPE_CHECKING:",
+]
+fail_under = 80
+show_missing = true
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

pytest_loco_json-1.3.1/src/pytest_loco_json/__init__.py

@@ -0,0 +1,11 @@
+"""JSON extension for pytest-loco.
+
+The `pytest-loco-json` extension adds first-class JSON support to the
+pytest-loco DSL. It provides facilities for decoding, encoding, and
+querying JSON data as part of test execution.
+
+This extension is designed to integrate seamlessly with the pytest-loco
+plugin system and can be enabled by registering the `json` plugin.
+Once enabled, JSON becomes a native data format within the DSL, suitable
+for validation, transformation, and data-driven testing scenarios.
+"""

pytest_loco_json-1.3.1/src/pytest_loco_json/format.py

@@ -0,0 +1,105 @@
+"""JSON content type support.
+
+This module defines JSON decoding and encoding support for the DSL,
+based on the `orjson` library. It also integrates JSONPath-based
+transformations to allow querying decoded JSON structures.
+"""
+
+from functools import cache
+from typing import TYPE_CHECKING
+
+import orjson
+
+from pytest_loco.extensions import (
+    Attribute,
+    ContentDecoder,
+    ContentEncoder,
+    ContentType,
+    Schema,
+)
+
+from .transforms import query
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+if TYPE_CHECKING:
+    from pytest_loco.values import RuntimeValue
+
+
+@cache
+def _json_decode(value: bytes | str) -> 'RuntimeValue':
+    """Decode a JSON document with caching."""
+    if not isinstance(value, (bytes, str)):
+        raise TypeError('wrong type to decode')
+
+    return orjson.loads(value)
+
+
+def json_decode(value: 'RuntimeValue',
+                params: 'Mapping[str, RuntimeValue]') -> 'RuntimeValue':  # noqa: ARG001
+    """Decode a JSON string into a Python value.
+
+    This decoder parses a JSON document into native Python objects
+    using `orjson`. Decoding results are cached for reuse.
+    Decoder parameters are ignored.
+
+    Args:
+        value: JSON string to decode.
+        params: Decoder parameters (unused).
+
+    Returns:
+        Parsed Python representation of the JSON document.
+    """
+    return _json_decode(value)
+
+
+def json_encode(value: 'RuntimeValue',
+                params: 'Mapping[str, RuntimeValue]') -> str:
+    """Encode a Python value into a JSON string.
+
+    This encoder serializes a Python value into JSON using `orjson`.
+    Optional parameters control serialization behavior.
+
+    Args:
+        value: Python value to serialize.
+        params: Encoder parameters.
+
+    Returns:
+        JSON string representation of the value.
+    """
+    options = 0
+    if params.get('sort_keys'):
+        options |= orjson.OPT_SORT_KEYS
+
+    return orjson.dumps(value, option=options).decode()
+
+
+json_decoder = ContentDecoder(
+    decoder=json_decode,
+    transformers=[
+        query,
+    ],
+)
+
+json_encoder = ContentEncoder(
+    encoder=json_encode,
+    parameters=Schema({
+        'sort_keys': Attribute(
+            base=bool,
+            aliases=['sortKeys'],
+            default=False,
+            title='Sort JSON object keys',
+            description=(
+                'If enabled, JSON object keys are sorted alphabetically '
+                'during serialization.'
+            ),
+        ),
+    }),
+)
+
+json_format = ContentType(
+    name='json',
+    decoder=json_decoder,
+    encoder=json_encoder,
+)

pytest_loco_json-1.3.1/src/pytest_loco_json/instructions.py

@@ -0,0 +1,73 @@
+"""JSONPath instruction for the DSL.
+
+This module defines a DSL instruction `jq` that allows compiling
+JSONPath expressions from YAML scalar nodes. The resulting instruction
+can be used to query values from complex data structures at runtime.
+It ensures that parsing and compilation errors are wrapped in
+`DSLSchemaError` with proper YAML context.
+"""
+
+from typing import TYPE_CHECKING
+
+import jsonpath
+import yaml
+
+from pytest_loco.errors import DSLSchemaError
+from pytest_loco.extensions import Instruction
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+if TYPE_CHECKING:
+    from yaml import BaseLoader
+    from yaml.nodes import ScalarNode
+
+if TYPE_CHECKING:
+    from pytest_loco.values import Deferred, RuntimeValue
+
+
+def jsonpath_query_constructor(loader: 'BaseLoader', node: 'ScalarNode') -> 'Deferred[RuntimeValue]':
+    """Construct a precompiled JSONPath expression from a YAML scalar node.
+
+    This function is intended to be used as a YAML instruction constructor
+    in the DSL. It reads a scalar string from the YAML node, compiles it
+    into a JSONPath expression, and returns a deferred callable that can
+    be executed at runtime to query a value.
+
+    Args:
+        loader: YAML loader instance used to parse the document.
+        node: YAML scalar node containing the JSONPath expression.
+
+    Returns:
+        A deferred JSONPath object that can be called with a target value
+        to evaluate the expression.
+
+    Raises:
+        DSLSchemaError: If the JSONPath expression is invalid or
+            the YAML node cannot be processed.
+    """
+    try:
+        variable, query_string = loader.construct_scalar(node).split(' ', 1)
+        query = jsonpath.compile(query_string)
+
+    except yaml.MarkedYAMLError as base:
+        raise DSLSchemaError.from_yaml_error(base) from base
+
+    except Exception as base:
+        raise DSLSchemaError.from_yaml_node('Invalid variable or JSONPath', node) from base
+
+    def resolver(context: 'Mapping[str, RuntimeValue]') -> 'RuntimeValue':
+        """Wrapper for resolve a values by the JSONPath selector."""
+        value = context.get(variable)
+        if not value:
+            return []
+
+        return query.findall(value, filter_context=context)
+
+    return resolver
+
+
+jsonpath_query = Instruction(
+    constructor=jsonpath_query_constructor,
+    name='jsonpath',
+)

pytest_loco_json-1.3.1/src/pytest_loco_json/plugin.py

@@ -0,0 +1,16 @@
+"""JSON plugin for pytest-loco DSL.
+
+This module defines the `json` plugin that provides JSON content
+support and JSONPath-based instructions for querying data structures.
+"""
+
+from pytest_loco.extensions import Plugin
+
+from .format import json_format
+from .instructions import jsonpath_query
+
+json = Plugin(
+    name='json',
+    content_types=[json_format],
+    instructions=[jsonpath_query],
+)

pytest_loco_json-1.3.1/src/pytest_loco_json/transforms.py

@@ -0,0 +1,99 @@
+"""JSON content transformers.
+
+This module provides a DSL extension that allows extracting data
+from structured values using JSONPath expressions. The transformer
+can return either all matched items or a single selected value
+depending on configuration.
+"""
+
+from typing import TYPE_CHECKING, Literal
+
+import jsonpath
+
+from pytest_loco.extensions import Attribute, ContentTransformer, Schema
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+if TYPE_CHECKING:
+    from jsonpath import JSON
+
+if TYPE_CHECKING:
+    from pytest_loco.values import RuntimeValue
+
+
+def jsonpath_query(value: 'JSON', params: 'Mapping[str, RuntimeValue]') -> 'RuntimeValue':
+    """Query a value using a JSONPath expression.
+
+    The function applies a JSONPath query to the provided value and
+    returns either all matched items or a single item based on
+    transformer parameters.
+
+    Args:
+        value: Input value to query.
+        params: Transformer parameters.
+
+    Returns:
+        Query results.
+    """
+    query = params.get('query')
+    if not isinstance(query, str):
+        return None
+
+    items = jsonpath.findall(query, value)
+    if not params.get('exact_one'):
+        return items
+
+    if not items:
+        return None
+
+    result = None
+    match params.get('exact_mode'):
+        case 'first':
+            result = items[0]
+        case 'last':
+            result = items[-1]
+
+    return result
+
+
+query = ContentTransformer(
+    transformer=jsonpath_query,
+    name='query',
+    field=Attribute(
+        base=str,
+        aliases=['find', 'select'],
+        required=True,
+        title='JSONPath expression',
+        description=(
+            'JSONPath expression used to extract values from the input '
+            'data structure.'
+        ),
+    ),
+    parameters=Schema({
+        'exact_one': Attribute(
+            base=bool,
+            aliases=['exactOne', 'selectOne'],
+            default=True,
+            title='Return a single value',
+            description=(
+                'If enabled, the transformer returns a single matched '
+                'value instead of a list. If multiple matches are found, '
+                'the selection strategy is controlled by `exact_mode`. '
+                'If no matches are found, `None` is returned.'
+            ),
+        ),
+        'exact_mode': Attribute(
+            base=Literal['first', 'last'],
+            aliases=['exactMode', 'selectMode', 'mode'],
+            default='first',
+            examples=['first', 'last'],
+            title='Single-value selection strategy',
+            description=(
+                'Defines how a single value is selected when multiple '
+                'matches are found and ``exact_one`` is enabled. '
+                'Possible values are ``first`` and ``last``.'
+            ),
+        ),
+    }),
+)