Adapter Contract Testing

What it is

A technique to keep simulators honest. The same abstract test class is run against both the real adapter and the simulator, proving they behave identically. If the real API changes or a simulator drifts, a test fails.

See: https://github.com/adapter-contract-testing/adapter-contract-testing-papers

The pattern (canonical structure)

python
1# contracts/foo_contract.py  — the shared spec
2class FooContract(ABC):
3    @abstractmethod
4    def create_foo(self) -> Foo: ...   # only one abstract method
5
6    def test_something(self):
7        foo = self.create_foo()
8        ...
9
10# test_foo.py  — one class per implementation, nothing else
11class TestRealFoo(FooContract):
12    def create_foo(self): return RealFoo(...)
13
14class TestSimulatorFoo(FooContract):
15    def create_foo(self): return SimulatorFoo(...)

Rules

1. One abstract method — create_foo() (or create_gateway() etc.). No other setup plumbing.

2. Two concrete subclasses — real adapter + simulator. One file per port, not spread across multiple files.

3. No pytest.skip in subclasses — if a test needs pre-existing data, create_foo() must return a pre-seeded instance. A skip means the subclass doesn't honour the contract.

4. No simulator-only test classes — simulator-specific behaviour (internal state, edge cases unique to the fake) goes in standalone test_ functions in the same file, not in a third contract subclass.

5. The contract IS the port spec — every behaviour the pipeline relies on must have a test here. If you can't write a contract test for it, question whether it belongs on the port at all.

Example from this codebase

python
1# tests/contracts/smoobu_gateway_contract.py
2class SmoobuGatewayContract(ABC):
3    @abstractmethod
4    def create_gateway(self) -> SmoobuGateway: ...
5
6    def test_get_threads_non_empty(self):
7        page = self.create_gateway().get_threads(1)
8        assert len(page.threads) > 0
9
10# tests/test_smoobu_contract.py
11class TestSimulatorSmoobuContract(SmoobuGatewayContract):
12    def create_gateway(self):
13        gw = SimulatorSmoobuGateway()
14        # Pre-seed so ALL contract tests pass without skips
15        gw.inject_active_reservation(...)
16        gw.inject_guest_message(...)
17        return gw
18
19class TestSmoobuClientContract(SmoobuGatewayContract):
20    @pytest.mark.skipif(not API_KEY, reason="no credentials")
21    def create_gateway(self): return SmoobuClient(API_KEY)

What goes where