[rspec-users] simple == with prettier error messages + good documentation

David Chelimsky dchelimsky at gmail.com
Mon Feb 2 03:27:11 EST 2009


On Sat, Jan 31, 2009 at 12:02 PM,  <r_j_h_box-sf at yahoo.com> wrote:
> Passing the it() and describe() args through to the reporting layer sounds
> like a great idea.  I've thought more about the reporting-levels approach.
> The numeric as I postulated earlier is probably not the most useful thing.
>
> As a product manager, I want to be able to flexibly present the appropriate
> documentation to different audiences, to avoid the need for maintaining
> multiple docs.
>
> describe "an example group", :audience => :execs
> describe "an example group", :audience => :owner
> describe "an example group", :audience => :users
> describe "an example group", :audience => :developers
>
> These could be entirely ad-hoc, allowing the developer to select the desired
> labels for the situation at hand.
>
> When generating reports, you'd state which audiences to generate docs for
> (maybe with a default set coded into a helper?).
>
> When generating reports to text, any examples or groups that were skipped
> would be simply tabulated, and the summary would be displayed at the bottom:
>
>   Skipped 7 example groups and 27 examples for Users.
>   Skipped 3 example groups and 12 examples for Developers.
>
> And when generating reports to HTML, any docs for not-specified roles could
> simply be folded/hidden by default, allowing the viewer to drill down.  Of
> course, this could be skipped by setting an option for static HTML purposes,
> and the skipped items could be reported in the same way as the text version.
>
> Does this seem like a useful way to treat the various detail levels of
> documentation we want to present to different audiences?

Hey Randy,

I just committed code that makes the options available to the
formatters for both example groups and individual examples. If you
grab the latest from git, take a look at
examples/passing/filtered_formatter_example.rb and you'll see how it
works.

This should let you experiment with different ways of filtering
things. The approach you suggest does seem sound, but I'm not prepared
to add any first class support for anything like that to rspec proper
until its been proven effective.

I'm also interested in figuring out how to apply this to the actual
run, not just the reporting. i.e. use options as a tagging system to
determine which groups and/or individual examples to run. This would
require some entry point earlier in the process, and I'm not quite
sure the best approach yet. Ideas are welcome.

Cheers,
David

>
> Randy
>
>
> ________________________________
> From: David Chelimsky <dchelimsky at gmail.com>
>
> Randy:
>> http://gist.github.com/54764
>>
>> Then when generating spec docs, you could vary the detail level on what's
>> generated, to generate only up to level-2 documentation, or to generate
>> full-detail documentation if you prefer.
>>
>> Nested it()s could do the same thing, I suppose.  Not sure what side
>> effects
>> would come into play.  Pretty clearly, a nested it() wouldn't have an
>> embedded transaction or respect the outer before() block, since the outer
>> if() would handle both those things.
>
> For a number of technical reasons, the nested code example (it()) is a
> non-starter.
>
> The idea of having some means of flagging examples so they report
> differently is possible. Right now, example groups and examples each
> take a hash in their declarations:
>
> describe "an example group", :with => "some, :args => "like this" do
>   it "an example", :with => "some", :other => "args"
>   ...
>   end
> end
>
> Those are accessible to the runner, and are used internally for
> assorted filtering. As of this moment, they don't make it past the
> reporters, because the object that goes to formatters is a wrapper w/
> limited information instead of the real example. We could add the
> options to that wrapper though, and then you'd be able to write a
> custom formatter that would do anything you like based on the
> configuration of those options.
>
> WDYT about that?
>
>
>
>
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>


More information about the rspec-users mailing list