[Feature Request] enhancing for `spec` / `create_autospec` and error handling.

[skokado]

Feature requests in PyCon JP 2025 Sprint.

1. Add supoprt for differnt types of Mock Creation

Extend the mock system to support different ways of generating mocks (autospec, spec, magic, default). This allows developers to enforce stricter testing, handle special SDKs, and test side effects more realistically.

Motivation
Inspired from unittest.mock usage, we can make restrictly for test target class / module.

• Current mocks only support return_value and side_effect.

Example interfaces are:

• Enforce correct signatures (autospec).
• Limit attribute exposure (spec).
• Handle dunder methods (magic).
• Fall back to lightweight mocks (default).

Example: mocking genai.generate_content with either autospec or side effect behavior.

{
  "mocked_modules": {
    "genai": {
      "methods": {
        "generate_content": {
          "mode": "autospec",
          "return_value": "my_val",
          "side_effect": "ValueError"
        }
      }
    }
  }
}

• mode: "default" | "autospec" | "spec" | "magic"
• return_value: any JSON-serializable value (optional)
• side_effect:
  • String: exception name (e.g. "ValueError")
  • List: sequence of values/exceptions
  • Future: callable reference

2. Automatically mock stop

referring from @patch decorator, following idea would be useful?

• As is:

class TestFileSystem(unittest.TestCase):
    def setUp(self):
        self.mock_manager = MockManager('./mocks/os_mock_data.json')
        self.mock_manager.apply_mocks()

    def tearDown(self):
        self.mock_manager.stop_mocks()

    ...

• To be?

@mock_from_json(path="./mocks/os_mock_data.json")
class TestFileSystem(unittest.TestCase):
    # setUp and tearDown is unnecessary

    ...

[ChefTDD]

Below is a generated proposal. @buildingBlaiseLabs can take a look at this later.

Goal

Provide a drop-in alternative to unittest.mock that:

• Creates mocks (autospec, spec, magic, default)

• Saves/loads them as JSON

• Works without the real SDK installed

• Automatically applies/stops mocks in tests

---

1. Key Features

Feature	Description
auto_serialize()	Wraps create_autospec; builds a mock and JSON in one step.
MockSerializer	Converts mocks ↔ JSON, storing spec snapshots and side effects.
MockManager.from_json()	Decorator that auto-loads mocks for test classes.
ensure_module_exists()	Creates fake SDK modules if missing.
Modes Supported	"default", "magic", "spec", "autospec".

---

2. Developer Flow

Step 1 — Create and Serialize a Mock

from sdk_mocks import auto_serialize
import boto3
mock, _ = auto_serialize(

target=boto3.client,

instance=True,

return_values={"list_buckets": {"Buckets": ["test-bucket"]}},

save_path="./mocks/boto3_s3.json"

)

Step 2 — Use It in Tests

from sdk_mocks import MockManager
import unittest
@MockManager.from_json("./mocks/boto3_s3.json")

class TestS3(unittest.TestCase):

def test_list_buckets(self):

import boto3

s3 = boto3.client("s3")

self.assertEqual(s3.list_buckets(), {"Buckets": ["test-bucket"]})

No manual setUp/tearDown.
Works even if boto3 isn’t installed.

---

3. Core APIs (Simplified)

auto_serialize

def auto_serialize(target, instance=False, return_values=None,
                   save_path=None, mode="autospec", side_effects=None):
    # create mock, apply values, serialize, optionally save

MockSerializer

• to_json(mock) → dict with mode, spec snapshot, return values, side effects

• from_json(data) → rebuilds mock

• MagicMockGen() → optional global patch for create_autospec

MockManager.from_json

@classmethod
def from_json(cls, path):
    def decorator(test_cls):
        def setUp(self):
            self.mock_manager = cls(path)
            self.mock_manager.apply_mocks()
        def tearDown(self):
            self.mock_manager.stop_mocks()
        test_cls.setUp, test_cls.tearDown = setUp, tearDown
        return test_cls
    return decorator

---

4. Example JSON Output

{
  "mocked_modules": {
    "boto3": {
      "create_if_missing": true,
      "methods": {
        "client": {
          "mode": "autospec",
          "spec_snapshot": {
            "name": "S3Client",
            "methods": {
              "list_buckets": {"signature": "(self)"}
            }
          },
          "return_value": {"Buckets": ["test-bucket"]},
          "side_effect": null
        }
      }
    }
  }
}

---

5. Benefits

• Drop-in familiar API

• No SDK dependency required

• Zero boilerplate tests

• Portable, version-controlled mocks

• Clear extensibility for new SDKs or modes

---