Assert::View is a collection of view classes for displaying test results using the Assert testing framework (github.com/teaminsight/assert). It allows any number of views to be created and used when running tests with Assert.
Installation and Usage
Assert::View is a dependency of Assert and will be automatically installed when you install Assert:
$ gem install assert # will install assert-view as a dependency
Usage: the default view
Assert uses the Assert::View::DefaultView outputting to $stdout by default (github.com/teaminsight/assert/blob/master/lib/assert/setup/view.rb). To override and use a different view, add the following to your ~/.assert/options.rb file:
require 'assert/view/different_view' # Override the Assert view option and assign it an instance of the different view # Setup the view passing it the IO to output on ..view ::::DifferentView.new($stdout)
Usage: define your own and override
So, ~/.assert/option.rb is just a ruby script that is required when Assert is setting itself up. You can use this file to define your own custom view class and then override the Assert view option like above:
# Say you wanted to tweak and make a better DefaultView require 'assert/view/default_view' module :: class MyBetterDefaultView < DefaultView # override stuff and tweak it to your heart's content end end # Now override the view option to use your better terminal ..view ::::MyBetterDefaultView.new($stdout)
You could also define an entirely new view from scratch. Look at the existing views and read the below about writing your own view for more details. Once you have written your new view, tell Assert to use it with the following:
All views need to subclass the Assert::View::Base class. This class implements a few core things that assert expects of its view classes:
All view initializers take two things at minimum:
output_io: an IO stream to output to ($stdout, etc…)
suite: (optional) an instance of the core suite class; the suite of tests to run/render (defaults to Assert.suite - you probably shouldn't change this default unless you know what you are doing)
The suite reader provides access to the suite of tests that will be or has been run. Use this reader to do things like count tests or test results, iterate through the tests and display detailed results, etc. This reader provides all the model data needed to render your view.
The view renderer provided by the base class uses Undies (github.com/kelredd/undies) to define and render view templates. It mixes in a 'render' method to the base view that handles creating an Undies::Template from the view's template definition and wiring up the necessary runner callbacks.
The base class provides a few utilities for rendering views:
run_time: get a string with the suite's run time in seconds
run_seed: get the seed value used to run the test suite in random order
count: helper method for counting stuff on the suite, ie: 'count(:tests)'
etc… Check out the base class for all utilities (github.com/teaminsight/assert-view/blob/master/lib/assert/view/base.rb)
Anatomy of a View
So I'd like to explain some key things about Assert views in detail to understand the anatomy of a view and hopefully help you understand how to create your own.
First off, all views need to subclass Assert::View::Base. The base class provides a bunch of utilities and handles all the necessary callbacks between a view and Assert's Runner class. In addition, the base class provides all methods necessary to render the view's template. Beyond that, a View has 3 main parts:
1 - Options
The base class mixes in Assert's options helpers so that options can be specified on any view. The base class provides a few key options:
default_passed_abbrev: [“.”] the default abbreviation for passed results
default_failed_abbrev: [“F”] ditto for failed results
default_errored_abbrev: [“E”] ditto for errored results
default_skipped_abbrev: [“S”] ditto for skipped results
default_ignored_abbrev: [“I”] ditto for ignored results
In addition, the DefaultView specifies a few options of its own:
styled: [true] whether or not to show ansi-styled results, set to false for plain text output
passed_styles [:green] the styles to markup passing result output with
failed_styles [:red, :bold] ditto for failed result output
errored_styles [:yellow, :bold] ditto for errored result output
skipped_styles [:cyan] ditto for skipped result output
ignored_styles [:magenta] ditto for ignored result output
Use options in your views to override the base default options or to define your own for tweaking behavior and customization.
2 - Template / Template Helpers
The base class provides a 'template' class method. Use this method to define an Undies template to render your view. Check out Undies for details on how to create an Undies template. Templates are given two locals to work with:
view: this local refers to the instance of the view class. Use it to get data or run logic.
runner: this is a block used to callback to Assert's runner and run the tests. Pass this local to the base 'run_tests' method to control when (in rendering your view) the tests are run. Optionally pass a block to 'run_tests' that will be called each time a new result is generated by the running tests. Use this to render live runtime result data.
If you need to define some helper methods for your view to use, add them to a helpers module (check out: github.com/teaminsight/assert-view/blob/master/lib/assert/view/helpers/ansi.rb). Use the 'helper' class method on your view to mix those helpers in to the view's template scope and then you can use them in your template.
3 - Data/Logic
Assert views encourage defining your view's data handling and business logic seperately from your view's template. Define instance methods on your view to access, process, and handle data and business logic. Your template can then access them using its 'view' local.
TODO: put in notes about other views available for use…
Roll Your Own!
Check out the different views available here. Use a few and customize them using their options. If you find you can't see your test results how you like or you prefer the way an alternate testing library outputs test results, create your own view class. Write it inline in your '.assert/options.rb' file and hook it up with Assert's view option. If you want to share it with everyone, fork this gem, add it in, and submit a pull request.
TODO: put in guidlines for submitting new views…
Copyright © 2011 Kelly Redding and Team Insight
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.