Ruby Forum RSpec > HTML Story Formatter

Hiya,

I am trying to use the HTML Story Formatter in conjunction with
CruiseControl.rb. I have got it outputting the stories to a file, but I
notice there are CSS and JS files linked in the head, which don't appear
to be anywhere in the rspec repository. Are these files available and if
so where?

Cheers,
Jon

On Thu, Jul 24, 2008 at 7:32 AM, Jonathan Leighton
<j@jonathanleighton.com> wrote:
> Hiya,
>
> I am trying to use the HTML Story Formatter in conjunction with
> CruiseControl.rb. I have got it outputting the stories to a file, but I
> notice there are CSS and JS files linked in the head, which don't appear
> to be anywhere in the rspec repository. Are these files available and if
> so where?

They're in the story_server directory. We haven't automated this yet,
so what I do is just copy them to a logical place and set up a rake
task to put the stories in the same place. On Rails projects, I've
gotten into the habit of putting them in
public/doc/[javascripts|stylesheets] (or similar) and then use this
rake task.

namespace :stories do

  desc "Run all the stories (HTML)"
  task :html do
    sh "ruby stories/all.rb -fh:public/doc/index.html"
  end

end

Now the customers can see the story output at /docs. Of course, so can
anybody else, so that might come down before releasing or move to a
controller that can manage who gets to see it. But this should give
you an idea.

Also note that the javascript is 1/2 baked at this point and includes
an "add step" (non) feature (which you'll see in the browser) that
doesn't really do anything.

Maybe it's time to get rid of that for now and standardize on where
this stuff goes :)

HTH,
David

For another variant, with my CC.rb setup, I have a rake task as follows:

  desc "Copy RSpec Story HTML includes"
  task :copy_story_html_includes do
    if ENV['CC_BUILD_ARTIFACTS']
      stories_output_dir = File.join(ENV['CC_BUILD_ARTIFACTS'], 
'Stories')
      system "mkdir #{stories_output_dir}"
      system("/bin/cp -r
#{RAILS_ROOT}/vendor/plugins/rspec/story_server/prototype/stylesheets/
#{stories_output_dir}")
      system("/bin/cp -r
#{RAILS_ROOT}/vendor/plugins/rspec/story_server/prototype/javascripts/
#{stories_output_dir}")
    end
  end

And then I just have that as a pre-requisite to my regular
spec:stories rake task (since it'll only do something if we're in the
CC.rb environment):

  desc "Run all spec stories"
  task :stories => [ :copy_story_html_includes ] do
    if ENV['CC_BUILD_ARTIFACTS']
      ruby "stories/all.rb --format html >
#{File.join(ENV['CC_BUILD_ARTIFACTS'], 'Stories', 'index.html')}"
    else
      ruby "stories/all.rb --format plain --colour"
    end
  end


On Thu, Jul 24, 2008 at 5:44 AM, David Chelimsky <dchelimsky@gmail.com> 
wrote:
> They're in the story_server directory. We haven't automated this yet,
>    sh "ruby stories/all.rb -fh:public/doc/index.html"
> an "add step" (non) feature (which you'll see in the browser) that
>> Cheers,
> http://rubyforge.org/mailman/listinfo/rspec-users
>



--
Christopher Bailey
Cobalt Edge LLC
http://cobaltedge.com

Thanks for both your answers. The copying rake task was pretty useful as
I was basically intending to write the same thing after I read David's
message :)

Jon

On Thu, 2008-07-24 at 09:29 -0700, Christopher Bailey wrote:
>       system("/bin/cp -r
>   task :stories => [ :copy_story_html_includes ] do
> > On Thu, Jul 24, 2008 at 7:32 AM, Jonathan Leighton
> > so what I do is just copy them to a logical place and set up a rake
> >  end
> > doesn't really do anything.
> >> Jon
> >
> 
> 
> 
--
Jonathan Leighton
http://jonathanleighton.com/

To handle this I wrote a patch which delivered the styles in the html 
formatters output. In much the same way as the html spec formatter does.

I know Aslak Hellesøy has been looking at the editable html stories.

Is it acceptable to have stories have styles embedded in the html 
formatter until Aslak's editable stories project evolves?

I could imagine there are some arguments that the HTML output of stories 
is something people might want to control the look and feel of, more so 
than specs as they are seen more frequently by customers.

Perhapes by default the styles are embedded in the html formatter but if 
a CSS stylesheet is passed to the formatter than it will suppress this 
output and use your custom css.

something like:
ruby stories/all.rb --format html --css my_own.css

--
Joseph Wilk,
http://www.joesniff.co.uk



David Chelimsky wrote:
> On Thu, Jul 24, 2008 at 7:32 AM, Jonathan Leighton
> <j@jonathanleighton.com> wrote:
>> Hiya,
>>
>> I am trying to use the HTML Story Formatter in conjunction with
>> CruiseControl.rb. I have got it outputting the stories to a file, but I
>> notice there are CSS and JS files linked in the head, which don't appear
>> to be anywhere in the rspec repository. Are these files available and if
>> so where?
> 
> They're in the story_server directory. We haven't automated this yet,
> so what I do is just copy them to a logical place and set up a rake
> task to put the stories in the same place. On Rails projects, I've
> gotten into the habit of putting them in
> public/doc/[javascripts|stylesheets] (or similar) and then use this
> rake task.
> 
> namespace :stories do
> 
>   desc "Run all the stories (HTML)"
>   task :html do
>     sh "ruby stories/all.rb -fh:public/doc/index.html"
>   end
> 
> end
> 
> Now the customers can see the story output at /docs. Of course, so can
> anybody else, so that might come down before releasing or move to a
> controller that can manage who gets to see it. But this should give
> you an idea.
> 
> Also note that the javascript is 1/2 baked at this point and includes
> an "add step" (non) feature (which you'll see in the browser) that
> doesn't really do anything.
> 
> Maybe it's time to get rid of that for now and standardize on where
> this stuff goes :)
> 
> HTH,
> David

On Fri, Jul 25, 2008 at 8:08 AM, Joseph Wilk <lists@ruby-forum.com> 
wrote:
> than specs as they are seen more frequently by customers.
>
> Perhapes by default the styles are embedded in the html formatter but if
> a CSS stylesheet is passed to the formatter than it will suppress this
> output and use your custom css.
>
> something like:
> ruby stories/all.rb --format html --css my_own.css

That all sounds reasonable to me. Sensible defaults, yet configurable.

Other opinions?

David Chelimsky wrote:
> On Fri, Jul 25, 2008 at 8:08 AM, Joseph Wilk <lists@ruby-forum.com>
wrote:
>
>> To handle this I wrote a patch which delivered the styles in the html
formatters output. In much the same way as the html spec formatter
does.
>> I know Aslak Hellesøy has been looking at the editable html stories. Is
it acceptable to have stories have styles embedded in the html
formatter until Aslak's editable stories project evolves?
>> I could imagine there are some arguments that the HTML output of
stories
>> is something people might want to control the look and feel of, more so
than specs as they are seen more frequently by customers.
>> Perhapes by default the styles are embedded in the html formatter but
if
>> a CSS stylesheet is passed to the formatter than it will suppress this
output and use your custom css.
>> something like:
>> ruby stories/all.rb --format html --css my_own.css
>>
> That all sounds reasonable to me. Sensible defaults, yet configurable.
Other opinions?
>

I like that idea.  I haven't wanted to push back any of my changes to 
the
HTML formatter because I knew that Aslak's goal was to create a 
customer
facing editable HTML page.

However, for CI builds it is more useful as a programmer to not have 
that
functionality and inline the backtrace as well (which is something  most
customer's wouldn't want to see.)  I vote for inlining the basic  styles
and providing the way to configure it as suggested above.  I  think the
HTML formatter should include the backtrace and then JS can be  used to
hide it for a customer-facing version.

Which brings up the other question.. how do we want to handle the JS?
Due to how the HTML is written out JS is required to change the Story's
and Scenario's styles when a step fails or is pending.  I did this with
lowpro for the rspec-story-tmbundle:
http://github.com/bmabey/rspec-story-tmbundle/tree/master/Support/resource/rspec.js
(The JS commented out in the file was the original JS that Aslak did for
the editable version.)
My JS is untested though (and only works for rspec 1.1.4), so I don't
know if you want to incorporate it into rspec, plus it would require the
additional lowpro.js lib.

The bigger question, I think, is how to handle the required JS files.  I
don't think inlining the whole prototype lib is a good solution.  So,
maybe we could default to generating full paths to the JS files which
reside in the rspec lib folder?  Then we could allow options to be 
passed
in to modify the JS path, just like the CSS option above?

Any other suggestions/ideas of how to handle the external JS files?

-Ben

On Sat, 2008-07-26 at 16:38 -0600, Ben Mabey wrote:
> Any other suggestions/ideas of how to handle the external JS files?

Wasn't there some Google-hosted JS lib repository launched a little
while ago? That could be used for Prototype?

Jon

--
Jonathan Leighton
http://jonathanleighton.com/

> Which brings up the other question.. how do we want to handle the JS?
> Due to how the HTML is written out JS is required to change the Story's
> and Scenario's styles when a step fails or is pending.  I did this with
> lowpro for the rspec-story-tmbundle:

The current html formatter in trunk no longer requires js to apply 
styles for failure or pending.

So that moves us along to looking at js to hide/show the backtrace.

The idea of showing the backtrace in the html has been something I've 
been debating for a while. I did come to conclusion that as a developer 
I have the build log (or terminal stories are run from) as a source for 
story errors. Hence I felt I was best left leaving my stories clean for 
the non-developer users of the stories.

I can see from your post that there is a usecase for a more developer 
centric  output.

My goal with the default story output was to get a standalone .html file 
which can then be moved around and played with without having to worry 
about managing css & js files. Pretty much just as the spec reporter 
does.

Thinking about a developer centric report and maintaining a standalone 
html report starts to make me think about different formatters/reports.

* Default standalone
* Custom css
--
* Developer centric story report - js & customizable css

So this move us to something like:

*ruby stories/all.rb --format html
*ruby stories/all.rb --format html --css my_own.css

AND

*ruby stories/all.rb --format developer-html

I think the first two are important and represent the majority of use 
cases.

If we can separate the idea of js and backtrace output to a separate 
formatter then we can start work on the first two outputs now (and make 
story reports usable out of the box).

Then we can use a developer formatter as a sounding board for 
advanced/verbose output (profiling each story aswell perhaps?). 
Potentially Aslak's new interface could move to this dev-formatter(or 
some other formatter) so that we continue development without disturbing 
those using the simple default output.

What do people think?

--
Joseph Wilk
http://www.joesniff.co.uk

Ben Mabey wrote:
> David Chelimsky wrote:
>> On Fri, Jul 25, 2008 at 8:08 AM, Joseph Wilk <lists@ruby-forum.com>
> wrote:
>>
>>> To handle this I wrote a patch which delivered the styles in the html
> formatters output. In much the same way as the html spec formatter
> does.
>>> I know Aslak Helles�y has been looking at the editable html stories. Is
> it acceptable to have stories have styles embedded in the html
> formatter until Aslak's editable stories project evolves?
>>> I could imagine there are some arguments that the HTML output of
> stories
>>> is something people might want to control the look and feel of, more so
> than specs as they are seen more frequently by customers.
>>> Perhapes by default the styles are embedded in the html formatter but
> if
>>> a CSS stylesheet is passed to the formatter than it will suppress this
> output and use your custom css.
>>> something like:
>>> ruby stories/all.rb --format html --css my_own.css
>>>
>> That all sounds reasonable to me. Sensible defaults, yet configurable.
> Other opinions?
>>
> 
> I like that idea.  I haven't wanted to push back any of my changes to 
> the
> HTML formatter because I knew that Aslak's goal was to create a 
> customer
> facing editable HTML page.
> 
> However, for CI builds it is more useful as a programmer to not have 
> that
> functionality and inline the backtrace as well (which is something  most
> customer's wouldn't want to see.)  I vote for inlining the basic  styles
> and providing the way to configure it as suggested above.  I  think the
> HTML formatter should include the backtrace and then JS can be  used to
> hide it for a customer-facing version.
> 
> Which brings up the other question.. how do we want to handle the JS?
> Due to how the HTML is written out JS is required to change the Story's
> and Scenario's styles when a step fails or is pending.  I did this with
> lowpro for the rspec-story-tmbundle:
> http://github.com/bmabey/rspec-story-tmbundle/tree/master/Support/resource/rspec.js
> (The JS commented out in the file was the original JS that Aslak did for
> the editable version.)
> My JS is untested though (and only works for rspec 1.1.4), so I don't
> know if you want to incorporate it into rspec, plus it would require the
> additional lowpro.js lib.
> 
> The bigger question, I think, is how to handle the required JS files.  I
> don't think inlining the whole prototype lib is a good solution.  So,
> maybe we could default to generating full paths to the JS files which
> reside in the rspec lib folder?  Then we could allow options to be 
> passed
> in to modify the JS path, just like the CSS option above?
> 
> Any other suggestions/ideas of how to handle the external JS files?
> 
> -Ben

Joseph Wilk wrote:
>> Which brings up the other question.. how do we want to handle the JS?
>> Due to how the HTML is written out JS is required to change the Story's
>> and Scenario's styles when a step fails or is pending.  I did this with
>> lowpro for the rspec-story-tmbundle:
>>     
>
> The current html formatter in trunk no longer requires js to apply 
> styles for failure or pending.
>   

Ahh, good to know.  Does that mean that the HTML isn't outputted until
all of the scenario's are ran for a particular story?
> So that moves us along to looking at js to hide/show the backtrace.
>
> The idea of showing the backtrace in the html has been something I've 
> been debating for a while. I did come to conclusion that as a developer 
> I have the build log (or terminal stories are run from) as a source for 
> story errors. Hence I felt I was best left leaving my stories clean for 
> the non-developer users of the stories.
>   

This is true for regular development, although having the backtrace can
also be helpful in the HTML version if you use that as your main
formatter (i.e. in textmate.)
The real use for the backtrace, IMO, is for providing a decent build
artifact for CI.  Otherwise you could have to look through your test.log
file and try to match it up.. which would be no fun.
>
> AND
> advanced/verbose output (profiling each story aswell perhaps?). 
> Potentially Aslak's new interface could move to this dev-formatter(or 
> some other formatter) so that we continue development without disturbing 
> those using the simple default output.
>
> What do people think?
>   

I really like that idea, and I agree with you that these two would cover
most use cases.

-Ben

> Ahh, good to know.  Does that mean that the HTML isn't outputted until
> all of the scenario's are ran for a particular story?

Exactly. It made the html much nicer but did loose that per scenario 
output. I added a progress bar formatter so I could still get that 
direct scenario feedback, be it just a green dot or red F :)

David are you happy with this html and dev-html formatter direction? If 
so I'll move this issue to lighthouse and start adding my patch.



Ben Mabey wrote:
> Joseph Wilk wrote:
>>> Which brings up the other question.. how do we want to handle the JS?
>>> Due to how the HTML is written out JS is required to change the Story's
>>> and Scenario's styles when a step fails or is pending.  I did this with
>>> lowpro for the rspec-story-tmbundle:
>>>     
>>
>> The current html formatter in trunk no longer requires js to apply 
>> styles for failure or pending.
>>   
> 
> Ahh, good to know.  Does that mean that the HTML isn't outputted until
> all of the scenario's are ran for a particular story?
>> So that moves us along to looking at js to hide/show the backtrace.
>>
>> The idea of showing the backtrace in the html has been something I've 
>> been debating for a while. I did come to conclusion that as a developer 
>> I have the build log (or terminal stories are run from) as a source for 
>> story errors. Hence I felt I was best left leaving my stories clean for 
>> the non-developer users of the stories.
>>   
> 
> This is true for regular development, although having the backtrace can
> also be helpful in the HTML version if you use that as your main
> formatter (i.e. in textmate.)
> The real use for the backtrace, IMO, is for providing a decent build
> artifact for CI.  Otherwise you could have to look through your test.log
> file and try to match it up.. which would be no fun.
>>
>> AND
>> advanced/verbose output (profiling each story aswell perhaps?). 
>> Potentially Aslak's new interface could move to this dev-formatter(or 
>> some other formatter) so that we continue development without disturbing 
>> those using the simple default output.
>>
>> What do people think?
>>   
> 
> I really like that idea, and I agree with you that these two would cover
> most use cases.
> 
> -Ben

On Tue, Jul 29, 2008 at 2:28 PM, Joseph Wilk <lists@ruby-forum.com> 
wrote:
>> Ahh, good to know.  Does that mean that the HTML isn't outputted until
>> all of the scenario's are ran for a particular story?
>
> Exactly. It made the html much nicer but did loose that per scenario
> output. I added a progress bar formatter so I could still get that
> direct scenario feedback, be it just a green dot or red F :)
>
> David are you happy with this html and dev-html formatter direction? If
> so I'll move this issue to lighthouse and start adding my patch.

Sorry for the long silence on this - just got back from my first
"computer-free" vacation in some years. I recommend it to everyone
(though some may wish to prepare themselves for assorted withdrawal
symptoms).

Anyhow - I'm not convinced one way or the other as to whether two
formatters for different audiences is better than a single html
formatter w/ some simple js to reveal backtraces. I can tell you from
my experience with FitNesse that the backtraces were sometimes
life-saving and sometimes simply annoying. Having the option to show
it but have it hidden on load would be nice.

Anybody else wanna chime in on this?

Hello,

Hope you had a nice break David.

I've been thinking about hidden backtraces in the html stories some more 
and I think having them carries little to no impact for the non-tech 
consumers of the stories.

I think its similar to how we use Nagios. The business like to look at 
the nice red and green lights. When things go wrong they don't care why, 
they care if its red. The QA people of the other hand can use the same 
interface to see what went wrong.

It feels a similar situation to that of the html stories.

The key thing for me is that we still try and make the html story 
reports standalone. Fortunately a simple show hide is not going to 
require any external js libs.

I'm happy to add some JS to my current patch to show/hide the backtrace 
when there is an error.

As for a separate Formatter for developers, with the JS/backtrace dealt 
with perhaps until something dramatic comes about that swings the 
discussion we procrastinate?

--
Joseph Wilk,
http://www.joesniff.co.uk

David Chelimsky wrote:
> On Tue, Jul 29, 2008 at 2:28 PM, Joseph Wilk <lists@ruby-forum.com> 
> wrote:
>>> Ahh, good to know.  Does that mean that the HTML isn't outputted until
>>> all of the scenario's are ran for a particular story?
>>
>> Exactly. It made the html much nicer but did loose that per scenario
>> output. I added a progress bar formatter so I could still get that
>> direct scenario feedback, be it just a green dot or red F :)
>>
>> David are you happy with this html and dev-html formatter direction? If
>> so I'll move this issue to lighthouse and start adding my patch.
> 
> Sorry for the long silence on this - just got back from my first
> "computer-free" vacation in some years. I recommend it to everyone
> (though some may wish to prepare themselves for assorted withdrawal
> symptoms).
> 
> Anyhow - I'm not convinced one way or the other as to whether two
> formatters for different audiences is better than a single html
> formatter w/ some simple js to reveal backtraces. I can tell you from
> my experience with FitNesse that the backtraces were sometimes
> life-saving and sometimes simply annoying. Having the option to show
> it but have it hidden on load would be nice.
> 
> Anybody else wanna chime in on this?