pynguin 0.48.0__tar.gz → 0.49.0.dev0__tar.gz

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pynguin
-Version: 0.48.0
+Version: 0.49.0.dev0
 Summary: Pynguin is a tool for automated unit test generation for Python
 License: MIT
 Keywords: unit test,random testing,search based,test generation

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [tool.poetry]
 name = "pynguin"
-version = "0.48.0"
+version = "0.49.0.dev"
 description = "Pynguin is a tool for automated unit test generation for Python"
 authors = [
   "Stephan Lukasczyk <stephan@pynguin.eu>",

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/src/pynguin/__version__.py

@@ -6,4 +6,4 @@
 #
 """Specifies the version of Pynguin."""
 
-__version__ = "0.48.0"
+__version__ = "0.49.0.dev"

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/src/pynguin/configuration.py

@@ -129,6 +129,25 @@ class MutationStrategy(str, enum.Enum):
     IEEE Transactions on SE 39.4 2013)"""
 
 
+class MockLLMBackend(str, enum.Enum):
+    """Where the mock-generation pipeline sends its LLM requests."""
+
+    AUTO = "AUTO"
+    """Use the proxy-cache when a proxy URL is configured, otherwise Pynguin's own
+    LLM client when an API key is available, otherwise no LLM at all."""
+
+    PROXY = "PROXY"
+    """Send classification and hint requests to the proxy-cache service."""
+
+    PYNGUIN = "PYNGUIN"
+    """Send classification and hint requests through Pynguin's own LLM client
+    (``LLM_API_KEY``/``LLM_BASE_URL``/``LLM_MODEL``), cached on disk."""
+
+    NONE = "NONE"
+    """Make no LLM calls: classify with the local rules only and configure mocks
+    from the static setups alone."""
+
+
 class RefinementGranularity(str, enum.Enum):
     """Granularity of the LLM readability & assertion refinement stages."""
 
@@ -1174,8 +1193,14 @@ class MockGenerationConfiguration:
     """Configuration for mock generation."""
 
     mock_generation_enabled: bool = False
-    """Enable the mock generation pipeline. Requires proxy_cache_url or
-    PYNGUIN_PROXY_CACHE_URL to be set, otherwise falls back to default Pynguin."""
+    """Enable the mock generation pipeline. Classes and functions the module under
+    test reaches are classified locally first; only the remaining third-party ones
+    are sent to the LLM backend selected by ``llm_backend``."""
+
+    llm_backend: MockLLMBackend = MockLLMBackend.AUTO
+    """Where classification and return-value hint requests go. ``AUTO`` prefers the
+    proxy-cache when a proxy URL is configured, then Pynguin's own LLM client when an
+    API key is available, and otherwise runs without an LLM."""
 
     proxy_cache_url: str = ""
     """Base URL of the proxy-cache service.
@@ -1186,6 +1211,34 @@ class MockGenerationConfiguration:
     When provided, the dependency analyzer consults these rules before the LLM.
     Omit to rely purely on the LLM classify endpoint."""
 
+    base_rules_path: str = ""
+    """Optional path to a local rules JSON file produced by the mock rule generator.
+    Used instead of ``base_rules_cache_id`` when set, so mined rules work without
+    the proxy-cache."""
+
+    spec_probability: float = 0.5
+    """Probability that a new mock of a known class is built as
+    ``MagicMock(spec=<class>)``. A spec'd mock passes ``isinstance`` checks and
+    raises ``AttributeError`` for attributes the class lacks; a bare mock accepts
+    everything. Mutation flips the choice, so the search keeps whichever reaches
+    more code. Expects values in [0, 1]."""
+
+    patch_calls: bool = True
+    """Also patch calls the module under test makes to external functions (e.g.
+    ``os.getenv``, ``time.time``, ``requests.get``) that the classifier marks as
+    environment, clock, randomness, or I/O boundaries. Patches are scoped to the
+    module under test during generation and exported as ``patch.object(...)``."""
+
+    patch_probability: float = 0.5
+    """Probability that a freshly generated test case patches each detected
+    external call. Expects values in [0, 1]."""
+
+    unconstructable_mock_probability: float = 0.4
+    """Probability of passing a mock (spec'd to the class) for a parameter whose
+    type Pynguin cannot construct, e.g. an abstract class or a protocol. Types that
+    can be constructed are never mocked unless they are classified boundaries.
+    Optional parameters of such types are skipped instead. Expects values in [0, 1]."""
+
 
 @dataclasses.dataclass
 class LocalSearchConfiguration:

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/src/pynguin/generator.py

@@ -97,6 +97,7 @@ from pynguin.utils.timeout import TestExecutionTimeoutError, time_limit
 if TYPE_CHECKING:
     from pynguin.analyses.module import ModuleTestCluster
     from pynguin.ga.algorithms.generationalgorithm import GenerationAlgorithm
+    from pynguin.mock_generation.mock_generator import MockGenerator
 
 if config.configuration.pynguinml.ml_testing_enabled or TYPE_CHECKING:
     from pynguin.utils.pynguinml import np_rng
@@ -644,6 +645,38 @@ def _cluster_candidate_classes(test_cluster: ModuleTestCluster) -> list[type]:
     return classes
 
 
+def _unconstructable_param_classes(test_cluster: ModuleTestCluster) -> set[str]:
+    """FQNs of parameter classes of the module under test that Pynguin cannot build.
+
+    Such parameters (abstract classes, protocols, classes without a usable
+    constructor) may receive a mock; their static setups are derived like those of
+    classified boundaries, so the mock can reach value-dependent branches.
+
+    Args:
+        test_cluster: The test cluster of the module under test.
+
+    Returns:
+        The FQNs (``module.qualname``) of those classes.
+    """
+    from pynguin.analyses.typesystem import Instance  # noqa: PLC0415
+    from pynguin.testcase.testfactory import may_mock_unconstructable  # noqa: PLC0415
+
+    out: set[str] = set()
+    for accessible in test_cluster.accessible_objects_under_test:
+        signature = getattr(accessible, "inferred_signature", None)
+        if signature is None:
+            continue
+        for param_type in signature.original_parameters.values():
+            if not isinstance(param_type, Instance):
+                continue
+            raw = param_type.type.raw_type
+            if not isinstance(raw, type):
+                continue
+            if may_mock_unconstructable(raw) and not test_cluster.get_generators_for(param_type):
+                out.add(f"{raw.__module__}.{raw.__qualname__}")
+    return out
+
+
 def _untyped_param_bindings(
     module_path: Path, candidate_classes: list[type], mock_targets: set[str]
 ) -> dict[tuple[str, str], str]:
@@ -722,6 +755,10 @@ def _apply_static_setups(  # noqa: C901
     except SyntaxError:
         return
     alias_map = ast_helpers.import_alias_map(tree)
+    # Classes the module defines itself (e.g. an abstract parameter type).
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef) and module_name:
+            alias_map.setdefault(node.name, f"{module_name}.{node.name}")
     candidates = candidate_classes or []
 
     # Index the injector's untyped bindings by callable key, as generate_templates does.
@@ -765,6 +802,127 @@ def _apply_static_setups(  # noqa: C901
                     template.setup_lines.append(line)
 
 
+def _resolve_fqn(fqn: str) -> Any:
+    """Import the object a fully-qualified name stands for.
+
+    Args:
+        fqn: A dotted name such as ``requests.sessions.Session``.
+
+    Returns:
+        The object, or None if no prefix of *fqn* imports as a module holding it.
+    """
+    parts = fqn.split(".")
+    for split in range(len(parts) - 1, 0, -1):
+        try:
+            obj: Any = importlib.import_module(".".join(parts[:split]))
+        except Exception:  # noqa: BLE001, S112
+            continue
+        for name in parts[split:]:
+            obj = getattr(obj, name, None)
+            if obj is None:
+                break
+        if obj is not None:
+            return obj
+    return None
+
+
+def _apply_spec_paths(module: types.ModuleType, mock_targets: set[str]) -> None:
+    """Record how each mocked class is spelled from the module under test.
+
+    The path lets a mock be rendered as ``MagicMock(spec=module_0.<path>)`` without
+    importing anything else into the generated test.
+
+    Args:
+        module: The module under test.
+        mock_targets: The FQNs of the mocked classes.
+    """
+    import pynguin.testcase.mock_templates_store as _mock_store  # noqa: PLC0415
+    from pynguin.mock_generation.patch_targets import (  # noqa: PLC0415
+        find_attribute_path,
+    )
+
+    for fqn in sorted(mock_targets):
+        obj = _resolve_fqn(fqn)
+        if obj is None:
+            continue
+        path = find_attribute_path(module, obj)
+        if path is None:
+            continue
+        _mock_store.MOCK_SPEC_PATHS[fqn] = path
+        template = _mock_store.MOCK_TEMPLATES_BY_TARGET.get(fqn)
+        if template is not None:
+            template.spec_path = path
+
+
+def _setup_patch_templates(
+    module: types.ModuleType,
+    gen: MockGenerator,
+    base_rules_cache_id: str | None,
+    rules_path: Path | None,
+) -> int:
+    """Find the external functions the module under test calls and pick those to patch.
+
+    Each candidate goes through the same classifier as the mocked classes; every
+    callee decided as ``mock`` becomes a patch template whose return values come
+    from the static analysis of its call sites.
+
+    Args:
+        module: The module under test.
+        gen: The mock generator whose classifier decides.
+        base_rules_cache_id: proxy-cache rule set to consult before the LLM.
+        rules_path: local rules JSON, used instead of *base_rules_cache_id*.
+
+    Returns:
+        The number of patch templates created.
+    """
+    import pynguin.testcase.mock_templates_store as _mock_store  # noqa: PLC0415
+    from pynguin.mock_generation import patch_targets  # noqa: PLC0415
+    from pynguin.mock_generation.mock_generator import (  # noqa: PLC0415
+        MockTemplate,
+        MutableSetup,
+    )
+
+    module_path = Path(str(module.__file__))
+    source = module_path.read_text(encoding="utf-8")
+    candidates = patch_targets.find_patch_candidates(source, module)
+    if not candidates:
+        return 0
+    analyzer = gen.analyzer(module_path, base_rules_cache_id, rules_path)
+    decisions = {
+        decision.target: decision
+        for decision in analyzer.classify_targets([
+            (target.fqn, callee) for target, callee in candidates
+        ])
+    }
+    for target, _callee in candidates:
+        decision = decisions.get(target.fqn)
+        if decision is None or decision.decision != "mock":
+            continue
+        mutable, lines = patch_targets.patch_setups(source, target)
+        dependency = target.attribute.lower()
+        _mock_store.MOCK_PATCH_TEMPLATES.append(
+            MockTemplate(
+                dependency=dependency,
+                import_path=target.fqn.split(".", maxsplit=1)[0],
+                mock_target=target.fqn,
+                setup_code=f"mock_{dependency} = MagicMock()",
+                setup_lines=lines,
+                mutable_setups=[
+                    MutableSetup(target=chain, candidates=cands) for chain, cands in mutable
+                ],
+                patch_target=target,
+            )
+        )
+        _LOGGER.info(
+            "Mock generation: patching %s (%s: %s), setups=%s",
+            target.fqn,
+            decision.source,
+            decision.reason,
+            [(chain, cands) for chain, cands in mutable] + lines,
+        )
+    return len(_mock_store.MOCK_PATCH_TEMPLATES)
+
+
 def _setup_mock_generation(test_cluster: ModuleTestCluster) -> None:
     """Run the mock pipeline and record its statistics.
 
@@ -781,16 +939,20 @@ def _setup_mock_generation(test_cluster: ModuleTestCluster) -> None:
     stat.track_output_variable(RuntimeVariable.MockTargetsFromLLM, metrics["from_llm"])
     stat.track_output_variable(RuntimeVariable.MockHintTargets, metrics["hint_targets"])
     stat.track_output_variable(RuntimeVariable.MockUntypedParams, metrics["untyped_params"])
+    stat.track_output_variable(RuntimeVariable.MockPatchTargets, metrics["patch_targets"])
     stat.track_output_variable(RuntimeVariable.MockGenerationTime, metrics["time"])
 
 
 def _run_mock_generation(test_cluster: ModuleTestCluster) -> dict[str, Any]:
     """Run the mock pipeline and store templates for statement insertion.
 
-    Feeds the proxy-cache-generated mock templates to the test factory (via the shared
+    Feeds the mock templates to the test factory (via the shared
     ``mock_templates_store``) so that, when Pynguin needs a value of a
     mocked-library type, it inserts a mock statement configured from the
-    corresponding template (return values / side effects included).
+    corresponding template (return values / side effects included). External
+    functions the module calls and the classifier marks as ``mock`` become patch
+    templates. The LLM backend (proxy-cache or Pynguin's own client) is optional;
+    without one only rules, default patch rules, and static setups are used.
 
     Args:
         test_cluster: supplies the classes an untyped parameter may statically
@@ -807,23 +969,23 @@ def _run_mock_generation(test_cluster: ModuleTestCluster) -> dict[str, Any]:
         "from_llm": 0,
         "hint_targets": 0,
         "untyped_params": 0,
+        "patch_targets": 0,
         "time": 0.0,
     }
 
     if not config.configuration.mock_generation.mock_generation_enabled:
         return metrics
 
-    from pynguin.mock_generation.proxy_cache_resolver import (  # noqa: PLC0415
-        get_proxy_cache_url,
-    )
+    from pynguin.mock_generation import llm_backend  # noqa: PLC0415
 
-    if not get_proxy_cache_url():
+    backend = llm_backend.active_backend()
+    if backend == config.MockLLMBackend.NONE:
         _LOGGER.warning(
-            "Mock generation is enabled but no proxy-cache URL found. "
-            "Set PYNGUIN_PROXY_CACHE_URL or --proxy_cache_url. "
-            "Falling back to default Pynguin without mocks."
+            "Mock generation runs without an LLM: no proxy-cache URL and no LLM API key. "
+            "Only rules, default patch rules, and static setups are used."
         )
-        return metrics
+    else:
+        _LOGGER.info("Mock generation LLM backend: %s", backend.value)
 
     module_name = config.configuration.module_name
     module = sys.modules.get(module_name)
@@ -836,7 +998,11 @@ def _run_mock_generation(test_cluster: ModuleTestCluster) -> dict[str, Any]:
         MockGenerator,
     )
 
-    base_rules_cache_id = config.configuration.mock_generation.base_rules_cache_id or None
+    mock_config = config.configuration.mock_generation
+    base_rules_cache_id = mock_config.base_rules_cache_id or None
+    rules_path = Path(mock_config.base_rules_path) if mock_config.base_rules_path else None
+    _mock_store.MOCK_SPEC_PATHS = {}
+    _mock_store.MOCK_PATCH_TEMPLATES = []
 
     # Classes an untyped parameter could statically match. Computed unconditionally
     # so untyped parameters are mocked directly (no type tracing required).
@@ -844,11 +1010,12 @@ def _run_mock_generation(test_cluster: ModuleTestCluster) -> dict[str, Any]:
 
     start = time.perf_counter()
     try:
-        gen = MockGenerator(use_proxy=True)
+        gen = MockGenerator(use_llm=backend != config.MockLLMBackend.NONE)
         gen.generate_for_module(
             Path(str(module.__file__)),
             base_rules_cache_id,
             candidate_classes=candidate_classes,
+            rules_path=rules_path,
         )
         _mock_store.MOCK_TARGETS = gen.mock_targets
         _mock_store.MOCK_UNTYPED_PARAMS = _untyped_param_bindings(
@@ -878,27 +1045,39 @@ def _run_mock_generation(test_cluster: ModuleTestCluster) -> dict[str, Any]:
             mock_hint_generator,
         )
 
-        templates = mock_hint_generator.generate_templates(
-            Path(str(module.__file__)),
-            gen.mock_targets,
-            candidate_classes,
-            module_name=module_name,
-            untyped_bindings=_mock_store.MOCK_UNTYPED_PARAMS,
+        templates = (
+            mock_hint_generator.generate_templates(
+                Path(str(module.__file__)),
+                gen.mock_targets,
+                candidate_classes,
+                module_name=module_name,
+                untyped_bindings=_mock_store.MOCK_UNTYPED_PARAMS,
+            )
+            if backend != config.MockLLMBackend.NONE
+            else {}
         )
         _mock_store.MOCK_TEMPLATES_BY_TARGET = templates
         metrics["hint_targets"] = len(templates)
 
         # Static, deterministic return-value setups derived from the SUT itself
         # (branch constants + iteration defaults), so bare mocks reach value-
-        # dependent branches even when the proxy-cache returned no hints.
+        # dependent branches even when the LLM returned no hints. Parameter types
+        # Pynguin cannot construct get them too, as they may be mocked.
+        mockable = gen.mock_targets | _unconstructable_param_classes(test_cluster)
         _apply_static_setups(
             Path(str(module.__file__)),
-            gen.mock_targets,
+            mockable,
             candidate_classes,
             module_name,
             _mock_store.MOCK_UNTYPED_PARAMS,
         )
 
+        _apply_spec_paths(module, mockable)
+        if mock_config.patch_calls:
+            metrics["patch_targets"] = _setup_patch_templates(
+                module, gen, base_rules_cache_id, rules_path
+            )
+
         for fqn, template in templates.items():
             for setup in template.mutable_setups:
                 _LOGGER.info(

{pynguin-0.48.0 → pynguin-0.49.0.dev0}/src/pynguin/mock_generation/dependency_analyzer.py

@@ -6,9 +6,10 @@
 #
 """Classifies the external classes a module uses as 'mock', 'skip', or 'unknown'.
 
-Each candidate is a fully-qualified class name (target).  Classification order,
-first match wins: exception class -> skip, standard library -> skip, heuristic
-rule -> mock, proxy-cache (LLM) -> mock/skip, otherwise unknown.
+Each candidate is a fully-qualified class or function name (target).
+Classification order, first match wins: exception class -> skip, project under
+test -> skip, heuristic rule -> mock, default patch rule (functions) -> mock,
+standard library -> skip, LLM backend -> mock/skip, otherwise unknown.
 """
 
 from __future__ import annotations
@@ -21,6 +22,7 @@ import sys
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
+import pynguin.configuration as config
 from pynguin.mock_generation import llm_classifier_client
 
 if TYPE_CHECKING:
@@ -84,13 +86,20 @@ class DependencyAnalyzer:
         heuristic_rules: HeuristicRules | None = None,
         *,
         rules_cache_id: str | None = None,
-        use_proxy: bool = False,
+        rules_path: Path | None = None,
+        use_llm: bool = False,
     ) -> None:
-        """module_path: SUT source file; rules_cache_id: proxy-cache rules set to load."""
+        """Create an analyzer for one module.
+
+        module_path: SUT source file; rules_path: local rules JSON (preferred over
+        rules_cache_id, a proxy-cache rules set to load).
+        """
         self._module_path = module_path
-        self._use_proxy = use_proxy
+        self._use_llm = use_llm
         if heuristic_rules is not None:
             self._rules = heuristic_rules
+        elif rules_path is not None:
+            self._rules = HeuristicRules(rules_path)
         elif rules_cache_id:
             self._rules = self._load_rules(rules_cache_id)
         else:
@@ -172,58 +181,87 @@ class DependencyAnalyzer:
     # Classification
 
     def _classify_local(self, target: str, obj: Any) -> MockDecision | None:
-        """Deterministic classification (exception/stdlib/rule); None if proxy-cache needed."""
+        """Deterministic classification; None if the LLM is needed.
+
+        Order: exception class -> skip, defined in the project under test -> skip,
+        mined rule -> mock, default patch rule (functions only) -> mock, standard
+        library -> skip.
+        """
         if isinstance(obj, type) and issubclass(obj, BaseException):
             return MockDecision(target, "skip", "Exception class", "exception", 1.0)
-        if target.split(".", 1)[0] in sys.stdlib_module_names:
-            return MockDecision(target, "skip", "Standard library", "stdlib", 1.0)
+        if self._is_local(target, obj):
+            return MockDecision(target, "skip", "Defined in the project under test", "local", 1.0)
         reason = self._rules.match(target)
         if reason is not None:
             return MockDecision(target, "mock", reason, "rule", 0.9)
+        if obj is not None and not isinstance(obj, type) and callable(obj):
+            from pynguin.mock_generation.patch_targets import (  # noqa: PLC0415
+                DEFAULT_PATCH_RULES,
+            )
+
+            if target in DEFAULT_PATCH_RULES:
+                return MockDecision(
+                    target, "mock", "Environment, clock, randomness, or I/O", "rule", 1.0
+                )
+        if target.split(".", 1)[0] in sys.stdlib_module_names:
+            return MockDecision(target, "skip", "Standard library", "stdlib", 1.0)
         return None
 
+    @staticmethod
+    def _is_local(target: str, obj: Any) -> bool:
+        """Whether *target* belongs to the project the module under test is part of.
+
+        Such classes and functions are the code under test and should be exercised,
+        not replaced by a mock.
+        """
+        sut_top = config.configuration.module_name.split(".", 1)[0]
+        if not sut_top:
+            return False
+        defining = getattr(obj, "__module__", None) or target
+        return defining.split(".", 1)[0] == sut_top
+
     def _classify(self, target: str, obj: Any) -> MockDecision:
         """Classify a single class *target* (with its resolved *obj* when available)."""
         local = self._classify_local(target, obj)
         if local is not None:
             return local
-        if self._use_proxy:
-            proxy = self._classify_via_proxy(target)
-            if proxy is not None:
-                return proxy
+        if self._use_llm:
+            decision = self._classify_via_llm(target)
+            if decision is not None:
+                return decision
         return MockDecision(target, "unknown", "Unclassified external class", "llm", 0.0)
 
     def _classify_all(self, pairs: list[tuple[str, Any]]) -> list[MockDecision]:
-        """Classify many candidates, batching the proxy-cache calls into one request."""
+        """Classify many candidates, batching the LLM calls into one request."""
         local: dict[str, MockDecision] = {}
-        proxy_needed: list[str] = []
+        llm_needed: list[str] = []
         for target, obj in pairs:
             decision = self._classify_local(target, obj)
             if decision is not None:
                 local[target] = decision
             else:
-                proxy_needed.append(target)
+                llm_needed.append(target)
 
-        proxy = self._classify_via_proxy_batch(proxy_needed) if self._use_proxy else {}
+        llm = self._classify_via_llm_batch(llm_needed) if self._use_llm else {}
 
         decisions: list[MockDecision] = []
         for target, _obj in pairs:
             decisions.append(
                 local.get(target)
-                or proxy.get(target)
+                or llm.get(target)
                 or MockDecision(target, "unknown", "Unclassified external class", "llm", 0.0)
             )
         return decisions
 
     @staticmethod
-    def _classify_via_proxy_batch(targets: list[str]) -> dict[str, MockDecision]:
-        """Batch-classify *targets* via the proxy-cache; empty dict on connection/HTTP error."""
+    def _classify_via_llm_batch(targets: list[str]) -> dict[str, MockDecision]:
+        """Batch-classify *targets* via the LLM backend; empty dict on any error."""
         if not targets:
             return {}
         try:
             results = llm_classifier_client.classify_targets_batch(targets)
         except Exception as exc:  # noqa: BLE001
-            _logger.warning("Proxy batch classify unavailable (%d): %s", len(targets), exc)
+            _logger.warning("LLM batch classify unavailable (%d): %s", len(targets), exc)
             return {}
         return {
             target: MockDecision(
@@ -237,12 +275,12 @@ class DependencyAnalyzer:
         }
 
     @staticmethod
-    def _classify_via_proxy(target: str) -> MockDecision | None:
-        """MockDecision from the proxy-cache, or None on connection/HTTP error."""
+    def _classify_via_llm(target: str) -> MockDecision | None:
+        """MockDecision from the LLM backend, or None on any error."""
         try:
             result = llm_classifier_client.classify_target(target)
         except Exception as exc:  # noqa: BLE001
-            _logger.warning("Proxy classify unavailable for %r: %s", target, exc)
+            _logger.warning("LLM classify unavailable for %r: %s", target, exc)
             return None
         return MockDecision(
             target,