Adding rspec-rails as a :test group dependency

Project Hydra traditionally makes use of the Rspec testing framework.

From http://rspec.info/
RSpec is testing tool for the Ruby programming language. Born under
the banner of Behaviour-Driven Development, it is designed to make
Test-Driven Development a productive and enjoyable experience with
features like:

* a rich command line program (the rspec command)
* textual descriptions of examples and groups (rspec-core)
* flexible and customizable reporting
* extensible expectation language (rspec-expectations)
* built-in mocking/stubbing framework (rspec-mocks)

By declaring rspec-rails in the :test group, the gem is only available
when the application is running in test.
Bundling up rspec-rails and its dependencies.

The following commands were run:
$ bundle
Initializing rspec for our application

The following commands were run:
$ rspec --init
Setting test framework generator to rspec

By default Rails provides numerous generators. Other gems can also
provide generators. Run `rails generate` or its synonym `rails g` to
see a list of all the generators.

Most generators will generate "production" code and "test" code. By
setting our test framework to :rspec, the generators will – if they
are written "properly" – create rspec files for us.

http://guides.rubyonrails.org/generators.html#customizing-your-workflow
Ensuring that Rails loads up for our specs

Prior to this change, when I would run `rspec` from the command line,
I would get the following exception:
    spec/models/user_spec.rb:3:in `<top (required)>':
      uninitialized constant User (NameError)

What was happening is that rspec without the spec_helper changes was
unable to find where the User class was defined.

By adding these lines Rails now successfully boots.
Adding Devise 3.1.x to Gemfile

The `gem "devise", "~> 3.1.0"` declaration indicates that I only want
to use versions of Devise that are in the 3.1.x family.
I believe Devise is using to [semantic versioning](http://semver.org/)

Devise is a "Flexible authentication solution for Rails with Warden."
https://github.com/plataformatec/devise

Warden is a "General Rack Authentication Framework"
https://github.com/hassox/warden

Rack is "a modular Ruby webserver interface"
https://github.com/rack/rack
http://rack.github.io/
Bundling up Devise and its dependencies.

Among other things, Devise added the following dependencies to our
project.
    devise (3.1.0)
      bcrypt-ruby (~> 3.0)
      orm_adapter (~> 0.1)
      railties (>= 3.2.6, < 5)
      thread_safe (~> 0.1)
      warden (~> 1.2.3)

The following commands were run:
$ bundle
Installing devise via generator

As per https://github.com/plataformatec/devise#getting-started

The following commands were run:
$ rails generate devise:install
Managing devise authentication via User model

It is convention that the User model be the model that persists
passwords and negotiates authentication.

As per https://github.com/plataformatec/devise#getting-started

The following commands were run:
$ rails generate devise User
Running migrations for Devise's User

More about migrations at http://guides.rubyonrails.org/migrations.html
By running `rake db:migrate` we are applying Devise changes and
additions to our *development* database.

The following commands were run:
$ rake db:migrate
Adding capybara to test arsenal

From https://github.com/jnicklas/capybara
Capybara helps you test web applications by simulating how a real user
would interact with your app. It is agnostic about the driver running
your tests and comes with Rack::Test and Selenium support built in.
WebKit is supported through an external gem.
Bundling up capybara and its dependencies.

Capybara adds the following dependencies. You'll likely want to
remember nokogiri.
    capybara (2.1.0)
      mime-types (>= 1.16)
      nokogiri (>= 1.3.3)
      rack (>= 1.0.0)
      rack-test (>= 0.5.4)
      xpath (~> 2.0)

From http://nokogiri.org
Nokogiri (鋸) is an HTML, XML, SAX, and Reader parser. Among
Nokogiri’s many features is the ability to search documents via XPath
or CSS3 selectors.

XML is like violence - if it doesn’t solve your problems, you are not
using enough of it.

The following commands were run:
$ bundle
Adding capybara to the spec_helper

https://github.com/jnicklas/capybara#using-capybara-with-rspec
Adding the first thoughts on user signup

The describe do, it do is the foundational structure of rspec.
"Describe" provides the context in which we are running our specs.
"It" is the context for an expectation/assertion.
Adding first spec step for viewing singup page

By using `rake routes` I was able to inspect what the existing routes
were for my Rails application. It looks like '/users/sign_in' is the
path to the Devise signup page.

Once the change was made, I ran `rspec` and an
ActiveRecord::StatementInvalid exception was raised (see below).

Rspec said that it could not find the 'users' table. This is because
our *test* database has not been created. When `rake db:migrate` is
run, only the *development* database was modified.

So I ran `rake db:test:prepare` and then ran `rspec`.

The following failure occurred when I ran `rspec`:

    Failures:

      1) user signup attempting to login without an account
         Failure/Error: visit('/users/sign_in')
         ActiveRecord::StatementInvalid:
           Could not find table 'users'

    Finished in 0.04759 seconds
    2 examples, 1 failure, 1 pending

    Failed examples:

    rspec ./spec/features/user_signup_spec.rb:4 # user signup…
Adding second spec step for user sign up

Filling out the sign in form, I needed to see what the page looked
like, in particular what the DOM elements were.

So I fired up the `rails server` (`rails s` is the synonym) and
visited http://localhost:3000/users/sign_in. With my developer tools
(Firebug or Developer Tools) I inspected the DOM and found the
`form.edit_user` CSS selector to be reasonable.

More information about targeting elements via Capybara:

https://github.com/jnicklas/capybara#scoping
Adding final step for validation

From https://github.com/plataformatec/devise#configuring-controllers

    Remember that Devise uses flash messages to let users know if sign
    in was successful or failed. Devise expects your application to
    call "flash[:notice]" and "flash[:alert]" as appropriate.

I was expecting my application to implement some sort of FlashHash
rendering. For more on Rails' FlashHash, see the following:
http://guides.rubyonrails.org/action_controller_overview.html#the-flash

Out of the box it does not. So I updated the application layout to
include a naive implementation of the flash handler. It was copied
directly from the Ruby on Rails Action Controller Overview Guide page.

But how did I know the warning message should be "Invalid email or
password." My original expectation was:

`page.should have_content('Missing')`

Once I added the FlashHash handling, the error message changed from:

    Capybara::ExpectationNotMet:
      expected to find css "div" with text "Missing." but there were
      no matches. Also found "", "Email", "Password", "Remember me",
      "", which matched the selector but not all filters.

To

    Capybara::ExpectationNotMet:
        expected to find css "div" with text "Missing." but there were
        no matches. Also found "Invalid email or password.", "",
        "Email", "Password", "Remember me", "", which matched the
        selector but not all filters.

Notice the addition of "Invalid email or password." That is the
message I was looking for.
Adding and bundling capybara-selenium driver

I want to see what is happening in my capybara tests. With
capybara-selenium, the feature specs will run in a full browser
(as opposed to a headless brwoser). Then we can see what our tests are
doing.
https://github.com/jnicklas/capybara#selecting-the-driver

The following commands were run:
$ bundle