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

r_j_h_box-sf at yahoo.com r_j_h_box-sf at yahoo.com
Sat Jan 31 13:02:57 EST 2009

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?


From: David Chelimsky <dchelimsky at gmail.com>

> 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

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"

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?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20090131/2df9bf0a/attachment.html>

More information about the rspec-users mailing list