In the previous blog posts I explained how to use Docker containers running Couchbase during your tests. Both post had this requirements that you had to build your own Couchbase Docker image with the cluster and data already configured. In this post I will tell you how you can use our official Docker image and setup the Cluster as you wish during the setup phase of your test.

A Custom Couchbase TestContainer

TestContainers already supports several specific type of containers, especially in the relational world as you can see on their documentation. They offer some advanced features like a JDBC connection that allow you to use the underlying database directly. In the same spirit we can create a custom CouchbaseContainer that will allow you to configure the cluster and buckets during your tests.

It will be responsible for starting the docker image and returns a configured CouchbaseCluster instance. First we define the default docker image identifier and the Liveness port as port 8091. This is the one that will be tested by the default HTTP wait strategy for the path '/ui/index.html#/'. Once we can reach this page we can start setting up the cluster.

Second step is to override the configure method to make sure we expose all the necessary ports and set the HTTP wait strategy,

At this point you can test that generic container. You would get the image running in a state where you need to configure Couchbase. You need to go through all the steps of the wizard. These steps can be automated through the CLI tools or the REST API. We are going to use the API to setup the cluster.

There are three mandatory calls we need to do. One to setup the ram quotas, one to setup the username and password for admin user and one to setup the available services on the cluster(key/value, index, query and fts).

Using curl those calls would look like this:

There are multiple ways to do a POST in Java, here's an example:

All these calls will be made from the initCluster method. The content of those calls will depend on the configuration provided to the container. We can add some methods to define which services are enabled, what are the username and pasword, the ram quotas or the sample buckets to be installed.

After implementing that method, let's expose a CouchbaseEnvironnement and a CouchbaseCluster. The environnement getter is responsible for running initCluster if it has not been initialized yet. This methods also requires the custom waiting strategy wrote in the previous post. It basically polls on '/pools/default' until the first node presents a healthy state.

Here's the code of the complete class:


To use the CouchbaseContainer you can simply do something like:

If you want to only have the k/v service running with all data samples imported:

As you can see this is very simple and allow anyone to run test against Couchbase as long as they have Docker installed.


Tell us in the comments bellow if you like this and want us to provide additional configuration and shortcuts to setup your Couchbase Cluster during tests.

Posted by Laurent Doguin, Developer Advocate, Couchbase

Laurent is a Paris based Developer Advocate where he focuses on helping Java developers and the French community. He writes code in Java and blog posts in Markdown. Prior to joining Couchbase he was Nuxeo’s community liaison where he devoted his time and expertise to helping the entire Nuxeo Community become more active and efficient.

Leave a reply