README.md in mongo-fixture-0.0.5 vs README.md in mongo-fixture-0.1.0
- old
+ new
@@ -1,17 +1,50 @@
Mongo::Fixture
===============
[](http://travis-ci.org/Fetcher/mongo-fixture) [](https://codeclimate.com/github/Fetcher/mongo-fixture)
-Just like Rails 2 fixtures, but for [MongoDB][mongo-db] (using the standard [mongo connector Gem][mongo-gem] ).
+Similar to Rails 2 fixtures, but for [MongoDB][mongo-db] (using the standard [mongo connector Gem][mongo-gem] ).
[mongo-db]: http://www.mongodb.org/
[mongo-gem]: http://rubygems.org/gems/mongo
Show off
========
+### Single collection
+
+Assuming you have a fixture for the collection `messages` with:
+```yaml
+# test/fixtures/some_data/messages.yaml
+yesterday_afternoon:
+ text: Honey, pizza tonight?
+ sent: 2012-09-11
+today_morning:
+ text: Nice date yesterday, how about next week?
+ sent: 2012-09-12
+```
+
+You can write a brief ruby script and insert the data into your mongo db:
+```ruby
+require 'mongo'
+require 'mongo-fixture'
+
+DB = Mongo::Connection.new.db 'messages-db' # An example connetion setup
+
+# Insert the fixture into the database
+fixture_some_data = Mongo::Fixture.new :some_data, DB
+
+# You can now query the fixture for the data that was sent into the DB
+fixture_some_data.messages.yesterday_afternoon.text # => "Honey, pizza tonight?"
+```
+
+The fixture is identified by the name of the folder containing the fixture YAML files. The default folder is `test/fixtures`.
+
+As you can see, each record is preceded by a name, in this case `yesterday_afternoon` and `today_morning`. This names never get inserted into the database, they are just references for making it easier to access the fixture's information.
+
+### Associations
+
Assuming you have a fixture for the collection users with:
```yaml
# test/fixtures/simple/users.yaml
john:
name: John
@@ -25,21 +58,36 @@
and for messages:
```yaml
# test/fixtures/simple/messages.yaml
greeting:
- sender_id: 1
- receiver_id: 2
+ sender:
+ users: john
+ receiver:
+ users: jane
text: Hi Jane! Long time no see.
long_time:
- sender_id: 2
- receiver_id: 1
+ sender:
+ users: jane
+ receiver:
+ users: john
text: John! Long time indeed. How are you doing?
```
-and the ruby script
+Mongo Fixture will automatically insert the object id (`_id` field in the database) for the referenced users. The Mongo Fixture syntax specifies that:
+```yaml
+ sender:
+ users: john
+```
+
+is a reference to the record named `john` in the collection `users`.
+
+> Currently Mongo Fixture does not support references from one collection to another _and back_ from that collection to the first one.
+
+For example given the ruby script:
+
```ruby
# script.rb
require "mongo-fixture"
DB = Mongo::Connection.new.db 'mongo-test-db' # Just a simple example
@@ -52,11 +100,11 @@
# http://github.com/Fetcher/symbolmatrix
fixture.rollback # returns users and messages to pristine status (#drop)
-fixture = Mongo::Fixture.new :simple, DB, false # The `false` flag prevent the constructor to automatically push
+fixture = Mongo::Fixture.new :simple, DB, false # The `false` flag prevent the constructor from automatically pushing
# the fixture into the database
fixture.check # Will fail if the user or messages collection
# were already occupied with something
@@ -66,12 +114,34 @@
```
...naturally, `mongo-fixture` makes a lot more sense within some testing framework.
-> **Note**: As of version 0.0.1, the `test/fixtures` path for fixtures is not configurable. Will solve soon.
+### Many to many associations
+As is custom in Mongo, a many-to-many association is implemented by passing an array of ids to a field in any of the records to associate. Mongo Fixture supports this. For example:
+
+```yaml
+message:
+ sender:
+ users: john
+ receivers:
+ users: [mary, sue, harry, jack]
+ text: Meeting tonight guys?
+```
+
+will insert into the `receivers` field an array with the `_id`s of the referenced users.
+
+Changing fixtures directory
+---------------------------
+
+```ruby
+require 'mongo-fixture'
+
+Mongo::Fixture.path = 'fixtures' # Now fixtures will be required from `fixtures/`
+```
+
Installation
------------
gem install mongo-fixture
@@ -81,9 +151,13 @@
And then execute:
bundle
+Future
+------
+
+- Dump from a database to fixtures! This would be awesome.
## License
Copyright (C) 2012 Fetcher