Disclaimer: Always test your application against a real Couchbase Cluster to ensure proper proper functionality

About CouchbaseMock

A little known project known as CouchbaseMock has existed for quite a while here at Couchbase. A long long time ago, back when Couchbase was still known as Membase, we needed a simple application to act as a server to test that the clients functioned properly.

CouchbaseMock still serves this purpose today; although we run an extensive suite of tests against a real cluster before each SDK release, the CouchbaseMock is still used for smoke testing (or sanity testing) before each commit is merged to the Git repository.

The ubiquity of Java and the small footprint of the mock (about a 2.5MB download) make it ideal for serving as a cluster in resource constrained systems, where a full Couchbase Cluster cannot be installed. The mock additionally contains some special commands to simulate various operations (Such as failover, rebalance, and replication) in a controlled and detereminstic manner.

In the past few weeks, I have been working on adding view support to the Mock! – you’ve heard correctly: the mock can now understand design documents, and run user-defined map or reduce functions against all documents in its database. View support was required so that I could integrate higher level functionality within the C SDK (libcouchbase), the details of which will be published in a different post.

MapReduce Views in CouchbaseMock

The mock responds properly to all the view related APIs that Couchbase offers. You can use the SDK of your choice (or curl) to issue the appropriate REST API calls to create design documents and query views.

Implementing views in the Java mock was done by embedding Mozilla Rhino (a JavaScript interpreter written in Java) into the mock. JavaScript map and reduce functions are parsed by Rhino, and are represented as Java objects to the rest of the mock code.

Special care was taken to ensure the functionality of views mirrored that of Couchbase to the smallest level of detail – this was a bit challenging, especially in the case of sorting items – as Couchbase’s sorting works a bit differently than “traditional” JavaScript sorting.

The actual JSON output was also formatted to insert line breaks after each row, to make it easier to read from the terminal.

Finally, the actual beer-sample database is also bundled with the Mock. Using XZ compression, the database takes up very little room in the actual download.

Administrative REST API in CouchbaseMock

The mock also allows the creation and deletion of buckets on the fly. You can accomplish this using the same REST API that Couchbase understands. Currently only basic bucket creation, deletion, and listing are supported, but more features may be implemented in the future.

Running CouchbaseMock

To use CouchbaseMock, first get it from the source repository:

Once built, you should have a CouchbaseMock-1.0.0-.jar in the target directory within the source repository. The  is the abbreviated sha1 from git.

Finally, using it is as simple as running:

The -S option enables the beer-sample bucket. By default the mock will run on port 8091, but this can be customized using the command line options.

Once the mock is up and running, you may interact with it from the SDK of your choosing; this includes things like performing key-value operations, defining/querying views, and creating/destroying buckets.

Final Notes

The CouchbaseMock is a convenient way to spin up “something like” a Couchbase cluster. It should work as a drop-in for most applications and SDKs – in fact, the view tests for the Mock itself are more or less copy/pasted from the Java SDK.

The mock is an internal project and its primary aim is SDK testing. As such, the mock is not the official way to test applications using Couchbase, nor is there any guarantee of stability regarding the mock’s features and interfaces – things may be added or removed as necessary.

The above being said, the mock remains a convenient way to test basic functionality of applications using couchbase (or SDKs!) without requiring a full cluster install.

Additionally, if your application itself is written in Java, you may even wish to venture inside the Mock’s source code for ways to embed it within tests.


Posted by Mark Nunberg, Software Engineer, Couchbase

Mark Nunberg is a software engineer working at Couchbase. He maintains the C client library (libcouchbase) as well as the Python client. He also developed the Perl client (for use at his previous company) - which initially led him to working at Couchbase. Prior to joining Couchbase, he worked on distributed and high performance routing systems at an eCommerce analytics firm. Mark studied Linguistics at the Hebrew University of Jerusalem.


  1. Is there any plan to include N1QL capability to this mock? We are using N1QL heavily for our app and are interested to use a mock server for that.

  2. Hi, what is the best way for me to unit test code which contacts couchbase as of today 2017, would it be the couchbase mock? (post is from 2015 want to verify i’m not missing anything).

Leave a reply