CukeTest
=========

It can be useful to package commonly-used Cucumber steps as a gem. And every gem needs tests, right? Enter CukeTest.

CukeTest helps you test individual Cucumber steps with RSpec, verifying that they pass and fail under the right conditions.

Installation
============

    sudo gem install cuke-test

Usage
=====

Suppose you've packaged your Cucumber steps into a gem, and the file structure looks like this:

    my-cuke-steps
      lib
        my-cuke-steps
          steps.rb
      spec
        steps_spec.rb

You want to test your custom Cucumber steps in `steps_spec.rb`. Here's how:

    describe 'My Cuke Steps' do
      before :all do
        CukeTest.config.features_path = File.expand_path(File.dirname(__FILE__)) + '/features'
      end
      
      it 'passes when the expectation is met' do
        # Run an entire feature file
        feature('success.feature').should pass_cuke
        # Run just one scenario in a feature file
        scenario('some_successes_and_some_failures.feature', 'successful scenario').should pass_cuke
      end
      
      it 'fails when the expectation is not met' do
        feature('failure.feature').should fail_cuke('Text of failing step')
      end
    end

Now you need to create the feature files against which the above tests will be run. Put them in `spec/features`. Your new file structure should look like this:

    my-cuke-steps
      lib
        my-cuke-steps
          steps.rb
      spec
        steps_spec.rb
        features
          failure.feature
          some_successes_and_some_failures.feature
          success.feature

The last thing you need to do is tell your specs where to find your custom steps. (Otherwise, the steps you're testing will be undefined.) Fortunately, Cucumber automatically loads `.rb` files in the `features` directory. So we just need to require our step library from a new file within `features`:

    # in spec/features/steps.rb
    require File.expand_path(File.dirname(__FILE__)) + '../../lib/my-cuke-steps/steps.rb')

That's about it for the basic setup. If you're developing a gem where your custom matchers require other code from the same gem (e.g. custom matchers), you'll need to modify `spec/features/steps.rb`:

    # in spec/features/steps.rb
    require File.expand_path(File.dirname(__FILE__)) + '../../lib/my-cuke-steps/steps.rb')
    $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', '..', 'lib'))
    require 'your_gem_name'

You have to do this even if you require the gem files from within your specs, because CukeTest spawns a new process for Cucumber. (The spawned process will not inherit the `require` statements from your spec.)

Copyright
=========

Copyright (c) 2010 Jarrett Colby. See LICENSE for details.