== API

==== Given steps

"Given <b>a model</b> exists",  e.g.

  Given a user exists
  Given a user: "fred" exists
  Given the user exists

"Given <b>a model</b> exists with <b>fields</b>",  e.g.

  Given a user exists with name: "Fred"
  Given a user exists with name: "Fred", activated: false

You can refer to other models in the fields

  Given a user exists
  And a post exists with author: the user

  Given a person: "fred" exists
  And a person: "ethel" exists
  And a fatherhood exists with parent: user "fred", child: user "ethel"

"Given <b>n models</b> exist", e.g.

  Given 10 users exist

"Given <b>n models</b> exist with <b>fields</b>", examples:

  Given 10 users exist with activated: false

"Given the following <b>models</b> exist:", examples:

  Given the following users exist
    | name  | activated |
    | Fred  | false     |
    | Ethel | true      |

==== Then steps

===== Asserting existence of models

"Then <b>a model</b> should exist",  e.g.

  Then a user should exist

"Then <b>a model</b> should exist with <b>fields</b>", e.g.

  Then a user: "fred" should exist with name: "Fred" # we can label the found user for later use

You can use other models, booleans, numerics, and strings as fields

  Then a person should exist with child: person "ethel"
  Then a user should exist with activated: false
  Then a user should exist with activated: true, email: "fred@gmail.com"

"Then <b>n models</b> should exist", e.g.

  Then 10 events should exist

"Then <b>n models</b> should exist with <b>fields</b>", e.g.

  Then 2 people should exist with father: person "fred"

"Then the following <b>models</b> exist". This allows the creation of multiple models
using a table syntax. Using a column with the singularized name of the model creates a referenceable model. E.g.

  Then the following users exist:
    | name   | activated |
    | Freddy | false     |

  Then the following users exist:
    | user | name   | activated |
    | Fred | Freddy | false     |

===== Asserting associations

One-to-one assocs: "Then <b>a model</b> should be <b>other model</b>'s <b>association</b>", e.g.

  Then the person: "fred" should be person: "ethel"'s father

Many-to-one assocs: "Then <b>a model</b> should be [in|one of] <b>other model</b>'s <b>association</b>", e.g.

  Then the person: "ethel" should be one of person: "fred"'s children
  Then the comment should be in the post's comments

===== Asserting predicate methods

"Then <b>a model</b> should [be|have] [a|an] <b>predicate</b>", e.g.

  Then the user should have a status # => user.status.should be_present
  Then the user should have a stale password # => user.should have_stale_password
  Then the car: "batmobile" should be fast # => car.should be_fast

"Then <b>a model</b> should not [be|have] [a|an] <b>predicate</b>", e.g.

  Then person: "fred" should not be childless # => fred.should_not be_childless

=== Regexps for use in your own steps

By default you get some regexps available in the main namespace for use
in creating your own steps: `capture_model`, `capture_fields`, and others (see lib/pickle.rb)

(You can use any of the regexps that Pickle uses by using the Pickle.parser namespace, see
Pickle::Parser::Matchers for the methods available)

*capture_model*

  Given /^#{capture_model} exists$/ do |model_name|
    model(model_name).should_not == nil
  end

  Then /^I should be at the (.*?) page$/ |page|
    if page =~ /#{capture_model}'s/
      url_for(model($1))
    else
      # ...
    end
  end

  Then /^#{capture_model} should be one of #{capture_model}'s posts$/ do |post, forum|
    post = model!(post)
    forum = model!(forum)
    forum.posts.should include(post)
  end

*capture_fields*

This is useful for setting attributes, and knows about pickle model names so that you
can build up composite objects with ease

  Given /^#{capture_model} exists with #{capture_fields}$/ do |model_name, fields|
    create_model(model_name, fields)
  end

  # example of use
  Given a user exists
  And a post exists with author: the user # this step will assign the above user as :author on the post