Skip to content

Latest commit

 

History

History
301 lines (235 loc) · 10.5 KB

README.md

File metadata and controls

301 lines (235 loc) · 10.5 KB
Raw

Build Status

fongo

Fongo is an in-memory java implementation of MongoDB. It intercepts calls to the standard mongo-java-driver for finds, updates, inserts, removes and other methods. The primary use is for lightweight unit testing where you don't want to spin up a mongod process.

Maven Central License Apache2

Usage

Add dependency to your project:

If you use 3.X drivers (async included)

<dependency>
  <groupId>com.github.fakemongo</groupId>
  <artifactId>fongo</artifactId>
  <version>2.1.0</version>
  <scope>test</scope>
</dependency>

Other dependency management

If you use 2.X drivers (this branch fongo-drivers-2.x) will be deprecated soon

<dependency>
  <groupId>com.github.fakemongo</groupId>
  <artifactId>fongo</artifactId>
  <version>1.6.5</version>
  <scope>test</scope>
</dependency>

Other dependency management

Alternatively: clone this repo and build the jar: mvn package then copy jar to your classpath

Use in place of regular com.mongodb.Mongo instance:

import com.github.fakemongo.Fongo;
import com.mongodb.BasicDBObject;
import com.mongodb.DB;
import com.mognodb.DBCollection;
...
Fongo fongo = new Fongo("mongo server 1");

// once you have a DB instance, you can interact with it
// just like you would with a real one.
DB db = fongo.getDB("mydb");
DBCollection collection = db.getCollection("mycollection");
collection.insert(new BasicDBObject("name", "jon"));

Scope

Fongo doesn't implement all MongoDB functionality. Most query and update syntax is supported. Gridfs and capped collections are not supported. MapReduce is in minimal way but will be enhanced soon.

  • $near can be used
  • $geoWithin can be used with $box for now.

Implementation Details

Fongo depends on Objenesis to hijack the com.mongodb.MongoClient class. It has a "provided" dependency on the mongo-java-driver and was tested with 2.13.0 and 3.0.1. It also has a "provided" dependency on sl4j-api for logging. If you don't already have sl4j in your project, you can add a maven dependency to the logback implementation like this:

<dependency> 
  <groupId>ch.qos.logback</groupId>
  <artifactId>logback-classic</artifactId>
  <version>1.1.7</version>
  <scope>test</scope>
</dependency>

Fongo should be thread safe. All read and write operations on collections are synchronized. It's pretty course, but should be good enough for simple testing. Fongo doesn't have any shared state (no statics). Each fongo instance is completely independent.

Usage Details

// Fongo instance methods

// get all created databases (they are created automatically the first time requested)
Collection<DB> dbs = fongo.getUsedDatabases();
// also
List<String> dbNames = fongo.getDatabaseNames();
// also
fongo.dropDatabase("dbName");

// get an instance of the hijacked com.mongodb.Mongo
Mongo mongo = fongo.getMongo();

If you use Spring, you can configure fongo in your XML configuration context:

<bean name="fongo" class="com.github.fakemongo.Fongo">
    <constructor-arg value="InMemoryMongo" />
</bean>
<bean id="mongo" factory-bean="fongo" factory-method="getMongo" />

<mongo:db-factory id="mongoDbFactory" mongo-ref="mongo" />

<!-- localhost settings for mongo -->
<!--<mongo:db-factory id="mongoDbFactory" />-->

<bean id="mongoTemplate" class="org.springframework.data.mongodb.core.MongoTemplate">
    <constructor-arg ref="mongoDbFactory"/>
</bean>

Junit

If you use JUnit in your project, you can use Rule to instantiate a Fongo object :

@Rule
public FongoRule fongoRule = new FongoRule();

If you need, you can easily switch to your real MongoDB server (on localhost for now).

@Rule
public FongoRule fongoRule = new FongoRule(true);

WARNING : In this case, the database WILL BE DROPPED when test is finish. So, use a random database name (e.g. UUID), BUT NOT your real database.

You can specify the version of the database with :

@Rule
public FongoRule fongoRule = new FongoRule(new ServerVersion(2, 6));

In this case, the drivers didn't handle queries with the same way.

Junit (async drivers)

If you use JUnit in your project, you can use Rule to instantiate a Fongo object :

@Rule
public FongoAsyncRule fongoAsyncRule = new FongoAsyncRule();

If you need, you can easily switch to your real MongoDB server (on localhost for now).

@Rule
public FongoAsyncRule fongoAsyncRule = new FongoAsyncRule(true);

WARNING : In this case, the database WILL BE DROPPED when test is finish. So, use a random database name (e.g. UUID), BUT NOT your real database.

You can specify the version of the database with :

@Rule
public FongoAsyncRule fongoAsyncRule = new FongoAsyncRule(new ServerVersion(2, 6));

In this case, the drivers didn't handle queries with the same way.

Text Search Simulation

Fongo simulates text search now. The results of text search are quite similar to real, but not exactly.

Next features are supported:

  • Plain words search
  • Search strings
  • Negated words
  • Projections in search query
  • Limits

Fongo text search simulation does not support:

  • Languages (including language-specific stop words)
  • Filter (maybe in future)
  • Weights in text index (we plan to support them in future)

Limitations, Differences:

  • Only text command search is supported. We will support find query with $text operator probably in future.
  • Scores in returned results are not always the same as the real Mongo's scores.
  • Only one field can be indexed as text field now. This limitation will be removed soon.

Usage example of the text search simulation:

    @Test
    public void findByTextTest() {
    //....
    //Define index:
    collection.createIndex(new BasicDBObject("myTextFieldToIndex", "text"));

    DBObject textSearchCommand = new BasicDBObject("search", "my search \"my phrase\" -without -this -words");

    //Search Command
    DBObject textSearchResult = collection.getDB()
            .command(new BasicDBObject("collection", new BasicDBObject("text", textSearchCommand)));

    //Make your assertions
    //....
	}

Todo

  • more testing
  • complete compatibility with Jongo

Reporting Bugs and submitting patches

If you discover a bug with fongo you can file an issue in github. At the very least, please include a complete description of the problem with steps to reproduce. If there were exceptions thrown, please include the complete stack traces. If it's not easy to explain the problem, failing test code would be helpful. You can fork the project and add a new failing test case.

It's even better if you can both add the test case and fix the bug. I will merge pull requests with test cases and add your name to the patch contributors below. Please maintain the same code formatting and style as the rest of the project.

Changelog

Version 2.1.0 include compatibility with 3.X async driver version. Version 2.0.0 break compatibility with 2.X driver version. Version 1.6.0 break compatibility with 2.12.X driver version.

Original Author

Patch Contributers