README.rst

Looking for Maintainers

We are currently looking for maintainers for Mongomock who will help advance the project, as the original authors have moved to other projects requiring all of their attention. Anyone interested, please ping @vmalloc.

What is this?

Mongomock is a small library to help testing Python code that interacts with MongoDB via Pymongo.

It can receive a record-replay style mock as an argument. In this manner we record the
expected calls (find, and then a series of updates), and replay them later.

It can receive a carefully hand-crafted mock responding to find() and update() appropriately.

Option number 1 is obviously the best approach here, since we are testing against a real mongodb
instance. However, a mongodb instance needs to be set up for this, and cleaned before/after the
test. You might want to run your tests in continuous integration servers, on your laptop, or
other bizarre platforms - which makes the mongodb requirement a liability.

We are left with #2 and #3. Unfortunately they are very high maintenance in real scenarios,
since they replicate the series of calls made in the code, violating the DRY rule. Let's see
#2 in action - we might write our test like so:

This breaks the test, although the end result being tested is just the same. The test also repeats
large portions of the code we already wrote.

We are left, therefore, with option #3 -- you want something to behave like a mongodb database
collection, without being one. This is exactly what this library aims to provide. With mongomock,
the test simply becomes:

Important Note About Project Status & Development

MongoDB is complex. This library aims at a reasonably complete mock of MongoDB for testing purposes,
not a perfect replica. This means some features are not likely to make it in any time soon.

Also, since many corner cases are encountered along the way, our goal is to try and TDD our way into
completeness. This means that every time we encounter a missing or broken (incompatible) feature, we
write a test for it and fix it. There are probably lots of such issues hiding around lurking, so feel
free to open issues and/or pull requests and help the project out!

NOTE: We don't include pymongo functionality as "stubs" or "placeholders". Since this library is
used to validate production code, it is unacceptable to behave differently than the real pymongo
implementation. In such cases it is better to throw NotImplementedError than implement a modified
version of the original behavior.

Contributing

When submitting a PR, please make sure that:

You include tests for the feature you are adding or bug you are fixing. Preferably, the test should
compare against the real MongoDB engine (see examples in tests for reference).

No existing test got deleted or unintentionally castrated

The travis build passes on your PR.

Branching model

The branching model used for this project follows the gitflow workflow. This means that pull requests
should be issued against the develop branch and not the master branch. If you want to contribute to
the legacy 2.x branch than your pull request should go into the support/2.x branch.

Acknowledgements

Mongomock has originally been developed by Rotem Yaari. It is currently being developed and maintained by Martin Domke .

Also, many thanks go to the following people for helping out, contributing pull requests and fixing bugs: