schemathesis 3.15.4__py3-none-any.whl → 4.4.2__py3-none-any.whl

schemathesis/cli/commands/run/loaders.py

@@ -0,0 +1,118 @@
+"""Automatic schema loading.
+
+This module handles the automatic detection and loading of API schemas,
+supporting both GraphQL and OpenAPI specifications.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from json import JSONDecodeError
+from typing import TYPE_CHECKING, Any, Callable
+
+from schemathesis import graphql, openapi
+from schemathesis.config import ProjectConfig
+from schemathesis.core.errors import LoaderError, LoaderErrorKind
+from schemathesis.core.fs import file_exists
+
+if TYPE_CHECKING:
+    from schemathesis.schemas import BaseSchema
+
+Loader = Callable[["ProjectConfig"], "BaseSchema"]
+
+
+def load_schema(location: str, config: ProjectConfig) -> BaseSchema:
+    """Load API schema automatically based on the provided configuration."""
+    if is_probably_graphql(location):
+        # Try GraphQL first, then fallback to Open API
+        return _try_load_schema(location, config, graphql, openapi)
+    # Try Open API first, then fallback to GraphQL
+    return _try_load_schema(location, config, openapi, graphql)
+
+
+def should_try_more(exc: LoaderError) -> bool:
+    """Determine if alternative schema loading should be attempted."""
+    import requests
+    from yaml.reader import ReaderError
+
+    if (isinstance(exc.__cause__, ReaderError) and "characters are not allowed" in str(exc.__cause__)) or (
+        isinstance(exc.__cause__, JSONDecodeError)
+        and ('"swagger"' in exc.__cause__.doc or '"openapi"' in exc.__cause__.doc)
+    ):
+        return False
+
+    # We should not try other loaders for cases when we can't even establish connection
+    return not isinstance(exc.__cause__, requests.exceptions.ConnectionError) and exc.kind not in (
+        LoaderErrorKind.OPEN_API_INVALID_SCHEMA,
+        LoaderErrorKind.OPEN_API_UNSPECIFIED_VERSION,
+        LoaderErrorKind.OPEN_API_UNSUPPORTED_VERSION,
+    )
+
+
+def detect_loader(location: str, module: Any) -> Callable:
+    """Detect API schema loader."""
+    if file_exists(location):
+        return module.from_path
+    return module.from_url
+
+
+def _try_load_schema(location: str, config: ProjectConfig, first_module: Any, second_module: Any) -> BaseSchema:
+    """Try to load schema with fallback option."""
+    from urllib3.exceptions import InsecureRequestWarning
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", InsecureRequestWarning)
+        try:
+            return _load_schema(location, config, first_module)
+        except LoaderError as exc:
+            # If this was the OpenAPI loader on an explicit OpenAPI file, don't fallback
+            if first_module is openapi and is_openapi_file(location):
+                raise exc
+            if should_try_more(exc):
+                try:
+                    return _load_schema(location, config, second_module)
+                except Exception as second_exc:
+                    if is_specific_exception(second_exc):
+                        raise second_exc
+            # Re-raise the original error
+            raise exc
+
+
+def _load_schema(location: str, config: ProjectConfig, module: Any) -> BaseSchema:
+    """Unified schema loader for both GraphQL and OpenAPI."""
+    loader = detect_loader(location, module)
+
+    kwargs: dict = {}
+    if loader is module.from_url:
+        if config.wait_for_schema is not None:
+            kwargs["wait_for_schema"] = config.wait_for_schema
+        kwargs["verify"] = config.tls_verify
+        request_cert = config.request_cert_for()
+        if request_cert:
+            kwargs["cert"] = request_cert
+        auth = config.auth_for()
+        if auth is not None:
+            kwargs["auth"] = auth
+
+    return loader(location, config=config._parent, **kwargs)
+
+
+def is_specific_exception(exc: Exception) -> bool:
+    """Determine if alternative schema loading should be attempted."""
+    return (
+        isinstance(exc, LoaderError)
+        and exc.kind == LoaderErrorKind.GRAPHQL_INVALID_SCHEMA
+        # In some cases it is not clear that the schema is even supposed to be GraphQL, e.g. an empty input
+        and "Syntax Error: Unexpected <EOF>." not in exc.extras
+    )
+
+
+def is_probably_graphql(location: str) -> bool:
+    """Detect whether it is likely that the given location is a GraphQL endpoint."""
+    return location.endswith(("/graphql", "/graphql/", ".graphql", ".gql"))
+
+
+def is_openapi_file(location: str) -> bool:
+    name = os.path.basename(location).lower()
+    return any(name == f"{base}{ext}" for base in ("openapi", "swagger") for ext in (".json", ".yaml", ".yml"))

schemathesis/cli/commands/run/validation.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import codecs
+import operator
+import pathlib
+from contextlib import contextmanager
+from functools import reduce
+from typing import Callable, Generator
+from urllib.parse import urlparse
+
+import click
+
+from schemathesis.cli.ext.options import CsvEnumChoice
+from schemathesis.config import ReportFormat, SchemathesisWarning, get_workers_count
+from schemathesis.core import errors, rate_limit, string_to_boolean
+from schemathesis.core.fs import file_exists
+from schemathesis.core.validation import has_invalid_characters, is_latin_1_encodable
+from schemathesis.filters import expression_to_filter_function
+from schemathesis.generation import GenerationMode
+from schemathesis.generation.metrics import MetricFunction
+
+INVALID_DERANDOMIZE_MESSAGE = (
+    "`--generation-deterministic` implies no database, so passing `--generation-database` too is invalid."
+)
+INVALID_REPORT_USAGE = (
+    "Can't use `--report-preserve-bytes` without enabling cassette formats. "
+    "Enable VCR or HAR format with `--report=vcr`, `--report-vcr-path`, "
+    "`--report=har`, or `--report-har-path`"
+)
+INVALID_SCHEMA_MESSAGE = "Invalid SCHEMA, must be a valid URL or file path."
+FILE_DOES_NOT_EXIST_MESSAGE = "The specified file does not exist. Please provide a valid path to an existing file."
+INVALID_BASE_URL_MESSAGE = (
+    "The provided base URL is invalid. This URL serves as a prefix for all API endpoints you want to test. "
+    "Make sure it is a properly formatted URL."
+)
+MISSING_REQUEST_CERT_MESSAGE = "The `--request-cert` option must be specified if `--request-cert-key` is used."
+
+
+def validate_schema_location(ctx: click.core.Context, param: click.core.Parameter, location: str) -> str:
+    try:
+        netloc = urlparse(location).netloc
+        if netloc:
+            validate_url(location)
+            return location
+    except ValueError as exc:
+        raise click.UsageError(INVALID_SCHEMA_MESSAGE) from exc
+    if "\x00" in location or not location:
+        raise click.UsageError(INVALID_SCHEMA_MESSAGE)
+    exists = file_exists(location)
+    if exists or bool(pathlib.Path(location).suffix):
+        if not exists:
+            raise click.UsageError(FILE_DOES_NOT_EXIST_MESSAGE)
+        return location
+    raise click.UsageError(INVALID_SCHEMA_MESSAGE)
+
+
+def validate_url(value: str) -> None:
+    from requests import PreparedRequest, RequestException
+
+    try:
+        PreparedRequest().prepare_url(value, {})
+    except RequestException as exc:
+        raise click.UsageError(INVALID_SCHEMA_MESSAGE) from exc
+
+
+def validate_base_url(ctx: click.core.Context, param: click.core.Parameter, raw_value: str) -> str:
+    try:
+        netloc = urlparse(raw_value).netloc
+    except ValueError as exc:
+        raise click.UsageError(INVALID_BASE_URL_MESSAGE) from exc
+    if raw_value and not netloc:
+        raise click.UsageError(INVALID_BASE_URL_MESSAGE)
+    return raw_value
+
+
+def validate_generation_codec(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None
+) -> str | None:
+    if raw_value is None:
+        return raw_value
+    try:
+        codecs.getencoder(raw_value)
+    except LookupError as exc:
+        raise click.UsageError(f"Codec `{raw_value}` is unknown") from exc
+    return raw_value
+
+
+def validate_rate_limit(ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None) -> str | None:
+    if raw_value is None:
+        return raw_value
+    try:
+        rate_limit.parse_units(raw_value)
+        return raw_value
+    except errors.IncorrectUsage as exc:
+        raise click.UsageError(exc.args[0]) from exc
+
+
+def validate_hypothesis_database(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None
+) -> str | None:
+    if raw_value is None:
+        return raw_value
+    if ctx.params.get("generation_deterministic"):
+        raise click.UsageError(INVALID_DERANDOMIZE_MESSAGE)
+    return raw_value
+
+
+def validate_auth(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None
+) -> tuple[str, str] | None:
+    if raw_value is not None:
+        with reraise_format_error(raw_value):
+            user, password = tuple(raw_value.split(":"))
+        if not user:
+            raise click.BadParameter("Username should not be empty.")
+        if not is_latin_1_encodable(user):
+            raise click.BadParameter("Username should be latin-1 encodable.")
+        if not is_latin_1_encodable(password):
+            raise click.BadParameter("Password should be latin-1 encodable.")
+        return user, password
+    return None
+
+
+def validate_auth_overlap(auth: tuple[str, str] | None, headers: dict[str, str]) -> None:
+    auth_is_set = auth is not None
+    header_is_set = "authorization" in {header.lower() for header in headers}
+    if len([is_set for is_set in (auth_is_set, header_is_set) if is_set]) > 1:
+        message = "The "
+        used = []
+        if auth_is_set:
+            used.append("`--auth`")
+        if header_is_set:
+            used.append("`--header`")
+        message += " and ".join(used)
+        message += " options were both used to set the 'Authorization' header, which is not permitted."
+        raise click.BadParameter(message)
+
+
+def validate_filter_expression(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None
+) -> Callable | None:
+    if raw_value:
+        try:
+            return expression_to_filter_function(raw_value)
+        except ValueError:
+            arg_name = param.opts[0]
+            raise click.UsageError(f"Invalid expression for {arg_name}: {raw_value}") from None
+    return None
+
+
+def _validate_header(key: str, value: str, where: str) -> None:
+    if not key:
+        raise click.BadParameter(f"{where} name should not be empty.")
+    if not is_latin_1_encodable(key):
+        raise click.BadParameter(f"{where} name should be latin-1 encodable.")
+    if not is_latin_1_encodable(value):
+        raise click.BadParameter(f"{where} value should be latin-1 encodable.")
+    if has_invalid_characters(key, value):
+        raise click.BadParameter(f"Invalid return character or leading space in {where.lower()}.")
+
+
+def validate_headers(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: tuple[str, ...]
+) -> dict[str, str]:
+    headers = {}
+    for header in raw_value:
+        with reraise_format_error(header):
+            key, value = header.split(":", maxsplit=1)
+        value = value.lstrip()
+        key = key.strip()
+        _validate_header(key, value, where="Header")
+        headers[key] = value
+    return headers
+
+
+def validate_request_cert_key(
+    ctx: click.core.Context, param: click.core.Parameter, raw_value: str | None
+) -> str | None:
+    if raw_value is not None and "request_cert" not in ctx.params:
+        raise click.UsageError(MISSING_REQUEST_CERT_MESSAGE)
+    return raw_value
+
+
+def validate_preserve_bytes(ctx: click.core.Context, param: click.core.Parameter, raw_value: bool) -> bool:
+    if not raw_value:
+        return False
+
+    report_formats = ctx.params.get("report_formats", []) or []
+    vcr_enabled = ReportFormat.VCR in report_formats or ctx.params.get("report_vcr_path")
+    har_enabled = ReportFormat.HAR in report_formats or ctx.params.get("report_har_path")
+
+    if not (vcr_enabled or har_enabled):
+        raise click.UsageError(INVALID_REPORT_USAGE)
+
+    return True
+
+
+def reduce_list(
+    ctx: click.core.Context, param: click.core.Parameter, value: tuple[list[str]] | None
+) -> list[str] | None:
+    if not value:
+        return None
+    return reduce(operator.iadd, value, [])
+
+
+def convert_maximize(
+    ctx: click.core.Context, param: click.core.Parameter, value: tuple[list[str]]
+) -> list[MetricFunction]:
+    from schemathesis.generation.metrics import METRICS
+
+    names: list[str] = reduce(operator.iadd, value, [])
+    return METRICS.get_by_names(names)
+
+
+def convert_generation_mode(ctx: click.core.Context, param: click.core.Parameter, value: str) -> list[GenerationMode]:
+    if value == "all":
+        return list(GenerationMode)
+    return [GenerationMode(value)]
+
+
+def convert_boolean_string(
+    ctx: click.core.Context, param: click.core.Parameter, value: str | None
+) -> str | bool | None:
+    if value is None:
+        return value
+    return string_to_boolean(value)
+
+
+@contextmanager
+def reraise_format_error(raw_value: str) -> Generator[None, None, None]:
+    try:
+        yield
+    except ValueError as exc:
+        raise click.BadParameter(f"Expected KEY:VALUE format, received {raw_value}.") from exc
+
+
+def convert_workers(ctx: click.core.Context, param: click.core.Parameter, value: str | None) -> int | None:
+    if value is None:
+        return value
+    if value == "auto":
+        return get_workers_count()
+    return int(value)
+
+
+WARNINGS_CHOICE = CsvEnumChoice(SchemathesisWarning)
+
+
+def validate_warnings(
+    ctx: click.core.Context, param: click.core.Parameter, value: str | None
+) -> bool | None | list[SchemathesisWarning]:
+    if value is None:
+        return None
+    boolean = string_to_boolean(value)
+    if isinstance(boolean, bool):
+        return boolean
+    return WARNINGS_CHOICE.convert(value, param, ctx)  # type: ignore[return-value]

schemathesis/cli/constants.py

@@ -1,3 +1,8 @@
 MIN_WORKERS = 1
 DEFAULT_WORKERS = MIN_WORKERS
 MAX_WORKERS = 64
+ISSUE_TRACKER_URL = (
+    "https://github.com/schemathesis/schemathesis/issues/new?"
+    "labels=Status%3A%20Needs%20Triage%2C+Type%3A+Bug&template=bug_report.md&title=%5BBUG%5D"
+)
+EXTENSIONS_DOCUMENTATION_URL = "https://schemathesis.readthedocs.io/en/stable/guides/extending/"

schemathesis/cli/core.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+import shutil
+
+import click
+
+
+def get_terminal_width() -> int:
+    # Some CI/CD providers (e.g. CircleCI) return a (0, 0) terminal size so provide a default
+    return shutil.get_terminal_size((80, 24)).columns
+
+
+def ensure_color(ctx: click.Context, color: bool | None) -> None:
+    if color:
+        ctx.color = True
+    elif color is False or "NO_COLOR" in os.environ:
+        ctx.color = False
+        os.environ["NO_COLOR"] = "1"

schemathesis/cli/ext/fs.py

@@ -0,0 +1,16 @@
+from pathlib import Path
+
+import click
+
+from schemathesis.core.fs import ensure_parent
+
+
+def open_file(file: Path) -> None:
+    try:
+        ensure_parent(file, fail_silently=False)
+    except OSError as exc:
+        raise click.BadParameter(f"'{file.name}': {exc.strerror}") from exc
+    try:
+        file.open("w", encoding="utf-8")
+    except (OSError, ValueError) as exc:
+        raise click.BadParameter(f"Could not open file {file.name}: {exc}") from exc

schemathesis/cli/ext/groups.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+import os
+import sys
+import textwrap
+from typing import Any, Callable, Optional
+
+import click
+
+GROUPS: dict[str, OptionGroup] = {}
+
+
+def should_use_color(ctx: click.Context) -> bool:
+    """Determine whether to use colored output in help text.
+
+    Priority (highest to lowest):
+    1. ctx.color (if explicitly set via callbacks)
+    2. --no-color flag (from command line)
+    3. --force-color flag (from command line)
+    4. NO_COLOR environment variable
+    5. TTY detection (colorize only if stdout is a TTY)
+    6. Default (False for non-TTY environments)
+    """
+    color_setting = getattr(ctx, "color", None)
+    if color_setting is not None:
+        # Explicit setting via --no-color or --force-color takes precedence
+        return bool(color_setting)
+    if "--no-color" in sys.argv:
+        # Check command line for --no-color flag (handles any order with -h)
+        return False
+    if "--force-color" in sys.argv:
+        # Check command line for --force-color flag (handles any order with -h)
+        return True
+    if "NO_COLOR" in os.environ:
+        # Respect NO_COLOR environment variable (https://no-color.org/)
+        return False
+    # Default based on TTY detection (matches Click's auto-detection)
+    # In test environments (CliRunner), stdout is not a TTY, so colors are disabled
+    return sys.stdout.isatty() if hasattr(sys.stdout, "isatty") else False
+
+
+class OptionGroup:
+    __slots__ = ("order", "name", "description", "options")
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        order: int | None = None,
+        description: str | None = None,
+    ):
+        self.name = name
+        self.description = description
+        self.order = order if order is not None else len(GROUPS) * 100
+        self.options: list[tuple[str, str]] = []
+
+
+OPTION_COLOR = "cyan"
+# Use default terminal color for better readability
+HELP_COLOR: Optional[str] = None
+SECTION_COLOR = "green"
+
+
+def _colorize_filtering_description(description: str, style_fn: Callable[..., str]) -> str:
+    replacements = [
+        ("--include-TYPE VALUE", OPTION_COLOR),
+        ("Match operations with exact VALUE", HELP_COLOR),
+        ("--include-TYPE-regex PATTERN", OPTION_COLOR),
+        ("Match operations using regular expression", HELP_COLOR),
+        ("--exclude-TYPE VALUE", OPTION_COLOR),
+        ("Exclude operations with exact VALUE", HELP_COLOR),
+        ("--exclude-TYPE-regex PATTERN", OPTION_COLOR),
+        ("Exclude operations using regular expression", HELP_COLOR),
+    ]
+    for token, color in replacements:
+        description = description.replace(token, style_fn(token, fg=color))
+    return description
+
+
+class CommandWithGroupedOptions(click.Command):
+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        # Collect options into groups or ungrouped list
+        for group in GROUPS.values():
+            group.options = []
+
+        use_color = should_use_color(ctx)
+
+        def style(text: str, **kwargs: Any) -> str:
+            # Only apply styling if colors are enabled
+            if use_color:
+                return click.style(text, **kwargs)
+            return text
+
+        for param in self.get_params(ctx):
+            rv = param.get_help_record(ctx)
+            if rv is not None:
+                option_repr, message = rv
+                if isinstance(param.type, click.Choice):
+                    message += (
+                        getattr(param.type, "choices_repr", None)
+                        or f" [possible values: {', '.join(param.type.choices)}]"
+                    )
+
+                styled_option = style(option_repr, fg=OPTION_COLOR, bold=True)
+                styled_message = style(message, fg=HELP_COLOR)
+
+                if isinstance(param, GroupedOption) and param.group is not None:
+                    option_group = GROUPS.get(param.group)
+                    if option_group is not None:
+                        option_group.options.append((styled_option, styled_message))
+                else:
+                    global_group = GROUPS.get("Global options")
+                    if global_group is not None:
+                        global_group.options.append((styled_option, styled_message))
+
+        groups = sorted(GROUPS.values(), key=lambda g: g.order)
+        # Format each group
+        for group in groups:
+            with formatter.section(style(group.name, fg=SECTION_COLOR, bold=True)):
+                if group.description:
+                    description = group.description
+                    if use_color and group.name == "Filtering options":
+                        description = _colorize_filtering_description(description, style)
+                    formatter.write(textwrap.indent(description, " " * formatter.current_indent))
+                    formatter.write("\n\n")
+
+                if group.options:
+                    formatter.write_dl(group.options)
+
+
+class StyledGroup(click.Group):
+    def format_options(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        use_color = should_use_color(ctx)
+
+        def style(text: str, **kwargs: Any) -> str:
+            # Only apply styling if colors are enabled
+            if use_color:
+                return click.style(text, **kwargs)
+            return text
+
+        options = []
+        for param in self.get_params(ctx):
+            rv = param.get_help_record(ctx)
+            if rv is not None:
+                option_repr, message = rv
+                options.append((style(option_repr, fg=OPTION_COLOR, bold=True), style(message, fg=HELP_COLOR)))
+
+        if options:
+            with formatter.section(style("Options", fg=SECTION_COLOR, bold=True)):
+                formatter.write_dl(options)
+
+        self.format_commands(ctx, formatter)
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        use_color = should_use_color(ctx)
+
+        def style(text: str, **kwargs: Any) -> str:
+            # Only apply styling if colors are enabled
+            if use_color:
+                return click.style(text, **kwargs)
+            return text
+
+        commands = []
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None:
+                continue
+            if cmd.hidden:
+                continue
+
+            commands.append((style(subcommand, fg=OPTION_COLOR, bold=True), cmd.get_short_help_str()))
+
+        if commands:
+            with formatter.section(style("Commands", fg=SECTION_COLOR, bold=True)):
+                formatter.write_dl(commands)
+
+
+class GroupedOption(click.Option):
+    def __init__(self, *args: Any, group: str | None = None, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.group = group
+
+
+def group(
+    name: str,
+    *,
+    description: str | None = None,
+) -> Callable:
+    GROUPS[name] = OptionGroup(name, description=description)
+
+    def _inner(cmd: Callable) -> Callable:
+        for param in reversed(cmd.__click_params__):  # type: ignore[attr-defined]
+            if not isinstance(param, GroupedOption) or param.group is not None:
+                break
+            param.group = name
+        return cmd
+
+    return _inner
+
+
+def grouped_option(*args: Any, **kwargs: Any) -> Callable:
+    kwargs.setdefault("cls", GroupedOption)
+    return click.option(*args, **kwargs)