Assert::View

Description

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
Assert.options.view Assert::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 Assert::View
  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
Assert.options.view Assert::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:

Assert.options.view Assert::View::MyNewView.new($stdout)

Assert::View::Base class

All views need to subclass the Assert::View::Base class. This class implements a few core things that assert expects of its view classes:

Initializer

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)

‘suite’ reader

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 Renderer

The view renderer provided by the base class defines and renders view templates. It mixes in a ‘render’ method to the base view that handles creating a Template object from the view’s template definition and wiring up the necessary runner callbacks.

Utilities

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 template source to render your view. 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.

Other Views

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…

License

Copyright © 2011-Present 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.