HTML Story Formatter

johanatan · July 24, 2008, 2:37pm

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

johanatan · July 24, 2008, 2:46pm

On Thu, Jul 24, 2008 at 7:32 AM, Jonathan L.
[email protected] 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

johanatan · July 24, 2008, 6:32pm

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 C. [email protected]
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 B.
Cobalt Edge LLC
http://cobaltedge.com

johanatan · July 24, 2008, 6:57pm

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 B. wrote:

  system("/bin/cp -r
task :stories => [ :copy_story_html_includes ] do

On Thu, Jul 24, 2008 at 7:32 AM, Jonathan L.
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 L.
http://jonathanleighton.com/

johanatan · July 25, 2008, 3:19pm

On Fri, Jul 25, 2008 at 8:08 AM, Joseph W. [email protected]
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?

johanatan · July 25, 2008, 3:08pm

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 W.,
http://www.joesniff.co.uk

David C. wrote:

On Thu, Jul 24, 2008 at 7:32 AM, Jonathan L.
[email protected] 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

johanatan · July 27, 2008, 12:37pm

On Sat, 2008-07-26 at 16:38 -0600, Ben M. 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 L.
http://jonathanleighton.com/

johanatan · July 27, 2008, 12:43am

David C. wrote:

On Fri, Jul 25, 2008 at 8:08 AM, Joseph W. [email protected]
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:

github.com

bmabey/rspec-story-tmbundle/blob/master/Support/resource/rspec.js

Event.addBehavior({
	
	'dt.failure' : function() {
	  this.ancestors().each(function(e){
	    if (e.hasClassName('passed'))
	    {
	      e.addClassName('failed')
    		e.removeClassName('passed')
    	}	    
	  })
	},
  'li.pending' : function(){
	  this.ancestors().each(function(e){
	    if (e.hasClassName('passed'))
	    {
	      e.addClassName('pending')
    		e.removeClassName('passed')
    	}	    
	  })
	},

This file has been truncated. show original

(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

johanatan · July 28, 2008, 6:42pm

Joseph W. 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

johanatan · July 28, 2008, 11:54am

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 W.
http://www.joesniff.co.uk

Ben M. wrote:

David C. wrote:

On Fri, Jul 25, 2008 at 8:08 AM, Joseph W. [email protected]
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

johanatan · July 29, 2008, 9:28pm

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 M. wrote:

Joseph W. 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

johanatan · August 8, 2008, 5:09pm

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 W.,
http://www.joesniff.co.uk

David C. wrote:

On Tue, Jul 29, 2008 at 2:28 PM, Joseph W. [email protected]
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?

johanatan · August 6, 2008, 5:27am

On Tue, Jul 29, 2008 at 2:28 PM, Joseph W. [email protected]
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?