assert 1.1.0 → 2.0.0.rc.1

data/.assert.rb

@@ -0,0 +1,3 @@
+Assert.configure do |c|
+  # puts "Applying local settings..."
+end

data/README.md

@@ -1,7 +1,34 @@
-# The Assert testing framework
+# The Assert Testing Framework
 
 Test::Unit style testing framework, just better than Test::Unit.
 
+## Usage
+
+```ruby
+# in test/my_tests.rb
+
+require 'assert'
+
+class MyTests < Assert::Context
+
+  def test_something
+    assert_equal 1, 1
+  end
+
+end
+```
+
+```sh
+$ assert test/my_tests.rb
+Loaded suite (1 test)
+Running tests in random order, seeded with "33650"
+.
+
+1 result: pass
+
+(0.000199 seconds)
+```
+
 ## What Assert is
 
 * **Framework**: you define tests and the context they run in - Assert runs them.  Everything is pure ruby so use any 3rd party testing tools you like.  Create 3rd party tools that extend Assert behavior.
@@ -17,106 +44,170 @@ Test::Unit style testing framework, just better than Test::Unit.
 
 ## 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](https://github.com/thoughtbot/shoulda) and [Leftright](https://github.com/jordi/leftright/).  Assert uses class-based contexts so if you want to nest your contexts, use good old inheritance.
+Assert is a Test::Unit style testing framework.  This means you can write tests in Assert the same way you would with test-unit.
 
-Assert is tested using itself.  The tests are a pretty good place to look for examples and usage patterns.
+In addition, Assert adds some helpers and syntax sugar to enhance the way tests are written. Most are taken from ideas in [Shoulda](https://github.com/thoughtbot/shoulda) and [Leftright](https://github.com/jordi/leftright/).  Assert uses class-based contexts so if you want to nest your contexts, use inheritance.
 
-## Installation
+**Note**: Assert is tested using itself.  The tests are a pretty good place to look for examples and usage patterns.
 
-```
-$ gem install assert
+## CLI
+
+```sh
+$ assert --help
 ```
 
-## Usage
+Assert ships with a CLI for running tests.  Test files must end in `_tests.rb` (or `_test.rb`).  The CLI globs any given file path(s), requires any test files, and runs the tests in them.
 
-```ruby
-require 'assert'
+As an example, say your test folder has a file structure like so:
 
-class MyTests < Assert::Context
+```
+- test
+|  - basic_tests.rb
+|  - helper.rb
+|  - complex_tests.rb
+|  - complex
+|  |  - fast_tests.rb
+|  |  - slow_tests.rb
+```
 
-  def test_something
-    assert_equal 1, 1
-  end
+* `$ assert` - runs all tests ('./test' is used if no paths are given)
+* `$ assert test/basic` - run all tests in basic_tests.rb
+* `$ assert test/complex/fast_tests.rb` - runs all tests in fast_tests.rb
+* `$ assert test/basic test/comp` - runs all tests in basic_tests.rb, complex_tests.rb, fast_tests.rb and slow_tests.rb
+
+All you need to do is pass some sort of existing file path (hint: use tab-completion) and Assert will find any test files and run the tests in them.
+
+## Configuring Assert
 
+```ruby
+Assert.configure do |config|
+  # set your config options here
 end
 ```
 
-## Models
+Assert uses a config pattern for specifying settings.  Using this pattern, you can configure settings, extensions, custom views, etc.  Settings can be configured in 4 different scopes and are applied in this order: User, Local, CLI, ENV.
 
-Assert models exist to define, collect, structure, and report on Assert test data.
+### User settings
 
-### Suite
+Assert will look for and require the file `$HOME/.assert/initializer.rb`.  Use this file to specify user settings.  User settings can be overridden by Local, CLI, and ENV settings.
 
-A `Suite` object is reponsible for collecting and structuring tests and defines the set of tests to run using the test `Runner`.  Tests are grouped within the suite by their context.  Suite provides access to the contexts, tests, and test results.  In addition, the Suite model provides some stats (ie. run_time, runner_seed, etc...).
+### Local settings
 
-### Runner
+Assert will look for and require the file `./.assert.rb`.  Use this file to specify project settings.  Local settings can be overridden by CLI, and ENV settings.
 
-A `Runner` object is responsible for running a suite of tests and firing event callbacks to the `View`.  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.
+To specify a custom local settings file path, use the `ASSERT_LOCALFILE` env var.
 
-### Context
+### CLI settings
 
-A `Context` object is 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 the 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.
+Assert accepts options from its CLI.  Use these options to specify runtime settings.  CLI settings can be overridden by ENV settings.
 
-### Test
+### ENV settings
 
-A `Test` object 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.
+Assert uses ENV vars to drive certain settings.  Use these vars to specify absolute runtime settings.  ENV settings are always applied last and cannot be overridden.
 
-### Result
+## Running Tests
 
-A `Result` object defines the data related to a test result.  There are a few kinds of test results available:
+Assert uses its [`Assert::Runner`](/lib/assert/runner.rb) to run tests.  You can extend this default runner or use your own runner implementation.  Specify it in your user/local settings:
 
-* `Pass`
-* `Fail`
-* `Error`
-* `Skip`
-* `Ignore`
+```ruby
+require 'my_awesome_runner_class'
 
-Tests produce results as they are executed.  Every `assert` statement produces a result.  Some results, like `Error` and `Skip`, will halt execution.  `Pass` and `Ignore` results do not halt execution.  `Fail` results, by default, halt execution but there is an option to have them not halt execution.  Therefore, tests can have many results of varying types.
+Assert.configure do |config|
+  config.runner MyAwesomeRunnerClass.new
+end
+```
 
-### View
+### Test Dir
 
-A `View` object is responsible for rendering test result output.  Assert provides a `Assert::View::Base` object to provide common helpers and default runner callback handlers for building views.  Assert also provides a `Assert::View::DefaultView` that it renders its output with.  See the "Viewing Test Results" section below for more details.
+By default Assert expects tests in the `test` dir.  The is where it looks for the helper file and is the default path used when running `$ assert`.  To override this dir, do so in your user/local settings file:
 
-### Macro
+```ruby
+Assert.configure do |config|
+  config.test_dir "testing"
+end
+```
 
-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.
+### Test Helper File
 
-## User Options and Helpers
+By default Assert will look for a file named `helper.rb` in the `test_dir` and require it (if found) just before running the tests.  To override the helper file name, do so in your user/local settings file:
 
-Assert provides ways for setting user-specfic options and helpers.  When Assert is setting itself up, the last setup step is to look for and require the file `~/.assert/options.rb`.  This file is essentially a user level test helper file.  Use it to set options, configure assert extensions, setup/define how to view test results, etc.
+```ruby
+Assert.configure do |config|
+  config.test_helper "some_helpers.rb"
+end
+```
 
-## Running Tests
+### Test Order
 
-Assert uses its [`Assert::Runner`](https://github.com/teaminsight/assert/blob/master/lib/assert/runner.rb) object to run tests by default.  This runner runs its suite's tests in random order based on the suite's `runner_seed`.
+The default runner object runs tests in random order.  To run tests in a consistant order, specify a custom runner seed:
 
-You can extend this default runner or use your own runner implementation.  Either way, specify that you want to use your new runner class by adding this to your user options file
+In user/local settings file:
 
 ```ruby
-Assert.runner  MyAwesomeRunner
+Assert.configure do |config|
+  config.runner_seed 1234
+end
 ```
 
-### Test Order
+Using the CLI:
+
+```sh
+$ assert [-s|--seed] 1234
+```
 
-The default runner object runs tests in random order and the `DefaultView` 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:
+Using an ENV var:
 
+```sh
+$ ASSERT_RUNNER_SEED=1234 assert
 ```
-$ rake test                   # run tests in random order
-$ rake test runner_seed=1234  # run tests seeding with '1234'
+
+### Showing Output
+
+By default, Assert shows any output on `$stdout` produced while running a test.  It provides a setting to override whether to show this output or to 'capture' it and show it with the test result details:
+
+In user/local settings file:
+
+```ruby
+Assert.configure do |config|
+  config.show_output false
+end
 ```
 
-## Viewing Test Results
+Using the CLI:
 
-You have a few options when it comes to viewing test results in Assert.  Assert comes with its own `DefaultView` class that handles displaying test results.
+```sh
+$ assert [-o|--show-output|--no-show-output]
+```
+
+### Failure Handling
+
+By default, Assert will halt test execution when a test produces a Fail result.  It provides a setting to override this default:
 
-First, lets look at the default: `Assert::View::DefaultView`.  This is the default view class.  Its output goes something like this:
+In user/local settings file:
+
+```ruby
+Assert.configure do |config|
+  config.halt_on_fail false
+end
+```
+
+Using the CLI:
+
+```sh
+$ assert [-t|--halt|--no-halt]
+```
+
+## Viewing Test Results
+
+`Assert::View::DefaultView` is the default handler for viewing test results.  Its output goes something like this:
 
 * before the run starts, output some info about the test suite that is about to run
 * print out result abbreviations as the test results are generated
 * after the run finishes...
-* display any result details (from failing or error results) in reverse test/result order
-* output some summary info
+ * display any result details (from failing or error results) in reverse test/result order
+ * output some summary info
 
-You can run assert's test suite using `rake test` and get a feel for what this default outputs.  This view has a few options you can tweak:
+You can run a test suite and get a feel for what this default outputs.  The view has a few options you can tweak:
 
 * `styled`: whether to apply ANSI styles to the output, default `true`
 * `pass_styles`: how to style pass result output, default `:green`
@@ -125,20 +216,24 @@ You can run assert's test suite using `rake test` and get a feel for what this d
 * `skip_styles`: default `:cyan`
 * `ignore_styles`: default: `:magenta`
 
-To override an option, do so in your user options file:
+To override an option, do so in your user/local settings:
 
 ```ruby
-Assert.view.options.styled  false
+Assert.configure do |config|
+  config.view.styled false
+end
 ```
 
-However, the view you use is configurable.  Define you own view class and specify it in your `~/.assert/options.rb` file:
+However, the view hanlder you use is itself configurable.  Define you own view handler class and specify it in your user/local settings:
 
 ```ruby
 class MyCustomView < Assert::View::Base
   # define your view here...
 end
 
-Assert.options.view  MyCustomView.new
+Assert.configure do |config|
+  config.view MyCustomView.new
+end
 ```
 
 ### Anatomy of a View
@@ -157,17 +252,17 @@ Available callbacks from the runner, and when they are called:
 * `after_test`: after a test finishes running, the test is passed as an arg
 * `on_finish`: when the test suite is finished running
 
-Beyond that, each view can do as it sees fit.  Initialize how you wish, take whatever options you'd like, and output results as you see fit, given the available callbacks.
+Beyond that, each view can do as it sees fit.  Initialize how you wish, take whatever settings you'd like, and output results as you see fit, given the available callbacks.
 
 ### Using 3rd party views
 
-To use a 3rd party custom view, you first require it in and then specify using the `Assert.options.view` option.  Assert provides a helper for requiring in views.  It can be used in two ways.  You can pass a fully qualified path to the helper and if it exists, will require it in.
+To use a 3rd party custom view, first require it in and then configure it.  Assert provides a helper for requiring in views.  It can be used in two ways.  You can pass a fully qualified path to the helper and if it exists, will require it in.
 
 ```ruby
 Assert::View.require_user_view '/path/to/my/view'
 ```
 
-Alternatively, you can install/clone/copy/write your view implementations in `~/.assert/views` and require it in by name.  To have assert require it by name, have it installed at `~/assert/views/view_name/lib/view_name.rb` (this structure is compatible with popular conventions in rubygem development). For example:
+Alternatively, you can install/clone/copy/write your view implementations in `~/.assert/views` and require it in by name.  To have assert require it by name, have it installed at `~/assert/views/view_name/lib/view_name.rb` (this structure is compatible with popular conventions for rubygem development). For example:
 
 ```ruby
 # assuming ~/.assert/views/my-custom-view/lib/my-custom-view.rb exists
@@ -177,75 +272,54 @@ Assert::View.require_user_view 'my-custom-view'
 
 Once your view class is required in, use it and configure it just as you would any view.
 
-## Failure Handling
-
-Assert, by default, will halt test execution when a test produces a Fail result.  However, Assert provides an option to not halt when Fail results are produced.  You can control how assert handles fails by either setting a user option (in your user `~/.assert/options.rb` file):
-
-```ruby
-Assert::Test.options.halt_on_fail  false   # force not halting on fail results
-```
+## Assert Models
 
-or by setting an env variable:
+### Suite
 
-```
-$ rake test halt_on_fail=true             # force halt on failure using an env var
-```
+A `Suite` object is reponsible for collecting and structuring tests and defines the set of tests to run using the test `Runner`.  Tests are grouped within the suite by their context.  Suite provides access to the contexts, tests, and test results.  In addition, the Suite model provides some stats (ie. run_time, runner_seed, etc...).
 
-## Rake Tasks
+### Runner
 
-**Note**: rake task handling is deprecated and will be removed in v2.0
+A `Runner` object is responsible for running a suite of tests and firing event callbacks to the `View`.  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.
 
-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.  Test files must end in either `'_test.rb'` or `'_tests.rb'`.  Use this as an alternative to running ruby on each one of your test files individually.
+### Context
 
-As an example, say your test folder has a file structure like so:
+A `Context` object is 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 the 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.
 
-```
-- test
-|  - basic_test.rb
-|  - helper.rb
-|  - complex
-|  |  - fast_tests.rb
-|  |  - slow_tests.rb
-```
+### Test
 
-Add the following to your Rakefile to generate the test tasks:
+A `Test` object 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.
 
-```ruby
-require 'assert/rake_tasks'
-Assert::RakeTasks.install
-```
+### Result
 
-This would generate following rake tasks:
+A `Result` object defines the data related to a test result.  There are a few kinds of test results available:
 
-```
-$ 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
-```
+* `Pass`
+* `Fail`
+* `Error`
+* `Skip`
+* `Ignore`
 
-By default, the rake tasks do not show which test files are being loaded.  If you want to see this output from the rake tasks, set a "show_loaded_files" environment variable at the rake command line:
+Tests produce results as they are executed.  Every `assert` statement produces a result.  Some results, like `Error` and `Skip`, will halt execution.  `Pass` and `Ignore` results do not halt execution.  `Fail` results, by default, halt execution but there is an option to have them not halt execution.  Therefore, tests can have many results of varying types.
 
-```
-$ rake test show_loaded_files=true  # run the tests showing which files were loaded
-```
+### View
 
-## IRB with your environment loaded
+A `View` object is responsible for rendering test result output.  Assert provides a `Assert::View::Base` object to provide common helpers and default runner callback handlers for building views.  Assert also provides a `Assert::View::DefaultView` that it renders its output with.  See the "Viewing Test Results" section below for more details.
 
-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 [Assert's irb.rb](https://github.com/teaminsight/assert/blob/master/test/irb.rb) for an example.  Here's how you could use it:
+### Macro
 
-```
-$ rake irb
-> Assert
- => Assert
-```
+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.
 
 ## The Assert family of testing tools
 
 TODO: add in references to assert related tools.
 
+## Installation
+
+```
+$ gem install assert
+```
+
 ## Contributing
 
 The source code is hosted on Github.  Feel free to submit pull requests and file bugs on the issues tracker.
@@ -258,6 +332,6 @@ If submitting a Pull Request, please:
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 
-One note: 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.
+One note: please respect that Assert itself is intended to be the flexible, base-level, framework-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 (preferrably named 'assert-<whatever>') that uses Assert as a dependency.  When you do, tell us about it and we'll add to this readme with a short description.
+If you wish to extend Assert for your niche purpose/desire/philosophy, please do so in it's own gem (preferrably named `assert-<whatever>`) that uses Assert as a dependency.  When you do, tell us about it and we'll add to this README with a short description.

data/Rakefile

@@ -1,6 +1,3 @@
-require 'assert/rake_tasks'
-Assert::RakeTasks.install
-
 require 'bundler'
 Bundler::GemHelper.install_tasks
 

data/bin/assert

@@ -4,4 +4,4 @@
 #
 
 require 'assert/cli'
-Assert::CLI.run ARGV
+Assert::CLI.run *ARGV

data/lib/assert.rb

@@ -1,5 +1,76 @@
-require 'assert/setup/all'
-require 'assert/autorun'
+require 'singleton'
 
-Assert::Helpers.load(caller)
-Assert.autorun
+module Assert; end
+
+require 'assert/view'
+require 'assert/suite'
+require 'assert/runner'
+require 'assert/context'
+
+module Assert
+
+  def self.view;   Config.view;   end
+  def self.suite;  Config.suite;  end
+  def self.runner; Config.runner; end
+
+  def self.config; Config; end
+  def self.configure; yield Config if block_given?; end
+
+  def self.init(test_files, opts)
+    # load any test helper file
+    if p = opts[:test_dir_path]
+      helper_file = File.join(p, Config.test_helper)
+      require helper_file if File.exists?(helper_file)
+    end
+
+    # load the test files
+    Assert.view.fire(:before_load, test_files)
+    test_files.each{ |p| require p }
+    Assert.view.fire(:after_load)
+  end
+
+  class Config
+    include Singleton
+    # map any class methods to the singleton
+    def self.method_missing(m, *a, &b); self.instance.send(m, *a, &b); end
+    def self.respond_to?(m); super || self.instance.respond_to?(m); end
+
+    def self.settings(*items)
+      items.each do |item|
+        define_method(item) do |*args|
+          if !(value = args.size > 1 ? args : args.first).nil?
+            instance_variable_set("@#{item}", value)
+          end
+          instance_variable_get("@#{item}")
+        end
+      end
+    end
+
+    settings :view, :suite, :runner, :test_dir, :test_helper
+    settings :runner_seed, :show_output, :halt_on_fail, :debug
+
+    def initialize
+      @view   = Assert::View::DefaultView.new($stdout)
+      @suite  = Assert::Suite.new
+      @runner = Assert::Runner.new
+      @test_dir    = "test"
+      @test_helper = "helper.rb"
+
+      # TODO: secure random??
+      @runner_seed  = begin; srand; srand % 0xFFFF; end.to_i
+      @show_output  = true
+      @halt_on_fail = true
+      @debug        = false
+    end
+
+    def apply(settings)
+      settings.keys.each do |name|
+        if !settings[name].nil? && self.respond_to?(name.to_s)
+          self.send(name.to_s, settings[name])
+        end
+      end
+    end
+
+  end
+
+end