= Rspec Cells

<em>Spec your Cells.</em>

{<img src="https://secure.travis-ci.org/apotonick/rspec-cells.png" />}[http://travis-ci.org/apotonick/rspec-cells]

This plugin allows you to test your cells easily using RSpec. Basically, it adds a cells example group with a <tt>#render_cell</tt> helper.

Cells is Rails' popular {view components framework}[http://github.com/apotonick/cells].

= Installation

This gem runs with RSpec2 and Rails >= 3.x, so just add it to your app's +Gemfile+.

  group :test do
    gem "rspec-cells"
  end

= Usage

Simply put all your specs in the <tt>spec/cells</tt> directory. However, let the cell generator do that for you!

  rails g cell blog_post show -t rspec

will create an exemplary <tt>spec/cells/blog_post_cell_spec.rb</tt> for you.


== API

=== Old API

In your specs you can use +render_cell+ to assert the rendered markup (or whatever your state is supposed to do). This goes fine with Webrat matchers.

  it "renders posts count" do
    render_cell(:posts, :count).should have_selector("p", :content => "4 posts!")
  end

You can create a cell instance using the +cell+ method, and then render afterwards. This is helpful when you're planning to stub things or if you need to pass arguments to the cell constructor.

  it "renders empty posts list" do
    posts = cell(:posts)
    posts.stub(:recent_posts).and_return([])

    posts.render_state(:count).should have_selector("p", :content => "No posts!")
  end

After preparing the instance you can use +render_state+ for triggering the state.


=== View Models

With the introduction of cells [view models]() you get a slightly different API for your specs (which is identical to your app's one).

  it "renders empty posts list" do
    posts = cell(:posts).count.should should have_css "#comment_new .flag", visible: true)
  end

It's pretty simple, you use `#cell` to instantiate a view model instance and then call the state method on it.


== Capybara

If you want Capybara's string matchers be sure to bundle at least capybara +0.4.1+ in your Gemfile.

  group :development, :test do
    gem "capybara", "~> 0.4.1"
  end

In order to make the cells test generator work properly, capybara needs to be in both groups.


You can then use capybara's matchers in your cell spec.

  describe PostsCell do
    describe "search posts" do
      let(:search) { render_cell(:posts, :search) }

      it "should have a search field" do
        search.should have_field("Search by Title")
      end

      it "should have a search button" do
        search.should have_button("Search")
      end
    end

    describe "latest posts" do
      subject { render_cell(:posts, :latest) }

      it { should have_css("h3.title", :text => "Latest Posts") }
      it { should have_table("latest_posts") }
      it { should have_link("View all Posts") }
      it { should_not have_button("Create Post") }
      it { should_not have_field("Search by Title") }
    end
  end

You can see all capybara matchers and finders {here}[http://rubydoc.info/github/jnicklas/capybara/master/Capybara/Node/Simple].

== Running the specs

Run your examples with

  rake spec:cells

If you need more helpers, matchers and stuff, {just let us know}[http://cells.rubyforge.org/community.html].

== Contributors

* Jorge Calás Lozano <calas@qvitta.net> (Cleanup, capybara string matchers)

== LICENSE

Copyright (c) 2010, Nick Sutterer

Copyright (c) 2007-2009, Dmytro Shteflyuk <kpumuk@kpumuk.info> http://kpumuk.info

Released under the MIT License.