python-mocket: Mock Socket Traffic for Python Tests

Overview

Mocket is a Python testing framework that patches socket and SSL behavior to simulate network responses. It helps developers test clients that communicate over sockets without depending on live services, covering HTTP and HTTPS as well as lower-level protocols.

Use it when ordinary HTTP-only mocking is too narrow, or when tests should fail if they attempt unmocked network access. The project also offers asyncio support and an HTTPretty compatibility layer.

Key Features

• Register HTTP and HTTPS responses for client requests, including headers, bodies, and simulated socket errors.
• Match requests using custom callbacks that can inspect paths and parsed query parameters.
• Enable strict mode to raise an exception on unmocked network access, with optional host and host-port allowances.
• Support asyncio clients, including aiohttp, with a dedicated TCP connector option.
• Build custom socket-protocol mocks using its low-level framework, with HTTP and basic Redis mocks as examples.
• Record real socket traffic to JSON files for reuse in tests.
• Integrate with pook through an optional mock engine and provide an HTTPretty compatibility layer.

Use Cases

• Test an HTTP client library without reaching external services, useful for application and library test suites.
• Verify behavior for connection failures and other error paths by registering socket exceptions.
• Prevent accidental network access in tests, especially when a suite should run fully offline.
• Exercise asyncio-based HTTP clients with predictable mocked responses.
• Prototype tests for a custom database or protocol client that communicates over sockets.

Project Facts

• Language: Python
• License: BSD-3-Clause
• Stars: 311
• Forks: 51
• Topics: aiohttp, asyncio, coverage, framework, http, httpretty, https, micropython, mock, mocket, mocking, python, socket, socket-communication, socket-programming, ssl, tdd, tdd-utilities, testing, urequests
• Archived: false

Getting Started

Install from PyPI:

pip install mocket

See the README for setup examples, integrations, and configuration details.

Alternatives

• httptoolkit: HTTP Toolkit captures and mocks HTTP(S) traffic through a cross-platform debugging tool, while Mocket provides in-process socket mocks for Python tests.

Considerations

Mocket relies on patching Python's socket and SSL modules, so interactions with client libraries that initialize SSL components at import time may require importing them while Mocket is active or using the provided connector option. Its HTTP mock is not identical to HTTPretty: it uses callback-based matching rather than regex URL entries and represents errors with exceptions rather than response-body functions. The README describes Python 2.7 compatibility as ending at version 3.9.4; check the package documentation for version-specific interpreter support.