0
@@ -1 +1,96 @@
0
-see README.rdoc
0
\ No newline at end of file
0
+= Obsidian
0
+
0
+== DESCRIPTION
0
+
0
+Obsidian. It's metastable. 
0
+
0
+In the tangible world, obsidian is a naturally-occurring glass that is metastable at the earth's
0
+surface. It's commonly found within the margins of rhyolitic lava flows, where cooling of the lava is
0
+rapid. [1] In the slightly less tangible world of programming, <b>Obsidian</b> is home to chunks of
0
+Ruby code that we've found helpful. These bits of code are often found at the bottom of a mountain of
0
+yak hair, the occasionally-occurring product of simplifying various tasks.
0
+
0
+  1 http://en.wikipedia.org/wiki/Obsidian
0
+
0
+== FEATURES
0
+
0
+=== Model Update Tracker
0
+This library allows you to functionally test updates to models with clearer and more focused intent.
0
+It forces you to have a better understanding of how your objects interact and lets you demonstrate 
0
+that knowledge by specifying it in your tests.  For example, consider the following test which asserts
0
+that the code block persists an Asset record.  
0
+
0
+  assert_difference Asset :count do
0
+    post :create, :asset => {}
0
+  end
0
+
0
+Is it okay if the code block also persists a Location record? An AssetOwner record? Some other record?
0
+Chances are that the developer knows the answer to this question, but the test fails to capture that
0
+knowledge. Side effects matter, and our tests should adequately validate that the desired side effects
0
+(and <i>only</i> the desired side effects) are taking place. In the example below, assert_models_created
0
+allows us to validate that an Asset is created <i>and</i> that no other objects are inadvertently
0
+persisted.
0
+
0
+  assert_models_created(Asset) do
0
+    post :create, :asset => {}
0
+  end
0
+
0
+If the code block happened to create records other than just an Asset, a friendly test failure would let
0
+you know right away.
0
+
0
+Suppose, on the other hand, that you expect the creation of an Asset to <i>also</i> produce an AssetOwner
0
+and a Location. This is where you exercise your deep domain knowledge muscles and make your new
0
+Obsidian-powered test express and validate your intent.
0
+
0
+  assert_models_created(Asset, AssetOwner, Location) do
0
+    post: create, :asset => {}
0
+  end
0
+
0
+Now, if your code block fails to create the expected records, the above test would fail stating that it
0
+expected more to happen. If future changes to your code cause things to fall out of place, this test will
0
+catch that regression where the original assert_difference may not. In addition to assert_models_created,
0
+Model Update Tracker provides a whole host of other methods that provide similar functionality for
0
+asserting behavior related to updates, deletes, or even validating that nothing happened.
0
+
0
+* assert_models_created(models)
0
+* assert_models_updated(models)
0
+* assert_models_destroyed(models)
0
+* assert_no_models_created
0
+* assert_no_models_destroyed
0
+* assert_no_models_updated
0
+
0
+== INSTALL
0
+
0
+  sudo gem install obsidian
0
+
0
+== URLS
0
+
0
+* Log bugs, issues, and suggestions on Trac: http://opensource.thinkrelevance.com/wiki/obsidian
0
+* View Source: http://github.com/relevance/obsidian/tree/master
0
+* Git clone Source: git://github.com/relevance/obsidian.git
0
+* RDocs: http://thinkrelevance.rubyforge.org/obsidian/
0
+
0
+== LICENSE
0
+
0
+(The MIT License)
0
+
0
+Copyright (c) 2008 Relevance, Inc. - http://thinkrelevance.com
0
+
0
+Permission is hereby granted, free of charge, to any person obtaining
0
+a copy of this software and associated documentation files (the
0
+'Software'), to deal in the Software without restriction, including
0
+without limitation the rights to use, copy, modify, merge, publish,
0
+distribute, sublicense, and/or sell copies of the Software, and to
0
+permit persons to whom the Software is furnished to do so, subject to
0
+the following conditions:
0
+
0
+The above copyright notice and this permission notice shall be
0
+included in all copies or substantial portions of the Software.
0
+
0
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
0
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
0
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
0
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
0
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
0
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
0
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.