mockamorph 0.4.0
Lightweight interface mocking library for Python for expectation-driven testing
Requires Python: >=3.12
Keywords: mock, mocking, pytest, testing, unittest

# Mockamorph

Lightweight interface mocking library for Python for expectation-driven testing.

> [!NOTE]
> I hate monkey-patching using string-literals in tests. I created the `mockamorph` library to simplify testing code, inspired by [uber-go/mock](https://github.com/uber-go/mock).

> [!WARNING]
> Code is written with AI assistance. List of tools used:
> - Zed Editor with Claude Opus 4.5.


## Quick Example

```python
from typing import Protocol
from mockamorph import Mockamorph


# 1. Define a class to be mocked
class UserRepository(Protocol):
    def get_user(self, user_id: int) -> str: ...
    def save_user(self, name: str) -> bool: ...


# 2. Your code that depends on the interface (the code to be tested)
class UserService:
    def __init__(self, repo: UserRepository):
        self.repo = repo

    def greet_user(self, user_id: int) -> str:
        name = self.repo.get_user(user_id)
        return f"Hello, {name}!"

    def create_user(self, name: str) -> str:
        if self.repo.save_user(name):
            return "User created"
        raise RuntimeError("Failed to save user")


# 3. Test with Mockamorph
def test_user_service():
    with Mockamorph(UserRepository) as mock:
        # Set expectations BEFORE calling code
        mock.expect(UserRepository.get_user).called_with(42).returns("Alice")
        mock.expect(UserRepository.save_user).called_with("Bob").returns(True)
        mock.expect(UserRepository.save_user).called_with("").raises(RuntimeError("Invalid name"))

        # Use the mock
        service = UserService(mock.get_mock())
        
        assert service.greet_user(42) == "Hello, Alice!"
        assert service.create_user("Bob") == "User created"
        
        with pytest.raises(RuntimeError, match="Invalid name"):
            service.create_user("")
        # Mockamorph auto-verifies all expectations were satisfied on exit
```

## Motivation

When we write code with SOLID principles in mind, there are many interfaces and usecases in our code that depend on interfaces. In production, we use adapters as concrete implementations for those interfaces, but in tests we need to rely on mocks in order to test the business logic of usecases.

Typical code looks like this:
```python
class UserRepository(Protocol):
    def get_user(self, user_id: UserID) -> User | None: ...
    def save_user(self, user: User) -> User: ...
    
@final
class CreateNewUserUsecase:
    def __init__(self, repo: UserRepository):
        self.repo = repo
        
    def create_user(self, email: str) -> User:
        ... # some business logic
        
        user = User(email=email, token=10, ...) 
        user = self.repo.save_user(user)
        
        ... # some business logic
        
        return user
```


To test such code, we need to write the following:
```python
class TestCreateNewUserUsecase(unittest.TestCase):
    def test_create_user(self):
        mock_repo = Mock()
        
        usecase = CreateNewUserUsecase(repo=mock_repo)
        email = "test@example.com"
        expected = User(email=email, token=10, id=1)

        mock_repo.save_user.return_value = expected
        result = usecase.create_user(email=email)
        self.assertEqual(result, expected)

        mock_repo.save_user.assert_called_once_with(User(email=email, token=10))
```

Note that we need to:
- Set up the mock before initializing the `CreateNewUserUsecase` class
- Set up the mocked return value right before the actual call
- Assert that the method was called with the correct arguments after the execution
- Assert that the return value is correct

This way, we need to interact with the `mock` object multiple times, increasing the complexity of the test and the possibility of human error. To simplify this process, the `Mockamorph` library was created.

The same test could be written using `Mockamorph`:
```python
def test_create_user():
    email = "test@example.com"
    
    with Mockamorph(UserRepository) as ctrl:
        ctrl.expect(UserRepository.save_user).called_with(
            User(email=email, token=10)
        ).returns(
            User(email=email, token=10, id=1)
        )
        
        usecase = CreateNewUserUsecase(ctrl.get_mock())
        usecase.create_user(email)
        # Mockamorph automatically verifies all expectations were satisfied
```

Additionally, this approach simplifies TDT (table-driven tests) by allowing you to create mocks before actual test execution.


Some toy example:
```python
from collections.abc import Callable
from typing import Protocol, TypedDict, final

from mockamorph import Mockamorph


class Greeter(Protocol):
    def greet(self, name: str) -> str: ...


@final
class GreetUsecase:
    def __init__(self, greeter: Greeter) -> None:
        self._greeter = greeter

    def execute(self, name: str | None) -> str:
        if name is None:
            return "Hello, anon!"

        return self._greeter.greet(name) + "!"


def test_greet_table_driven() -> None:
    class Test(TypedDict):
        name: str
        mock: Callable[[Mockamorph[Greeter]], None]
        input: str | None
        expected: str

    tests: list[Test] = [
        {
            "name": "greets alice",
            "mock": lambda m: m.expect(Greeter.greet).called_with("Alice").returns("Hello, Alice"),
            "input": "Alice",
            "expected": "Hello, Alice!",
        },
        {
            "name": "greets bob",
            "mock": lambda m: m.expect(Greeter.greet).called_with("Bob").returns("Hi, Bob"),
            "input": "Bob",
            "expected": "Hi, Bob!",
        },
        {
            "name": "greets empty",
            "mock": lambda m: m.expect(Greeter.greet).called_with("").returns("Hello, stranger"),
            "input": "",
            "expected": "Hello, stranger!",
        },
        {
            "name": "name is missing",
            "mock": lambda m: None,  # no calls expected
            "input": None,
            "expected": "Hello, anon!",
        },
    ]

    for tt in tests:
        with Mockamorph(Greeter) as ctrl:
            tt["mock"](ctrl)
            result = GreetUsecase(ctrl.get_mock()).execute(tt["input"])
            assert result == tt["expected"], f"Failed: {tt['name']}"

```

## Examples

### Basic Mocking

```python
from mockamorph import Mockamorph

class Calculator(Protocol):
    def add(self, a: int, b: int) -> int: ...

with Mockamorph(Calculator) as mock:
    mock.expect(Calculator.add).called_with(2, 3).returns(5)
    
    calc = mock.get_mock()
    assert calc.add(2, 3) == 5
```

Mocking custom class is also supported:
```python
class Translator:
    def get_hello(self) -> str:
        return "Hello"

class GreeterUsecase:
    def __init__(self, dep: Translator):
        self._dep = dep

    def greet(self, name: str) -> str:
        return f"{self._dep.get_hello()} {name}!"

# test with a real implementation
assert GreeterUsecase(Translator()).greet("world") == "Hello world!"

# test with a mock
with Mockamorph(Translator) as ctrl:
    ctrl.expect(Translator.get_hello).called_with().returns("Привет")

    assert GreeterUsecase(ctrl.get_mock()).greet("мир") == "Привет мир!"
```

### Multiple Return Values (FIFO)

```python
with Mockamorph(Calculator) as mock:
    mock.expect(Calculator.add).called_with(1, 1).returns(2)
    mock.expect(Calculator.add).called_with(1, 1).returns(3)  # Different return for same args
    
    calc = mock.get_mock()
    assert calc.add(1, 1) == 2  # First call
    assert calc.add(1, 1) == 3  # Second call
```

### Raising Exceptions

```python
class FileReader(Protocol):
    def read(self, path: str) -> str: ...

with Mockamorph(FileReader) as mock:
    mock.expect(FileReader.read).called_with("/missing").raises(FileNotFoundError("Not found"))
    
    reader = mock.get_mock()
    with pytest.raises(FileNotFoundError):
        reader.read("/missing")
```

### Returning Tuples

```python
class DataSource(Protocol):
    def fetch(self) -> tuple[int, str, bool]: ...

with Mockamorph(DataSource) as mock:
    # Use tuple as argument to returns() for tuple unpacking
    mock.expect().fetch().called_with().returns((42, "hello", True))
    
    source = mock.get_mock()
    x, y, z = source.fetch()
    assert (x, y, z) == (42, "hello", True)
```

### Manual Verification

```python
mock = Mockamorph(Calculator)
mock.expect(Calculator.add).called_with(1, 2).returns(3)

calc = mock.get_mock()
calc.add(1, 2)

mock.verify()  # Manually verify all expectations were satisfied
```

### Resetting Expectations

```python
mock = Mockamorph(Calculator)
mock.expect(Calculator.add).called_with(1, 2).returns(3)
mock.reset()  # Clear all expectations
mock.verify()  # Passes - no expectations to satisfy
```

### Async Support

```python
class RemoteServer(Protocol):
    async def fetch(self, resource: str) -> bytes: ...

async with Mockamorph(RemoteServer) as mock:
    mock.expect(RemoteServer.fetch).awaited_with(resource="resA").returns(b"ok")
    
    source = mock.get_mock()
    assert await source.fetch() == b"ok"
```

### Context Managers

```python
class Repository[T](Protocol):
    @contextmanager
    def session(self) -> Generator[T, None, None]: ...

    def save_user(self, session: T, user: str) -> None: ...

class Usecase:
    def __init__[T](self, dep: Repository[T]) -> None:
        self._dep = dep

    def save(self, name: str):
        with self._dep.session() as session:
            self._dep.save_user(session, "user:" + name)

mock_session = object()
test_name = "hello"

with Mockamorph(Repository[object]) as ctrl:
    ctrl.expect(Repository[object].session).entered_with().yields(mock_session)
    ctrl.expect(Repository[object].save_user).called_with(
        mock_session, f"user:{test_name}"
    ).returns(None)

    Usecase(ctrl.get_mock()).save(test_name)
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/mockamorph/mockamorph.git
cd mockamorph

# Install dependencies with uv
uv sync --all-groups
```

### Running Tests

```bash
uv run pytest .
```

### Type Checking

```bash
uv run mypy src
# or
uv run basedpyright
```

### Building

```bash
uv run hatch build
```

### Publishing

```bash
uv run hatch publish
```

## License

MIT License - see LICENSE file for details.