Metadata-Version: 2.4
Name: spoof
Version: 2.4.1
Summary: A simple HTTP server for test environments
Author-email: Lex Scarisbrick <lex@scarisbrick.org>
License-Expression: MIT
Project-URL: Documentation, https://spoof.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/lexsca/spoof.git
Project-URL: Issues, https://github.com/lexsca/spoof/issues
Project-URL: Changelog, https://github.com/lexsca/spoof/blob/main/CHANGELOG.rst
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Mocking
Classifier: Topic :: Software Development :: Testing :: Traffic Generation
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Dynamic: license-file

########
Spoof 👻
########
.. image:: https://github.com/lexsca/spoof/actions/workflows/checks.yml/badge.svg
    :target: https://github.com/lexsca/spoof/actions/workflows/checks.yml
.. image:: https://img.shields.io/pypi/v/spoof.svg
    :target: https://pypi.org/project/spoof/
.. image:: https://img.shields.io/pypi/pyversions/spoof.svg
    :target: https://pypi.org/project/spoof/
.. image:: https://img.shields.io/github/license/lexsca/spoof.svg
    :target: https://github.com/lexsca/spoof/blob/master/LICENSE
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

|

**Spoof** is a simple HTTP server for test environments.

.. code-block:: python

   >>> import requests
   ... import spoof
   ...
   ... with spoof.http() as http:
   ...     http.responses.append([200, [], "This is Spoof 👻👋"])
   ...     requests.get(http.url).text
   ...
   'This is Spoof 👻👋'

A test interface for HTTP
=========================
Spoof lets you easily create HTTP servers on real network sockets.
Designed for test environments, what responses to send can be configured
anytime, including while a server is running. Requests can be
inspected live or after a response is sent.

Unlike a conventional HTTP server, where specific methods and paths are
configured in advance, Spoof accepts and records *all* requests, sending
whatever responses are queued, or a default response if the queue is empty.

Why would I want this?
======================
Have you ever wanted mock for HTTP? Ever wanted to refactor a client library,
but had no way to verify behavior apart from doing live integration testing?
If so, Spoof might be for you. Some key features:

* Decoupled requests and responses
* Concurrent servers
* SSL/TLS with post-quantum cryptography
* Proxy tunneling
* Live request debugging
* IPv6

Installation and Compatibility
==============================
Spoof is available on PyPI:

.. code-block:: console

   $ python -m pip install spoof

Spoof is tested on Python 3.10 to 3.14, uses the ``http.server`` module in
the standard library, and has no external Python dependencies.

Multiple Spoof servers can be run concurrently, and by default, the port
number is the next available port. With OpenSSL installed, Spoof can provide
SSL/TLS connectivity. HTTP proxying and IPv6 are also supported.

Response syntax
===============
Spoof expects responses to have the following syntax:

.. code-block:: python

   [httpStatus, [(headerName1, value1), (headerName2, value2)], content]

   # no content (Content-Length header is *not* sent if content is None)
   [200, [], None]

   # utf-8 content
   [200, [], "This is Spoof 👻👋"]

   # bytes content
   [200, [("Content-Type", "application/json")], b'{"success": true }']

   # responses can also be a callback, with request as the only argument
   def callback(request):
       return [200, [], request.path]

Response precedence
===================
Spoof determines what response to send to incoming requests based on
the following precedence, highest to lowest:

#. Oldest response queued in ``.responses`` using first-in, first-out (FIFO) order
#. Response stored in ``.defaultResponse`` if no responses are queued
#. Response stored in ``.errorResponse`` if ``.defaultResponse`` is ``None``

By default, Spoof will respond with an **HTTP 503 Service Unavailable** error,
because newly created Spoof instances have no responses queued and no default
response set. This requires non-error HTTP responses to be explicitly specified.

Response queue
==============
Spoof will always try to send a response from ``.responses`` first, before falling
back to ``.defaultResponse`` if the queue is empty. Backed by a
`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
instance, the ``.responses`` queue supports adding items via ``.responses.append()``
and ``.responses.extend()``, similar to a regular list.

Spoof HTTP servers run in a single background thread, so response order should
be predictable. Tests using Spoof should be able to use the same fixtures, in
the same order, and get the same results. Example queueing multiple responses,
verifying content, and request paths:

.. code-block:: python

   import requests
   import spoof

   with spoof.http() as http:
       http.responses.extend([
           [200, [("Content-Type", "application/json")], b'{"id": 1111}'],
           [200, [("Content-Type", "application/json")], b'{"id": 2222}'],
       ])
       http.defaultResponse = [404, [], "Not found"]

       assert requests.get(http.url + "/path").json() == {"id": 1111}
       assert requests.get(http.url + "/alt/path").json() == {"id": 2222}
       assert requests.get(http.url + "/oops").status_code == 404
       assert [r.path for r in http.requests] == ["/path", "/alt/path", "/oops"]

Response default
================
Spoof will always try to send a response from ``.responses`` first, before falling
back to ``.defaultResponse`` if the queue is empty. Example setting a callback as
a default response:

.. code-block:: python

   import requests
   import spoof

   with spoof.http() as http:
       http.defaultResponse = lambda request: [200, [], request.path]

       assert requests.get(http.url + "/alt").text == "/alt"

Request history
===============
Spoof records each request and appends it to the ``.requests`` property,
which is backed by a
`deque <https://docs.python.org/3/library/collections.html#collections.deque>`__
instance, the same as the ``.responses`` property. Think of it like a structured
access log. Example using request history:

.. code-block:: python

   >>> import requests
   ... import spoof
   ...
   ... with spoof.http() as http:
   ...     http.defaultResponse = [200, [], None]
   ...
   ...     [requests.get(http.url + path) for path in ["/a", "/b", "/c"]]
   ...     [f"{r.method} {r.path} {r.protocol}" for r in http.requests]
   ...
   [<Response [200]>, <Response [200]>, <Response [200]>]
   ['GET /a HTTP/1.1', 'GET /b HTTP/1.1', 'GET /c HTTP/1.1']

Request properties
==================
``SpoofRequestEnv`` instances have the following properties:

+-------------------------+----------------------------------------------+
| Property                | Description                                  |
+=========================+==============================================+
| content                 | ``bytes`` object of request content          |
+-------------------------+----------------------------------------------+
| contentEncoding         | Value of Content-Encoding header, if present |
+-------------------------+----------------------------------------------+
| contentLength           | Value of Content-Length header, if present   |
+-------------------------+----------------------------------------------+
| contentType             | Value of Content-Type header, if present     |
+-------------------------+----------------------------------------------+
| headers                 | ``http.client.HTTPMessage`` object of headers|
+-------------------------+----------------------------------------------+
| json()                  | Convenience to call ``json.loads`` on content|
+-------------------------+----------------------------------------------+
| method                  | Request method (e.g. GET, POST, HEAD)        |
+-------------------------+----------------------------------------------+
| path                    | Decoded URI path, without query string       |
+-------------------------+----------------------------------------------+
| protocol                | Protocol version (e.g. HTTP/1.0)             |
+-------------------------+----------------------------------------------+
| queryString             | Anything in URI after ``?``                  |
+-------------------------+----------------------------------------------+
| serverName              | Host name of HTTP server                     |
+-------------------------+----------------------------------------------+
| serverPort              | Port number of HTTP server                   |
+-------------------------+----------------------------------------------+
| uri                     | Raw URI path and query string, if present    |
+-------------------------+----------------------------------------------+

SSL/TLS Mode
============
Spoof can support SSL/TLS when the ``ssl=True`` argument is given, which
depends on the OpenSSL command line tools. This generates a self-signed
certificate suitable for use with localhost connections. For other
use-cases, ``spoof.ssl()`` can provide more configuration options:

.. code-block:: python

   import requests
   import spoof

   with spoof.http(ssl=True) as http:
       http.responses.append([200, [], "No self-signed cert warning!"])

       response = requests.get(http.url, verify=http.ssl.certFile)
       assert response.text == "No self-signed cert warning!"

If setting the ``verify`` option in ``requests`` isn't workable, the
``REQUESTS_CA_BUNDLE`` or ``CURL_CA_BUNDLE`` environment variables can be
set to the path of the self-signed certificate to silence SSL/TLS errors:

.. code-block:: python

   import os
   import requests
   import spoof

   with spoof.http(ssl=True) as http:
       http.responses.append([200, [], "No self-signed cert warning!"])

       os.environ["REQUESTS_CA_BUNDLE"] = http.ssl.certFile
       response = requests.get(http.url)
       assert response.text == "No self-signed cert warning!"

If `OpenSSL 3.5.0 <https://openssl-library.org/post/2025-04-08-openssl-35-final-release/>`__
or later is installed, Post-Quantum Cryptography (PQC) key algorithms can be used:

.. code-block:: python

   import requests
   import spoof

   with spoof.ssl(keyAlgorithm="mldsa65") as ssl:
       with spoof.http(ssl=ssl) as http:
           http.responses.append([200, [], "TLS with PQC Key Algorithm"])

           response = requests.get(http.url, verify=ssl.certFile)
           assert response.text == "TLS with PQC Key Algorithm"

Proxy Mode
==========
Spoof supports proxying by forwarding ``CONNECT`` requests to a
separate upstream Spoof instance when the ``proxy=True`` argument is
given. Unlike a real proxy server, Spoof won't try to connect to
external services. Example usage:

.. code-block:: python

   import requests
   import spoof

   with spoof.ssl(commonName="example.spoof") as ssl:
       with spoof.http(ssl=ssl, proxy=True) as proxy:
           proxy.upstream.defaultResponse = [200, [], "I'm here!"]

           response = requests.get(
               "https://example.spoof/ayt",
               proxies={"https": proxy.url},
               verify=ssl.certFile
           )
           assert proxy.requests[0].method == "CONNECT"
           assert proxy.requests[0].path == "example.spoof:443"
           assert proxy.upstream.requests[0].method == "GET"
           assert proxy.upstream.requests[0].path == "/ayt"
           assert response.text == "I'm here!"

If setting the ``proxies`` option in ``requests`` isn't workable, the
``https_proxy`` environment variable can be set to the URL of the proxy:

.. code-block:: python

   import os
   import requests
   import spoof

   with spoof.ssl(commonName="example.spoof") as ssl:
       with spoof.http(ssl=ssl, proxy=True) as proxy:
           proxy.upstream.defaultResponse = [200, [], "I'm here!"]

           os.environ["https_proxy"] = proxy.url
           os.environ["REQUESTS_CA_BUNDLE"] = ssl.certFile

           response = requests.get("https://example.spoof/ayt")
           assert proxy.requests[0].method == "CONNECT"
           assert proxy.requests[0].path == "example.spoof:443"
           assert proxy.upstream.requests[0].method == "GET"
           assert proxy.upstream.requests[0].path == "/ayt"
           assert response.text == "I'm here!"

IPv6 Mode
=========
Setting the ``host`` attribute to an IPv6 address will work as expected. There
is also an IPv6-only ``spoof.http6`` class that can be used if needed to
only listen on IPv6 sockets.

.. code-block:: python

   >>> import requests
   ... import spoof
   ...
   ... with spoof.http(host="::1") as http:
   ...     http.responses.append([200, [], "This is Spoof on IPv6 👀"])
   ...     requests.get(http.url).text
   ...     http.url
   ...
   'This is Spoof on IPv6 👀'
   'http://[::1]:51324'

.. code-block:: python

   >>> import requests
   ... import spoof
   ...
   ... with spoof.http6(host="localhost") as http:
   ...     http.responses.append([200, [], "This is also Spoof on IPv6 👀"])
   ...     requests.get(http.url).text
   ...     http.url
   ...
   'This is also Spoof on IPv6 👀'
   'http://[::1]:54296'

Debug mode
==========
Setting a callback with a ``breakpoint()`` can allow for live HTTP request
debugging, including setting custom responses and inspecting requests. Note
that callbacks can also be queued.

.. code-block:: python

   >>> import requests
   ... import spoof
   ...
   ... def debugCallback(request):
   ...     response = [200, [], ""]
   ...     breakpoint()
   ...     return response
   ...
   ... with spoof.http() as http:
   ...     http.defaultResponse = debugCallback
   ...     requests.get(http.url).text
   ...
   > <python-input-0>(6)debugCallback()
   (Pdb) request
   SpoofRequestEnv(content=None, contentEncoding=None, contentLength=0, contentType=None, headers=<http.client.HTTPMessage object at 0x10e16bd90>, method='GET', path='/', protocol='HTTP/1.1', queryString=None, serverName='localhost', serverPort=51612, uri='/')
   (Pdb) response[2] = "content set from pdb"
   (Pdb) c
   'content set from pdb'
