README.rdoc in assert-0.3.0 vs README.rdoc in assert-0.4.0

@@ -13,20 +13,26 @@
 
 * *Rspec*
 * *Unit/Functional/Integration/etc*: Assert is agnostic - you define whatever kinds of tests you like (one or more of the above) and assert runs them in context.
 * *Mock/Spec/BDD/Factories/etc*: Assert is the framework and there are a variety of 3rd party tools to do such things - feel free to use whatever you like.
 
+
+
 == Description
 
 Assert is a Test::Unit style testing framework.  This means you can write tests in Assert the same way you would with Test::Unit.  In addition, Assert adds some helpers and syntax sugar to enhance the way tests are written - most taken from ideas in Shoulda and Leftright.  Assert uses class-based contexts so if you want to nest your contexts, use good old inheritance.
 
 Assert is tested using itself.  The tests are a pretty good place to look for examples and usage patterns.  In addition (TODO) check out the wiki and ./examples in the source.
 
+
+
 == Installation
 
     gem install assert
 
+
+
 == Usage
 
     require 'assert'
 
     class MyTests < Assert::Context
@@ -35,22 +41,105 @@
         assert_equal 1, 1
       end
 
     end
 
+
+
+== Models
+Assert models exist to define, collect, structure, and report on Assert test data.
+
+=== Context
+Context defines the scope that tests are run in.  When tests are run, a new instance of the test context is created and the test code is evaluated within scope of this context instance.  Context provides methods for defining tests and test callbacks and for generating test results in running tests.  Subclass context classes to achieve nested context behavior
+
+=== Suite
+Suite is reponsible for collecting and structuring tests and defines the set of tests to run be the test runner.  Tests are grouped within the suite by their context.  Suite provides access to the contexts, test, and test results to both test runners and views.  In addition, the Suite model provides some stats readers (ie. run_time, runnner_seed, etc...) for use by the test runner and views.
+
+=== Test
+Test defines the test code that needs to be run and the results generated by that test code.  Tests are aware of their context and are responsible for running their code in context.
+
+=== Result
+Result defines the data related to a test result.  There are a few kinds of test results available:
+* Pass
+* Fail
+* Error
+* Skip
+* Ignore
+
+Tests can have many results of varying types.
+
+=== Macro
+Macros are procs that define sets of test code and make it available for easy reuse.  Macros work nicely with the 'should' and 'test' context methods.
+
+
+
+== Running Tests
+Assert uses a Runner object to run tests.  Any runner object should take the test suite and view as arguments and should provide a 'run' method that runs the tests and renders the view.
+
+=== Default Runner
+Assert provides a default Runner object for running test suites (https://github.com/teaminsight/assert/blob/master/lib/assert/runner.rb).  The default provides methods for running the tests, randomizing test order, and benchmarking test run time.  Feel free to extend this runner as you see fit.
+
+=== Test Order
+The default Runner object runs tests in random order and the default Terminal view will display the seed value.  If you want to run tests in a consistant order, set a 'runner_seed' environment variable.  Here's an example running tests with rake:
+
+    $ rake test   # run tests in random order
+    $ rake test runner_seed=1234  # run tests seeding with '1234'
+
+=== Rake Tasks
+Assert provides some rake task helpers that will scan your test folder and recursively generate rake tasks for each one of your test folders or files ending in '_test'.  Use this as an alternative to running ruby on each one of your test files individually.
+
+As an example, say your test folder has a file structure like so:
+
+    - test
+    |  - basic_test.rb
+    |  - helper.rb
+    |  - complex
+    |  |  - fast_tests.rb
+    |  |  - slow_tests.rb
+
+Add the following to your Rakefile to generate the test tasks:
+
+require 'assert/rake_tasks'
+Assert::RakeTasks.for(:test)
+
+This would generate following rake tasks:
+
+    $ rake -T
+    rake test                         # Run all tests
+    rake test:basic                   # Run tests for basic
+    rake test:complex                 # Run all tests for assertions
+    rake test:complex:fast            # Run tests for assertions:assert_block
+    rake test:complex:slow            # Run tests for assertions:assert_empty
+
+=== IRB with your environment loaded
+Assert provides a rake task for running irb with your test environment loaded.  Create an irb.rb file in your test file directory and have it require 'assert/setup'.  See https://github.com/teaminsight/assert/blob/master/test/irb.rb for an example.  Here's how you could use it:
+
+    $ rake irb
+    > Assert
+     => Assert
+    >
+
 == The Assert family of testing tools
 
 These are all tools that use and extend Assert.  If you write your own, share it with us and we will post it here.
 
-(TODO)
+=== assert-view
+Assert::View (https://github.com/teaminsight/assert-view) is a collection of views that can be used with Assert.  Specify what view you want to use in your ~/.assert/options.rb settings file, ie:
 
+    # default is Assert::View::Terminal.new(Assert.suite, $stdout)
+    Assert.options.view Assert::View::DifferentView.new(Assert.suite, $stdout)
+
+
+
 == Contributing
 
 The source code is hosted on Github.  It's clean, modular, and easy to understand.  Feel free to submit pull requests and file bugs on the issues tracker.
 
 One note, however: please respect that Assert itself is intended to be the flexible, base-level type logic that should change little if at all.  Pull requests for niche functionality or personal testing philosphy stuff will likely not be accepted.
 
 If you wish to extend Assert for your niche purpose/desire/philosophy, please do so in it's own gem (named 'assert-<whatever>') that uses Assert as a dependency.  When you do, tell us about it and we'll add to the Family of tools.
+
+
 
 == License
 
 Copyright (c) 2011 Kelly Redding, Collin Redding, and Team Insight