Skip to main content

Openmock

Mock/fake of opensearch library, allows you to mock opensearch-py

Fork of Python Elasticsearch(TM) Mock. Sometimes the developers who work with elasticsearch (TM), don't really have any input in choice of host and need to get work done.

Libraries.io dependency status for latest release Downloads

Installation

uv add --dev openmock

Documentation · Project homepage

Requires Python 3.11 or newer. Tested client/server versions and verification results are listed in the compatibility guide.

Usage

To use Openmock, decorate your test method with @openmock decorator:

from unittest import TestCase

from openmock import openmock


class TestClass(TestCase):

    @openmock
    def test_should_return_something_from_opensearch(self):
        self.assertIsNotNone(some_function_that_uses_opensearch())

Custom Behaviours

You can also force the behaviour of the OpenSearch instance by importing the openmock.behaviour module:

from unittest import TestCase

from openmock import behaviour


class TestClass(TestCase):

    ...

    def test_should_return_internal_server_error_when_simulate_server_error_is_true(self):
        behaviour.server_failure.enable()
        ...
        behaviour.server_failure.disable()

You can also disable all behaviours by calling behaviour.disable_all() (Consider put this in your def tearDown(self) method)

Available Behaviours

  • server_failure: Will make all calls to OpenSearch returns the following error message:
    {
        'status_code': 500,
        'error': 'Internal Server Error'
    }
    

Code example

Let's say you have a prod code snippet like this one:

import opensearchpy

class FooService:

    def __init__(self):
        self.es = opensearchpy.OpenSearch(hosts=[{'host': 'localhost', 'port': 9200}])

    def create(self, index, body):
        es_object = self.es.index(index, body)
        return es_object.get('_id')

    def read(self, index, id):
        es_object = self.es.get(index, id)
        return es_object.get('_source')

Then you should be able to test this class by mocking OpenSearch using the following test class:

from unittest import TestCase
from openmock import openmock
from foo.bar import FooService

class FooServiceTest(TestCase):

    @openmock
    def test_should_create_and_read_object(self):
        # Variables used to test
        index = 'test-index'
        expected_document = {
            'foo': 'bar'
        }

        # Instantiate service
        service = FooService()

        # Index document on OpenSearch
        id = service.create(index, expected_document)
        self.assertIsNotNone(id)

        # Retrieve document from OpenSearch
        document = service.read(index, id)
        self.assertEqual(expected_document, document)

Admin tools

Openmock ships three interactive admin tools for exploring fake state outside of tests.

Streamlit web UI (requires pip install openmock[web]):

openmock

Tkinter desktop GUI (requires Tk support and a graphical display):

openmock gui

FastAPI REST Bridge (requires pip install openmock[rest]):

openmock serve

These tools open a six-tab interface or an HTTP facade covering indices, search sandbox, cluster stats, CAT output, fake security (users/roles), and ingest pipelines. State in these tools is separate from your test processes.

Notes:

  • The mocked search method evaluates the query against indexed documents and returns matching results, not all documents. Use match_all to match all documents; request size or scroll to retrieve more than the default ten hits.
  • The mocked suggest method returns the exactly suggestions dictionary passed as body serialized in OpenSearch.suggest response. Attention: If the term is an int, the suggestion will be python term + 1. If not, the suggestion will be formatted as python {0}_suggestion.format(term) . Example:
    • Suggestion Body:
    suggestion_body = {
        'suggestion-string': {
            'text': 'test_text',
            'term': {
                'field': 'string'
            }
        },
        'suggestion-id': {
            'text': 1234567,
            'term': {
                'field': 'id'
            }
        }
    }
    
    • Suggestion Response:
    {
        'suggestion-string': [
            {
                'text': 'test_text',
                'length': 1,
                'options': [
                    {
                        'text': 'test_text_suggestion',
                        'freq': 1,
                        'score': 1.0
                    }
                ],
                'offset': 0
            }
        ],
        'suggestion-id': [
            {
                'text': 1234567,
                'length': 1,
                'options': [
                    {
                        'text': 1234568,
                        'freq': 1,
                        'score': 1.0
                    }
                ],
                'offset': 0
            }
        ],
    }
    

Testing

Run the full local release checks:

uv run --all-extras python scripts/check.py

Run the parity subset against a disposable Docker OpenSearch server:

uv run python scripts/opensearch_docker.py test

If you want to manage the container yourself, the backend seam is driven by OPENMOCK_TEST_BACKEND=real and OPENMOCK_REAL_OPENSEARCH_URL=http://localhost:9200. The default remains the in-memory mock backend.

The collected tests are split into two marker groups:

  • parity for live-backend parity coverage,
  • mock_backend for tests that are specific to the in-memory fake.

Examples:

uv run python -m pytest tests -m parity
uv run python -m pytest tests -m mock_backend

Won't catch pytest tests.

python -m unittest

Run the configured Python and opensearch-py compatibility matrix:

uv run tox

Changelog

See CHANGELOG.md

License

MIT with normalize_hosts.py being Apache 2 from Elasticsearch.

Metadata

Release files for openmock 3.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openmock 3.3.0
File Size Uploaded Provenance Actions
openmock-3.3.0.tar.gz 41.9 kB With provenance Details for openmock-3.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openmock 3.3.0
File Interpreter ABI Platform Actions
openmock-3.3.0-py3-none-any.whl Python 3 none any Details for openmock-3.3.0-py3-none-any.whl

Total release size: 88.5 kB

Release files / openmock-3.3.0.tar.gz

Download URL openmock-3.3.0.tar.gz
Size 41.9 kB
Tags Source
SHA-256 checksum
How to use checksums
60bd3ab83ad0c616779fc0146f1ef7e5d7730620ad056f799f16c0f71e4e5387
BLAKE2b-256 checksum
How to use checksums
eb449632e5693596d6a21895f630e354cc9888ddd4fe862d32d4842b2fec9eb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / openmock-3.3.0-py3-none-any.whl

Download URL openmock-3.3.0-py3-none-any.whl
Size 46.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d422a7a6848a29df5071503c19627c4a2ff8794a40d07f961bd23afe6f566672
BLAKE2b-256 checksum
How to use checksums
6413889832bb66a110518c8353d4feaecb4f57419e54f3ebf0e698d3133add67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for openmock 3.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openmock-3.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page