schemathesis 3.36.3__tar.gz → 3.37.0__tar.gz

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/build.yml

@@ -25,7 +25,7 @@ jobs:
     name: Generic pre-commit checks
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
 
@@ -41,7 +41,7 @@ jobs:
     name: Documentation
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
       - uses: ammaraskar/sphinx-action@master
@@ -63,7 +63,7 @@ jobs:
     name: Tests (Python ${{ matrix.python }} on ${{ matrix.os }} ${{ matrix.tox_env }})
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
 
@@ -80,7 +80,7 @@ jobs:
         run: uvx --with="tox" --with="tox-gh-actions" --with="tox-uv" tox
 
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v4.5.0
+        uses: codecov/codecov-action@v4.6.0
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
 
@@ -93,7 +93,7 @@ jobs:
     name: Test piping output to a file with CP1252 encoding on ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
 

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/codeql-analysis.yml

@@ -30,7 +30,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4.1.7
+        uses: actions/checkout@v4.2.0
         with:
           # We must fetch at least the immediate parents so that if this is
           # a pull request then we can checkout the head.
@@ -38,7 +38,7 @@ jobs:
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3.26.8
+        uses: github/codeql-action/init@v3.26.11
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -49,7 +49,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v3.26.8
+        uses: github/codeql-action/autobuild@v3.26.11
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -63,4 +63,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3.26.8
+        uses: github/codeql-action/analyze@v3.26.11

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/codspeed.yml

@@ -7,11 +7,14 @@ on:
   pull_request:
   workflow_dispatch:
 
+env:
+  SCHEMATHESIS_BENCHMARK_SEED: "42"
+
 jobs:
   benchmarks:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
       - uses: actions/setup-python@v5
         with:
           # Python 3.12 for flamegraph support

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/commit.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: Check out code
-        uses: actions/checkout@v4.1.7
+        uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 0
       - name: Run commitsar

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/example-build.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
 
       - name: Start containers
         run: docker compose up -d --build

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/master_update.yml

@@ -20,7 +20,7 @@ jobs:
             tag: "latest-bookworm"
 
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
             tag-suffix: "-bookworm"
 
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
 
       - name: Docker meta
         id: meta
@@ -68,7 +68,7 @@ jobs:
     name: Build and publish package to pypi.org
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
 

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/test-corpus.yml

@@ -12,7 +12,7 @@ jobs:
     name: Default corpus tests
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
           submodules: true
@@ -29,7 +29,7 @@ jobs:
     name: Corpus tests for the coverage phase
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
           submodules: true

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/test-hypothesis.yml

@@ -11,7 +11,7 @@ jobs:
     name: Hypothesis tests with CI profile
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
 

{schemathesis-3.36.3 → schemathesis-3.37.0}/.github/workflows/update-pre-commit.yml

@@ -10,7 +10,7 @@ jobs:
     name: Update pre-commit
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4.1.7
+      - uses: actions/checkout@v4.2.0
         with:
           fetch-depth: 1
           submodules: true

{schemathesis-3.36.3 → schemathesis-3.37.0}/.pre-commit-config.yaml

@@ -3,7 +3,7 @@ default_language_version:
 
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
@@ -38,12 +38,12 @@ repos:
         additional_dependencies: [types-click, types-requests, types-PyYAML]
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.8
+    rev: v0.6.9
     hooks:
       - id: ruff-format
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.8
+    rev: v0.6.9
     hooks:
       - id: ruff
 

{schemathesis-3.36.3 → schemathesis-3.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: schemathesis
-Version: 3.36.3
+Version: 3.37.0
 Summary: Property-based testing framework for Open API and GraphQL based apps
 Project-URL: Documentation, https://schemathesis.readthedocs.io/en/stable/
 Project-URL: Changelog, https://schemathesis.readthedocs.io/en/stable/changelog.html
@@ -40,7 +40,7 @@ Requires-Dist: hypothesis[zoneinfo]<7,>=6.103.4; python_version == '3.8'
 Requires-Dist: jsonschema[format]<5.0,>=4.18.0
 Requires-Dist: junit-xml<2.0,>=1.9
 Requires-Dist: pyrate-limiter<4.0,>=2.10
-Requires-Dist: pytest-subtests<0.8.0,>=0.2.1
+Requires-Dist: pytest-subtests<0.14.0,>=0.2.1
 Requires-Dist: pytest<9,>=4.6.4
 Requires-Dist: pyyaml<7.0,>=5.1
 Requires-Dist: requests<3,>=2.22

schemathesis-3.37.0/benches/coverage_phase.py

@@ -0,0 +1,133 @@
+"""Benchmarks for the coverage phase."""
+
+import pytest
+
+from schemathesis.generation.coverage import cover_schema_iter, CoverageContext
+
+CONTEXTS = [CoverageContext.with_positive(), CoverageContext.with_negative()]
+CONTEXT_NAMES = [",".join([m.value for m in ctx.data_generation_methods]) for ctx in CONTEXTS]
+
+BASIC_TYPES = [
+    {"type": "string"},
+    {"type": "integer"},
+    {"type": "number"},
+    {"type": "boolean"},
+    {"type": "null"},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", BASIC_TYPES, ids=lambda x: f"basic-{x['type']}")
+def test_basic_types(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+STRING_CONSTRAINTS = [
+    {"type": "string", "minLength": 5},
+    {"type": "string", "maxLength": 10},
+    {"type": "string", "pattern": "^[a-z]+$"},
+    {"type": "string", "format": "email"},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", STRING_CONSTRAINTS, ids=lambda x: f"string-{list(x.keys())[1]}")
+def test_string_constraints(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+NUMBER_CONSTRAINTS = [
+    {"type": "number", "minimum": 0, "maximum": 100},
+    {"type": "integer", "multipleOf": 5},
+    {"type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 1},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", NUMBER_CONSTRAINTS, ids=lambda x: f"number-{list(x.keys())[1]}")
+def test_number_constraints(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+ARRAY_CONSTRAINTS = [
+    {"type": "array", "items": {"type": "string"}},
+    {"type": "array", "minItems": 2, "maxItems": 5},
+    {"type": "array", "uniqueItems": True},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", ARRAY_CONSTRAINTS, ids=lambda x: f"array-{list(x.keys())[1]}")
+def test_array_constraints(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+OBJECT_CONSTRAINTS = [
+    {"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}},
+    {"type": "object", "required": ["id"], "properties": {"id": {"type": "string"}}},
+    {"type": "object", "additionalProperties": False, "properties": {"key": {"type": "string"}}},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", OBJECT_CONSTRAINTS, ids=lambda x: f"object-{list(x.keys())[1]}")
+def test_object_constraints(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+# Combined schemas
+COMBINED_SCHEMAS = [
+    {"anyOf": [{"type": "string"}, {"type": "integer"}]},
+    {"oneOf": [{"type": "number", "multipleOf": 5}, {"type": "number", "multipleOf": 3}]},
+    {"allOf": [{"type": "string"}, {"minLength": 5}]},
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", COMBINED_SCHEMAS, ids=lambda x: f"combined-{list(x.keys())[0]}")
+def test_combined_schemas(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))
+
+
+COMPLEX_NESTED_SCHEMAS = [
+    {
+        "type": "object",
+        "properties": {
+            "user": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string"},
+                    "age": {"type": "integer", "minimum": 18},
+                    "emails": {"type": "array", "items": {"type": "string", "format": "email"}},
+                },
+                "required": ["name", "age"],
+            }
+        },
+    },
+    {
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "id": {"type": "integer"},
+                "tags": {"type": "array", "items": {"type": "string"}, "uniqueItems": True},
+            },
+            "required": ["id"],
+        },
+        "minItems": 1,
+        "maxItems": 10,
+    },
+]
+
+
+@pytest.mark.benchmark
+@pytest.mark.parametrize("ctx", CONTEXTS, ids=CONTEXT_NAMES)
+@pytest.mark.parametrize("schema", COMPLEX_NESTED_SCHEMAS, ids=lambda x: f"complex-{x['type']}")
+def test_complex_nested_schemas(benchmark, ctx, schema):
+    benchmark(lambda: list(cover_schema_iter(ctx, schema)))

{schemathesis-3.36.3 → schemathesis-3.37.0}/docs/changelog.rst

@@ -1,9 +1,41 @@
 Changelog
 =========
 
-:version:`Unreleased <v3.36.3...HEAD>` - TBD
+:version:`Unreleased <v3.37.0...HEAD>` - TBD
 --------------------------------------------
 
+.. _v3.37.0:
+
+:version:`3.37.0 <v3.36.4...v3.37.0>` - 2024-10-09
+--------------------------------------------------
+
+**Added**
+
+- Support for ``pytest-subtests`` up to ``0.14``.
+- Experimental "Positive Data Acceptance" check to verify that schema-conforming data receives 2xx status responses. Enable with `--experimental=positive_data_acceptance`
+- Experimental CLI options to configure the ``negative_data_rejection`` check.
+- More negative string combinations with patterns in the coverage phase.
+
+**Fixed**
+
+- Internal error in conditional hooks.
+- Negative test cases for patterns in the coverage phase.
+
+.. _v3.36.4:
+
+:version:`3.36.4 <v3.36.3...v3.36.4>` - 2024-10-05
+--------------------------------------------------
+
+**Fixed**
+
+- False positive for ``ignored_auth`` when used in stateful test runner. :issue:`2482`
+- Open Api 3.1 spec using ``$ref`` in a path is incorrectly validated as invalid. :issue:`2484`
+- Properly serialize ``seed`` in cassettes if ``--hypothesis-derandomize`` is present.
+
+**Performance**
+
+- Improvements for the coverage phase.
+
 .. _v3.36.3:
 
 :version:`3.36.3 <v3.36.2...v3.36.3>` - 2024-09-29

{schemathesis-3.36.3 → schemathesis-3.37.0}/docs/experimental.rst

@@ -144,6 +144,49 @@ Using Environment Variables
 
 For more details, join the `GitHub Discussion #2418 <https://github.com/schemathesis/schemathesis/discussions/2418>`_.
 
+Positive Data Acceptance
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Verifies that schema-conforming data receives 2xx status responses, highlighting mismatches between schema and API behavior across all endpoints.
+
+**Allowed status codes**: 2xx, 401, 403, 404
+
+**Note**: May produce false positives with complex validation that is not reflected in the schema.
+
+.. _positive-data-acceptance-cli:
+
+In CLI
+~~~~~~
+
+.. code-block:: bash
+
+   st run https://example.schemathesis.io/openapi.json --experimental=positive_data_acceptance
+
+Configuration options:
+
+.. code-block:: bash
+
+   --experimental-positive-data-acceptance-allowed-statuses=202
+
+.. _positive-data-acceptance-env-vars:
+
+Using Environment Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To enable Positive Data Acceptance via environment variables:
+
+.. code-block:: bash
+
+    export SCHEMATHESIS_EXPERIMENTAL_POSITIVE_DATA_ACCEPTANCE=true
+
+Configure status codes:
+
+.. code-block:: bash
+
+    export SCHEMATHESIS_EXPERIMENTAL_POSITIVE_DATA_ACCEPTANCE_ALLOWED_STATUSES=201,202,204
+
+For more details, join the `GitHub Discussion #2499 <https://github.com/schemathesis/schemathesis/discussions/2499>`_.
+
 .. _stateful-test-runner:
 
 New Stateful Test Runner

{schemathesis-3.36.3 → schemathesis-3.37.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "schemathesis"
-version = "3.36.3"
+version = "3.37.0"
 description = "Property-based testing framework for Open API and GraphQL based apps"
 keywords = ["pytest", "hypothesis", "openapi", "graphql", "testing"]
 authors = [{ name = "Dmitry Dygalo", email = "dmitry@dygalo.dev" }]
@@ -43,7 +43,7 @@ dependencies = [
   "jsonschema[format]>=4.18.0,<5.0",
   "junit-xml>=1.9,<2.0",
   "pyrate-limiter>=2.10,<4.0",
-  "pytest-subtests>=0.2.1,<0.8.0",
+  "pytest-subtests>=0.2.1,<0.14.0",
   "pytest>=4.6.4,<9",
   "PyYAML>=5.1,<7.0",
   "requests>=2.22,<3",

{schemathesis-3.36.3 → schemathesis-3.37.0}/src/schemathesis/cli/__init__.py

@@ -36,6 +36,7 @@ from ..filters import FilterSet, expression_to_filter_function, is_deprecated
 from ..fixups import ALL_FIXUPS
 from ..generation import DEFAULT_DATA_GENERATION_METHODS, DataGenerationMethod
 from ..hooks import GLOBAL_HOOK_DISPATCHER, HookContext, HookDispatcher, HookScope
+from ..internal.checks import CheckConfig, PositiveDataAcceptanceConfig
 from ..internal.datetime import current_datetime
 from ..internal.output import OutputConfig
 from ..internal.validation import file_exists
@@ -52,7 +53,7 @@ from .context import ExecutionContext, FileReportContext, ServiceReportContext
 from .debug import DebugOutputHandler
 from .handlers import EventHandler
 from .junitxml import JunitXMLHandler
-from .options import CsvChoice, CsvEnumChoice, CustomHelpMessageChoice, OptionalInt
+from .options import CsvChoice, CsvEnumChoice, CsvListChoice, CustomHelpMessageChoice, OptionalInt
 from .sanitization import SanitizationHandler
 
 if TYPE_CHECKING:
@@ -296,6 +297,14 @@ REPORT_TO_SERVICE = ReportToService()
     default=False,
     help="Simulate test execution without making any actual requests, useful for validating data generation",
 )
+@grouped_option(
+    "--fixups",
+    help="Apply compatibility adjustments",
+    multiple=True,
+    type=click.Choice([*ALL_FIXUPS, "all"]),
+    metavar="",
+)
+@group("Experimental options")
 @grouped_option(
     "--experimental",
     "experiments",
@@ -307,6 +316,7 @@ REPORT_TO_SERVICE = ReportToService()
             experimental.STATEFUL_TEST_RUNNER.name,
             experimental.STATEFUL_ONLY.name,
             experimental.COVERAGE_PHASE.name,
+            experimental.POSITIVE_DATA_ACCEPTANCE.name,
         ]
     ),
     callback=callbacks.convert_experimental,
@@ -314,11 +324,22 @@ REPORT_TO_SERVICE = ReportToService()
     metavar="",
 )
 @grouped_option(
-    "--fixups",
-    help="Apply compatibility adjustments",
-    multiple=True,
-    type=click.Choice([*ALL_FIXUPS, "all"]),
+    "--experimental-positive-data-acceptance-allowed-statuses",
+    "positive_data_acceptance_allowed_statuses",
+    help="Comma-separated list of status codes considered as successful responses",
+    type=CsvListChoice(),
+    callback=callbacks.convert_status_codes,
+    metavar="",
+    envvar="SCHEMATHESIS_EXPERIMENTAL_POSITIVE_DATA_ACCEPTANCE_ALLOWED_STATUSES",
+)
+@grouped_option(
+    "--experimental-negative-data-rejection-allowed-statuses",
+    "negative_data_rejection_allowed_statuses",
+    help="Comma-separated list of status codes expected for rejected negative data",
+    type=CsvListChoice(),
+    callback=callbacks.convert_status_codes,
     metavar="",
+    envvar="SCHEMATHESIS_EXPERIMENTAL_NEGATIVE_DATA_REJECTION_ALLOWED_STATUSES",
 )
 @group("API validation options")
 @grouped_option(
@@ -834,6 +855,8 @@ def run(
     set_cookie: dict[str, str],
     set_path: dict[str, str],
     experiments: list,
+    positive_data_acceptance_allowed_statuses: list[str],
+    negative_data_rejection_allowed_statuses: list[str],
     checks: Iterable[str] = DEFAULT_CHECKS_NAMES,
     exclude_checks: Iterable[str] = (),
     data_generation_methods: tuple[DataGenerationMethod, ...] = DEFAULT_DATA_GENERATION_METHODS,
@@ -1142,6 +1165,16 @@ def run(
     else:
         selected_checks = tuple(check for check in checks_module.ALL_CHECKS if check.__name__ in checks)
 
+    checks_config = CheckConfig()
+    if experimental.POSITIVE_DATA_ACCEPTANCE.is_enabled:
+        from ..specs.openapi.checks import positive_data_acceptance
+
+        selected_checks += (positive_data_acceptance,)
+        if positive_data_acceptance_allowed_statuses:
+            checks_config.positive_data_acceptance.allowed_statuses = positive_data_acceptance_allowed_statuses
+    if negative_data_rejection_allowed_statuses:
+        checks_config.negative_data_rejection.allowed_statuses = negative_data_rejection_allowed_statuses
+
     selected_checks = tuple(check for check in selected_checks if check.__name__ not in exclude_checks)
 
     if fixups:
@@ -1197,6 +1230,7 @@ def run(
         stateful_recursion_limit=stateful_recursion_limit,
         hypothesis_settings=hypothesis_settings,
         generation_config=generation_config,
+        checks_config=checks_config,
         output_config=output_config,
         service_client=client,
         filter_set=filter_set,
@@ -1300,6 +1334,7 @@ def into_event_stream(
     filter_set: FilterSet,
     # Runtime behavior
     checks: Iterable[CheckFunction],
+    checks_config: CheckConfig,
     max_response_time: int | None,
     targets: Iterable[Target],
     workers_num: int,
@@ -1358,6 +1393,7 @@ def into_event_stream(
             dry_run=dry_run,
             store_interactions=store_interactions,
             checks=checks,
+            checks_config=checks_config,
             max_response_time=max_response_time,
             targets=targets,
             workers_num=workers_num,

{schemathesis-3.36.3 → schemathesis-3.37.0}/src/schemathesis/cli/callbacks.py

@@ -344,6 +344,48 @@ def convert_checks(ctx: click.core.Context, param: click.core.Parameter, value:
     return reduce(operator.iadd, value, [])
 
 
+def convert_status_codes(
+    ctx: click.core.Context, param: click.core.Parameter, value: list[str] | None
+) -> list[str] | None:
+    if not value:
+        return value
+
+    invalid = []
+
+    for code in value:
+        if len(code) != 3:
+            invalid.append(code)
+            continue
+
+        if code[0] not in {"1", "2", "3", "4", "5"}:
+            invalid.append(code)
+            continue
+
+        upper_code = code.upper()
+
+        if "X" in upper_code:
+            if (
+                upper_code[1:] == "XX"
+                or (upper_code[1] == "X" and upper_code[2].isdigit())
+                or (upper_code[1].isdigit() and upper_code[2] == "X")
+            ):
+                continue
+            else:
+                invalid.append(code)
+                continue
+
+        if not code.isnumeric():
+            invalid.append(code)
+
+    if invalid:
+        raise click.UsageError(
+            f"Invalid status code(s): {', '.join(invalid)}. "
+            "Use valid 3-digit codes between 100 and 599, "
+            "or wildcards (e.g., 2XX, 2X0, 20X), where X is a wildcard digit."
+        )
+    return value
+
+
 def convert_code_sample_style(ctx: click.core.Context, param: click.core.Parameter, value: str) -> CodeSampleStyle:
     return CodeSampleStyle.from_str(value)