README.md

couchinator-java-wrapper

Fixtures for CouchDB and IBM Cloudant.

Setup and teardown cloudant databases with ease. Couchinator is a great tool for unit testing and more. Couchinator is both a library and a command line utility.

The project is a Java wrapper around couchinator, thus it requires Node.js.

Install

Prequisites

• Node.js 8.x or greater

Maven

<dependency>
    <groupId>io.github.cdimascio</groupId>
    <artifactId>couchinator-java-wrapper</artifactId>
    <version>2.0.1</version>
</dependency>

Gradle

compile 'io.github.cdimascio:couchinator-java-wrapper:2.0.1'

Import

import io.github.cdimascio.couchinatorw.Couchinator;

Usage

Couchinator couchinator = Couchinator.build()
// or 
Couchinator couchinator = Couchinator
	.configure
	.url("<YOUR_COUCHDB_URL>")
	.resources("./my-fixtures")
	.affectDesignDocsOnly(true)
	.build()

// Setup the databases and fixtures defined in your data layout
couchinator.create();

// Teardown, then setup the databases and fixtures defined in your data layout
couchinator.reCreate();

// Teardown the database defined in your data layout
couchinator.destroy();

Note: Couchinator will only setup and destroy databases defined in your data layout.

Junit Example

@TestInstance(TestInstance.Lifecycle.PER_CLASS)
class ExampleUnitTest {
    private Couchinator couchinator = Couchinator
		.configure()
		.url("http://localhost:5984")     // couchdb or cloudant url (include usename/password)
		.resources("./src/test/resources/fixtures")  // fixtures resource location
		.build();

    @BeforeAll
    void beforeAll() throws CouchinatorException{
    	// setup the dbs defined in your data layout
        couchinator.create();
    }

    @Test
    public void doStuff() {
        assertNotNull("test stuff");
    }

    @AfterAll
    void afterAll() throws CouchinatorException{
        // teardown the dbs defined in your data layout
        couchinator.destroy();
    }
}

Data Layout

The following sections describe how to create a data layout.

To skip directly to a working example, go here

Getting Started

Couchinator enables you to represent CouchDB and Cloudant database(s) using a simple filesystem structure that mimics the actual database structure.

A couchinator filesystem data layout might look as such:

users
    _design
        students.json
	 teachers.json
    students-docs.json
    teachers-docs.json
classrooms
    _design
        classrooms.json
        classrooms-docs.json

Create a data layout representing 2 databases

Let's create a data layout to describe two databases users and classrooms

1. Create two folders, one for users and another for classrooms.

   users/
   classrooms/

   Note: Couchinator will use the folder name as the database name

2. Within each folder optionally create a _design folder to store any design documents

   users/
       _design/
   classrooms/
       _design/

3. Create design document(s) and store them in the appropriate _design folder

   In the example below, we create two design documents in the schools database and one in the users database.

   users/
       _design/
           students.json
           teachers.json
   classrooms/
       _design/
           classrooms.json

   The contents of each design document .json must be a valid CouchDB [design document](design document).

   For example, students.json:

   {
     "_id": "_design/students",
     "views": {
       "byId": {
          "map": "function (doc) {  
          if (doc.type === 'student') {
              emit(doc._id, doc);
          }
          }"
       }
     },
     "language": "javascript"
   }

4. Create the data to store in each database

   • Data must be stored using CouchDB's bulk document format
   • The data may be stored in a single JSON file or spread across multiple JSON files (useful for organizing data)

   users/
       _design/
           students.json
           teachers.json
       students-docs.json   # contains student data
       teachers-docs.json   # contains teacher data
   
   classrooms/
       _design/
           classrooms.json
       users-docs.json

   For example, student-docs.json contains students

   {
     "docs": [
       {
         "_id": "sam895454857",
         "name": "Sam C.",
         "type": "student"
       },
       {
         "_id": "josie895454856",
         "name": "Josie D.",
         "type": "student"
       }
     ]
   }

5. Run couchinator to create each database

See Junit example

Integrating with Travis

couchinator-java-wrapper wraps couchinator, a Node.js based tool, hence to Node.js must be installed in the running environment.

language: java
jdk:
- oraclejdk8
 
before_install:
- nvm install 10 # install node.js

script:
# do stuff
# ...

License

Apache 2.0