Errata for The RSpec Book

#40301: "Iteration" not explained

The term “iteration” is used very early on (first reference is p31 in b8_0) but not explained. There’s even an entire section titled “Planning the First Iteration” slightly later on but there’s still no explanation what this means in that section. Much later (p145) there’s a very brief reference to an iteration being an one or two week “mini-project” but no detailed explanation.

I think it would help to explain up front, at least briefly, what an iteration (and other Agile terms used in the book) is for those not familiar with Agile development methodologies rather than waiting till later like in Chap 10.
--Michael Wang

#41504: I would like more information on the higher-level project descriptions i.e. outcomes and feature sets, and how they fit in. Specifically, I want to know how they would fit in with the codebreaker example - what are the feature sets for it? Would there be outcomes?--Sean P. DeNigris

#42115: In the "Focus on the Role" section, the "Coh04" link Is being displayed in bright green. This is incredibly hard to read on the gray background.

I'm viewing the PDF using Preview.app on a 13" Macbook Pro running Snow Leopard (10.6.2). I don't think I have done any customization that would cause the color to be different on my system, but don't remember for sure.

The same bright green link also appears in the body text on Page 35 ("JAH02") and, while it's easier to read on a white background, it is still somewhat painful.

I do see that this is the same in other PragPub books (e.g. Agile Web Development with Rails) so maybe it is something particular to my machine. At any rate, I thought I'd point it out in case it is something that could be configured in your PDF files.--Paul Nelson

#42248: From the Scenario Outline on this page you can infer that the mark will always print the +'s before the -'s. But this fact is never explicitly stated anywhere. And in fact, I completely missed it on my first run through. It wasn't until the later chapter where you deal with duplicates that I realized the rule was already implied.

Is there some way that the Cucumber could updated to make this rule explicit in order to avoid confusion and increase communication? It could be added to the feature description, but it seems like it would be even better if it actually became an explicitly stated rule of its own. Is this possible?

Thanks!--Kevin Berridge

#42197: Scenarios: no matches
| code | guess | mark |
| 1234 | 5678 | |

Isn’t 78 in contradiction with 3.1 page 34 second paragraph : the code-breaker makes a guess of four numbers (again, 1 to 6) ?
--Bernard Kaiflin

#42198: Suggest to put the figure 4-1 back.

Reason : as I tried running cb/04 (old code) on page 55, I was stuck with require errors and wanted to check if my directory structure is correct, but couldn’t find the figure, which has been removed from B13.
I had appreciated the figure 4-1 and the following explanations on pages B12 51-52, especially the parallelism between lib and spec (related to the updating of $LOAD_PATH in env.rb, something not familiar for a newbie). I have adopted this scheme for my RSpec development now, lib + spec with a require_helper.rb similar to env.rb.
--Bernard Kaiflin

#42283: On page 54 of B13, the last line of the output of the example cucumber run from the page before is listed directly below the sidebar. Because it's a single line, it would probably be a good thing to find a way to put it with the rest of the output. "0m0.003s" looks pretty odd after the sidebar, especially considering the page content doesn't describe that line at all.--Jon Mischo

#42179: At some point in section 7.1 we need to update the start method by adding @secret = secret. I don't think you tell us that. I figured it out by debugging an error but I thought I'd let you know.

def start(secret)
@secret = secret
@output.puts 'Welcome to Codebreaker!'
@output.puts 'Enter guess:'
end

Love the book!--KRISTEN HAZARD

#42250: You begin Chapter 8 with nearly the same Fowler quote that you began section 5.4 with, though they are different in their wording:

5.4
In the preface to his seminal book on Refactoring [FBB99], Martin Fowler writes: “Refactoring is the process of changing a software system in such a way that it does not alter the external behaviour of the code yet improves its internal structure.”

Chapter 8
In his book, Refactoring [FBB+99], Martin Fowler describes refactoring as “a change made to the internal structure of software to make it easier to understand and cheaper to modify without changing its observable behavior.”

Reading the quote in chapter 8, it feels as if the authors have unintentionally repeated themselves, even though the second quote adds some new ideas. Maybe it should be introduced in a way that acknowledges that Fowler has already been mentioned, then says that Fowler further defines refactoring as such and such (using the quote).--Steve

#42162: I like the fact that you removed duplicate test cases from game_spec.rb. However, the single guess test case is a little simplistic. Why not test for something that covers all cases? Like:

describe "#guess" do
it "sends the mark to output" do
game.start('1234' )
output.should_receive(:puts).with('++-' )
game.guess('1354' )
end
end

The advantage here would be a chance to catch a problem introduced in the marker_spec.rb test cases: maybe someone edits the marker_spec test cases so they aren't providing the coverage needed. You'd at least have a chance of catching something at the game_spec level. <shrug>--Paul Nelson

#39655: omit (juvenile) "(It’s nice to do this from time to time anyway—it helps
their self-esteem.)" --we already *know* we have a heightened sense for cheap irony
--Jesse Crockett

#39658: "Whether this is due to real understanding and value of Agile principles, or simply a marketing ruse, only time will tell." over "Whether this is due to them understanding and valuing the underlying principles of Agile or simply a marketing ruse to dress up the same old tired processes is left as an exercise for the reader."
--Jesse Crockett

#42174: Maybe I missed the explanation somewhere in the book, but you mention that the "it" method accepts a string and an optional Hash along with the optional block. What is the Hash's purpose? Shouldn't there be an example of how to use the optional Hash parameter?

I checked the ri documentation for RSpec, but that didn't help a whole lot either. My next step will be to Google it, but it seems like this book has a responsibility to cover this feature.--Paul Nelson

#42168: In the RSpec examples earlier in the book, you pass a string parameter to "describe" that includes the pound/hash/number sign. Example:

describe "#start" do

Having used other BDD frameworks like JSpec and JBehave, it was not clear to me why the pound sign was prepended to the string. I'm guessing it is done to match the convention of Ruby's ri documentation tool, but it might be nice to have this convention explained in this section of the book, where "describe" is explored in detail.--Paul Nelson

#41742: The paragraph "Outcome-based planning" ends with "and that that’s ok" which might be correct but the two "that" sound very strange and could it be dropped anyways.--Thomas R. Koll

#38400: In the description of attach_file, there is all of a sudden the mention of "Photo". I took me a while to figure out how it relates to the form field. An example form would be nice here.--Patrick Debois

#38801: Isn't a full page for a screenshot of the rails project tree a bit generous? Couldn't be represented as a diagram, and to keep it consistent with the tree shown for the Mastermind game at the beginning of the book? --Robert Gravina

#40847: The first code example in section 14.2 Method Stubs has misleading code highlighting.

On line 6 of the code example:
statement.generate.should =~ /^Statement for Aslak/

The word "for" is highlighted as a ruby keyword, and led me to some head scratching.
--Timothy Elliott

#41788: This section indicates that a clarification will be made about the differences of using stub, mock and double to make a spec more clear, but I don't think it is really addressed in the chapter. After finishing the chapter, I am still unsure of when to really use mock vs. double. The chapter alludes that mock presents a tighter connection to the subject of the spec than stub, but the double instance doesn't seem to be addressed.--Marli Baumann

#42199: Last paragraph : By default, the spec command only loads files ending with _spec.rb. As you’ll see later in this chapter, … you can configure RSpec …

I haven’t found an explicit explanation in the rest of the chapter. Suggestion if it is not elsewhere :

By default, the spec command only loads files ending with _spec.rb. While this pattern is the convention, you can configure RSpec to load files based on any pattern you choose. For example, if your files end with _t.rb, add the following option :

--pattern *_t.rb
--Bernard Kaiflin

#42200: Paragraph “Invoke With Options Stored in a File with –options”

Suggestion : give also the short form of --options, which is uppercase -O.

Reason : having read the book “Scripted GUI testing” before, I used to run the tests with the command :
spec file.rb -fn -c

After having read this paragraph and created the spec.opts file, I naturally gave the command :
spec ./ –o spec.opts

… and it did not work !
--Bernard Kaiflin

#39771: rspec-rails ActiveRecord::Error mocking

For outside-in view specs it would be useful to see how to mock ActiveRecord errors, for example I want to implement

it "should render an error message if errors are present"

as part of my view spec, which I am amending after finding in a feature that I had no validation error messages showing up on the page to tell the user what they did wrong.

Some general advice on mocking these complex objects (where you could just stub the action you know your view uses, error_messages_for() in this case, but that would be fragile if, for example, the view were changed to use error_message_for several times instead).--Nick Rutherford

#42109: For the "Bundling in vendor/gems" and "Bundling in vendor/plugins" - what I forsee happening is someone relatively new to Rails reading the book and following it blindly, but being confused when they get here. Some more context as to /why/ one would pick one, the other, or neither might be helpful. Maybe a little callout section or something just before those two sections.--Cory Foy

#42114: Regarding the "Bundling in vendor/gems" section starting on p.303; Unpacking dependencies installs Nokogiri which will cause an error when running the first scenario on p.309. Shouldn't the book instruct the reader to remove Nokogiri from vendor/gems as it contains native extensions? I think this was mentioned in passing on b12 but has not been included on b13. --Sid Wood

#40121: The BD Rails: Rails Views chapter would benefit from describing how to mock/stub/place expectations on ActionView helpers, for example when using textile you may want to
@controller.template.stub!(:textilize).and_return('textiled text')

then
@controller.template.should_receive(:textilize).with(@service.teaser)
@controller.tepmlate.should_not_receive(:textilize).with(@service.name)

It took me a few hours to find this, I think it is worth adding to the chapter as these view helpers are an external dependency and their behaviour (i.e. is the textile actually converted correctly for display) seems better suited to the Cucumber level. Speccing textilize's behaviour should be done in RedCloth's own tests, not the application tests.

The minimum I would have found helpful is being told *what* to stub, it wasn't clear whether it was @controller, the helper module, or as it turned out another object which makes MVC sense but isn't mentioned in the literature.--Nicholas Rutherford

#42100: FYI, on MS Windows XP with ruby 1.8.6 (2008-08-11 patchlevel 287) [i386-mswin32], Time.now.strftime("%l") => "". I notice that the %l isn't documented in the Pickaxe. I used:
def formatted_time
hour = showtime_time.strftime("%I").to_i.to_s
hour + showtime_time.strftime(":%M%p").strip.downcase
end--Donald Parish

#40568: I'm not sure if the Rails Controller chapter is the best place for this (or even if this is the best mechanism to suggest) but I feel that some information on using RSpec for spec'ing routes would be useful to the reader. If nothing else, it'd definitely be useful to me.--Chris Ess

#41128: text from 348 to 351 needs breaking up with some headers. Its very easy to get lost in the example. I would suggest some sub headings like

Create Message Class
Mock As New Record
Add Input Field
Mock Title Attribute
Mock Null Object
Dry up with before(:each)

Perhaps these could be notes in the margin if titles are to unobtrusive--Andrew Premdas

#40128: It seems that testing the "validates_uniqueness_of" model validation is a bit tricky. Blogs and forums I've found have a number of suggestions, but they all seem to be "workarounds" to me. This topic doesn't appear to be covered in the RSpec book (yet). I'd really like to see this topic covered.--Les Nightingill

#40234: Just another point about keeping these three chapters on Rails MVC consistent:
In the Rails controller section, the method's if clause was implemented exactly reverse:

def create
@message = Message.new params[:message]
if @message.save
flash[:notice] = "The message was saved successfully."
redirect_to messages_path
else
render :action => "new"
end
end--Florian Leitner

#41143: This change of messages_controller break loads of the tests. It's not at all obvious how to refactor the tests and controller in tandem to achieve this. Especially as I can't see how to reference the current_user. This needs to be explained.--Brendan Maginnis

#41956: It'd be great if you could add a note as to how to handle errors that are raised in Webrat/Cucumber. On 395, the example of implementing an "access denied" feature in your ApplicationController is a good one, but it left me lost when I did the next logical step, which was to try and build it out using Cucumber.

Here's what I tried, in the wild, with the application controller/spec implemented as suggested:

Scenario: Users cannot sign up when sign ups are disabled
Given sign ups are disabled
When I go to the sign up page
Then I should see "forbidden"

The second step (using the built-in when I go to...) causes an AccessDenied error to be thrown (as you'd expect). However, when Webrat encounters the exception, it reraises it and the test fails. I'm not sure how to handle this (maybe with lambda { visit ... } ?), but some clarification would be fantastic here, seeing as it's the next logical step someone might try.--Pete Nicholls