adamgoucher/rspec-syntax-cheat-sheet.rb

## rspec-syntax-cheat-sheet.rb
# RSpec 2.0 syntax Cheet Sheet by http://ApproachE.com

# defining spec within a module will automatically pick Player::MovieList as a 'subject' (see below)
module Player
	describe MovieList, "with optional description" do

	  it "is pending example, so that you can write ones quickly"

	  it "is already working example that we want to suspend from failing temporarily" do
		pending("working on another feature that temporarily breaks this one")
		# actual test code is here, will never be reached
	  end

	  it "is pending when failing" do
		  pending "This will be marked as pending when the block will fail, otherwise (on success) will fail telling 'Why am I pending if I pass?'" do
			  1.should == 2 # will mark example as pending
			  2.should == 2 # will fail asking to remove pending status of example
		  end
	  end

	  # filters can be on describe/context or it
	  it "has as single boolean filter", :oscar => true
	  it "has as single filter with a custom value", :rating => 'family'
 	  it "has as two filters", :oscar => true, :rating => 'family'

	  # this will automatically generate name of the example based on the expectations inside it ~ 'it' with no description
	  specify { [1,2,3].should have(3).items }

	  #any helper methods, before/after, modules etc declared in the outer group are available in the inner group.
	  describe "outer" do
		  before(:each) { puts "first" }
		  describe "inner" do
			before(:each) { puts "second" }
			it { puts "third"}
			after(:each) { puts "fourth" }
		  end
		  after(:each) { puts "fifth" }
	  end

	  # 'describe' and 'context' are equivalent
	  # I prefer to use 'context' for defining an 'environment'
	  context "when first created" do
		it "is empty" do
		  movie_list = MovieList.new
		  movie_list.should be_empty
		end
	  end

	  # I prefer to use 'describe' for nouns, verbs; defining a nested set of specifications
	  describe "forward" do
		it "should jump to a next movie" do
		  next_movie = MovieList.new(2).forward
		  next_movie.track_number.should == 2
		end
	  end
	end

	it "will have default subject that corresponds to the instance of first parameter in 'describe'" do
		subject.class.should be == MovieList
	end
	# unless subject is set explicitly
	subject { MovieList.new(10) } # approximately similar to 'before(:each)'
	# no need to use 'subject.should', use 'should'
	specify { should have(10).items } # same as below
	specify { subject.should have(10).items }


	# similar to specify { subject.track_number.should == 1}
	its(:track_number) { should == 1 }

	context "specs set-up" do
		# we can run setup before each examle, or all of them
		before(:each) do
			@new_on_each_example = YourObject.new
		end
		before do
			@new_on_each_spec_less_verbose = YourObject.new
		end
		before(:all) do
			# Avoid using it as it will bring the 'shared state' into unit tests
			@same_instance_for_all_examples_within_the_context = YourObject.new
		end
		it "can access attributes defined in 'before'" do
			@new_on_each_example.should_not be_nil
			@same_instance_for_all_examples_within_the_context.should_not be_nil
		end

		# cleanup code can be run the same way using 'after' instead of 'before'
		# Avoid using 'after'
		# we can wrap examples: before + after + manual handling
		# In most cases 'before' + 'after' will work better.
		around do |example|
			DB.transaction { example.run }
			# should handle errors manually, so do not do something like:
			# DB.start_transaction
			# example.run
			# DB.rollback_transaction
		end
		it "should run within a transaction" do
			MovieList.new.save!
		end

		let(:new_on_each_example) { ObjectPerExample.new }
		it "can use method defined by 'let'" do
			new_on_each_example.should_not be_nil
			# the object is memoized, so
			new_on_each_example.should == new_on_each_example
		end

		# defining helper methods within context may be more useful than setup
		def forward(times) do
			list = MoviewList.new(10)
			list.forward(times).track_number
		end
		it "can use it multiple times" do
			forward(1).should == 1
			forward(2).should == 2
			forward(10).should == 1
		end

		# using 'yield' with helper methods
		def given_thing_with(options)
			yield Thing.new do |thing|
				thing.set_status(options[:status])
			end
		end
		it "should do something when ok" do
			given_thing_with(:status => 'ok') do |thing|
				thing.do_fancy_stuff(1, true, :move => 'left', :obstacles => nil)
			end
		end


		# helpers can come from modules
		module Helpers
			def shared_help
				[1,2,3]
			end
		end
		include Helpers
		it "can use helpers from Module" do
			shared_help.should == [1,2,3]
		end
		# or this module can be included for ALL example groups automatically during configuration:
		# RSpec.configure do |config|
		#	config.include Helpers
		# end
	end

	# set of same examples shared accross multiple specs
	# shared_examples_for should be in a separate file and defined outside of 'describe'/'context'
	shared_examples_for "any pizza" do
		it "tastes really good" do
			@pizza.should taste_really_good
		end
	end

	# to include the shared examples, into example groups:
	# it will assume @pizza instance variable is available here
	it_behaves_like "any pizza"

	context 'defining examples dynamically - everybody knows that :)' do
		{2 => 4, 3 => 6, 10 => 20}.each do |input, output|
			it "#{input} * 2 should be equal to #{output}" do
				(input * 2).should == output
				# will produce examples:
				# - 2 * 2 should be equal to 4
				# - 3 * 2 should be equal to 6
				# - 10 * 2 should be equal to 20
			end
		end
	end


	context "matchers" do
		it "shows built-in matchers" do
			# TODO: describe ===, eql, equal
			1.should == 1
			1.should_not == 2 # NOT 1.should != 2
			1.should_not equal(2) # same as above
			1.should_not == 2
			5.should be > 3
			5.should be <= 5
			(1.251).should be_close(1.25, 0.005)
			(1.251).should be_within(0.005).of 1.25 # >= RSpec 2.1
			"reg exp".should =~ /exp/
			[1,2].should include(1)
			1.should respond_to(:to_s)

			true.should be_true
			0.should be_true
			"this".should be_true

			lambda { Object.new.explodde! }.should raise_error(NameError)

			# nothing fits
			5.should satisfy { |it| it == 5 }
		end

		it "shows cool things" do
			count = 1
			expect {
				count = 3
			}.to change { count }.by(2)

			expect {
				# not changing
			}.to_not change { count }

			count = 1
			expect {
				count = 3
			}.to change { count }.to(3)

			count = 1
			expect {
				count = 3
			}.to change { count }from(1).to(3)

			# raise-rescue - exception handling
			expect {2 / 0}.to raise_error("divided by 0")
			expect {2 / 0}.to raise_error(/by 0/)
			expect {2 / 0}.to raise_error(ZeroDivisionError)

			# try-catch - expected circumstance handling
			lambda {  throw :room_is_full }.should throw_symbol(:room_is_full)

			# predicates
			nil.should be_nil #call nil.nil?
			[].should be_empty # calls [].empty?
			[1,2,3].should_not be_empty # calls [1,2,3].empty

			# convert anything that begins with have_ to a predicate on the target object beginning with has_
			{:id => 1}.has_key?(:id).should == true
			# can be written as
			{:id => 1}.should have_key(:id) # calls {:id => 1}.has_key?(:id)

			# collections
			obj = {}
			def obj.numbers
			 [1,2,3,4]
			end

			obj.should have(4).numbers # calls obj.numbers.length
			[1,2,3,4].should have(4).items # 'items' is 'reserved' to say "ensure number of items on the collection"
			[1,2,3,4].should be_any {|n| n % 2 == 0} # [1,2,3,4].any? {|n| n %% 2 == 0}.should be_true
			"stringy".should have(7).charaters # same as items, just syntactic sugar
			[1,2,3,4].should have_exactly(24).items # same as 'have'
			obj.should have_at_least(3).numbers


		end
	end # built-in matchers


	context "custom matchers" do
		# TODO: describe multiple ways

		#define class
		class SimilarTo
			# mandatory - link to the object under test
			def initialize(it)
				# object under test
				@it = it
			end
			# mandatory - check the positive condition
			def matches?(that)
				@that = that # save to use it in messages
				@that.to_s.downcase.should == @it.to_s.downcase
			end
			# optional - opoosite to mathch?
			def does_not_matche?(that)
				result = !matches?(that)
				@that, @it = @it, @that # swap for negative condition or additionally cusomtize messages
				result # don't forget to return
			end
			# mandatory
			def failure_message_for_should
				"expected #{@it} to be similar to #{@that}"
			end
			# optional
			def failure_message_for_should_not
				"expected #{@it} to be different from #{@that}"
			end
			#optional
			def description
				"#{@it} should be similar to #{@that}"
			end
		end

		#define method on example (see set-up to incude in all examples)
		def similar_to(that)
			SimilarTo.new(that)
		end
	end # custom matchers


	context "macros" do
		module ControllerMacros
		  def should_render(template)
			it "should render the #{template} template" do
			  do_request
			  response.should render_template(template)
			end
		  end

		  def should_assign(hash)
			variable_name = hash.keys.first
			model, method = hash[variable_name]
			model_access_method = [model, method].join('.')
			it "should assign @#{variable_name} => #{model_access_method}" do
			  expected = "the value returned by #{model_access_method}"
			  model.should_receive(method).and_return(expected)
			  do_request
			  assigns[variable_name].should == expected
			end
		  end

		  def get(action)
			define_method :do_request do
			  get action
			end
			yield
		  end
		end

		RSpec.configure do |config|
		  config.use_transactional_fixtures = true
		  config.use_instantiated_fixtures  = false
		  config.fixture_path = RAILS_ROOT + '/spec/fixtures/'
		  config.extend(ControllerMacros, :type => :controller)
		end
	end # macros

end # module
	# RSpec 2.0 syntax Cheet Sheet by http://ApproachE.com

	# defining spec within a module will automatically pick Player::MovieList as a 'subject' (see below)
	module Player
	describe MovieList, "with optional description" do

	it "is pending example, so that you can write ones quickly"

	it "is already working example that we want to suspend from failing temporarily" do
	pending("working on another feature that temporarily breaks this one")
	# actual test code is here, will never be reached
	end

	it "is pending when failing" do
	pending "This will be marked as pending when the block will fail, otherwise (on success) will fail telling 'Why am I pending if I pass?'" do
	1.should == 2 # will mark example as pending
	2.should == 2 # will fail asking to remove pending status of example
	end
	end

	# filters can be on describe/context or it
	it "has as single boolean filter", :oscar => true
	it "has as single filter with a custom value", :rating => 'family'
	it "has as two filters", :oscar => true, :rating => 'family'

	# this will automatically generate name of the example based on the expectations inside it ~ 'it' with no description
	specify { [1,2,3].should have(3).items }

	#any helper methods, before/after, modules etc declared in the outer group are available in the inner group.
	describe "outer" do
	before(:each) { puts "first" }
	describe "inner" do
	before(:each) { puts "second" }
	it { puts "third"}
	after(:each) { puts "fourth" }
	end
	after(:each) { puts "fifth" }
	end

	# 'describe' and 'context' are equivalent
	# I prefer to use 'context' for defining an 'environment'
	context "when first created" do
	it "is empty" do
	movie_list = MovieList.new
	movie_list.should be_empty
	end
	end

	# I prefer to use 'describe' for nouns, verbs; defining a nested set of specifications
	describe "forward" do
	it "should jump to a next movie" do
	next_movie = MovieList.new(2).forward
	next_movie.track_number.should == 2
	end
	end
	end

	it "will have default subject that corresponds to the instance of first parameter in 'describe'" do
	subject.class.should be == MovieList
	end
	# unless subject is set explicitly
	subject { MovieList.new(10) } # approximately similar to 'before(:each)'
	# no need to use 'subject.should', use 'should'
	specify { should have(10).items } # same as below
	specify { subject.should have(10).items }


	# similar to specify { subject.track_number.should == 1}
	its(:track_number) { should == 1 }

	context "specs set-up" do
	# we can run setup before each examle, or all of them
	before(:each) do
	@new_on_each_example = YourObject.new
	end
	before do
	@new_on_each_spec_less_verbose = YourObject.new
	end
	before(:all) do
	# Avoid using it as it will bring the 'shared state' into unit tests
	@same_instance_for_all_examples_within_the_context = YourObject.new
	end
	it "can access attributes defined in 'before'" do
	@new_on_each_example.should_not be_nil
	@same_instance_for_all_examples_within_the_context.should_not be_nil
	end

	# cleanup code can be run the same way using 'after' instead of 'before'
	# Avoid using 'after'
	# we can wrap examples: before + after + manual handling
	# In most cases 'before' + 'after' will work better.
	around do \|example\|
	DB.transaction { example.run }
	# should handle errors manually, so do not do something like:
	# DB.start_transaction
	# example.run
	# DB.rollback_transaction
	end
	it "should run within a transaction" do
	MovieList.new.save!
	end

	let(:new_on_each_example) { ObjectPerExample.new }
	it "can use method defined by 'let'" do
	new_on_each_example.should_not be_nil
	# the object is memoized, so
	new_on_each_example.should == new_on_each_example
	end

	# defining helper methods within context may be more useful than setup
	def forward(times) do
	list = MoviewList.new(10)
	list.forward(times).track_number
	end
	it "can use it multiple times" do
	forward(1).should == 1
	forward(2).should == 2
	forward(10).should == 1
	end

	# using 'yield' with helper methods
	def given_thing_with(options)
	yield Thing.new do \|thing\|
	thing.set_status(options[:status])
	end
	end
	it "should do something when ok" do
	given_thing_with(:status => 'ok') do \|thing\|
	thing.do_fancy_stuff(1, true, :move => 'left', :obstacles => nil)
	end
	end


	# helpers can come from modules
	module Helpers
	def shared_help
	[1,2,3]
	end
	end
	include Helpers
	it "can use helpers from Module" do
	shared_help.should == [1,2,3]
	end
	# or this module can be included for ALL example groups automatically during configuration:
	# RSpec.configure do \|config\|
	# config.include Helpers
	# end
	end

	# set of same examples shared accross multiple specs
	# shared_examples_for should be in a separate file and defined outside of 'describe'/'context'
	shared_examples_for "any pizza" do
	it "tastes really good" do
	@pizza.should taste_really_good
	end
	end

	# to include the shared examples, into example groups:
	# it will assume @pizza instance variable is available here
	it_behaves_like "any pizza"

	context 'defining examples dynamically - everybody knows that :)' do
	{2 => 4, 3 => 6, 10 => 20}.each do \|input, output\|
	it "#{input} * 2 should be equal to #{output}" do
	(input * 2).should == output
	# will produce examples:
	# - 2 * 2 should be equal to 4
	# - 3 * 2 should be equal to 6
	# - 10 * 2 should be equal to 20
	end
	end
	end


	context "matchers" do
	it "shows built-in matchers" do
	# TODO: describe ===, eql, equal
	1.should == 1
	1.should_not == 2 # NOT 1.should != 2
	1.should_not equal(2) # same as above
	1.should_not == 2
	5.should be > 3
	5.should be <= 5
	(1.251).should be_close(1.25, 0.005)
	(1.251).should be_within(0.005).of 1.25 # >= RSpec 2.1
	"reg exp".should =~ /exp/
	[1,2].should include(1)
	1.should respond_to(:to_s)

	true.should be_true
	0.should be_true
	"this".should be_true

	lambda { Object.new.explodde! }.should raise_error(NameError)

	# nothing fits
	5.should satisfy { \|it\| it == 5 }
	end

	it "shows cool things" do
	count = 1
	expect {
	count = 3
	}.to change { count }.by(2)

	expect {
	# not changing
	}.to_not change { count }

	count = 1
	expect {
	count = 3
	}.to change { count }.to(3)

	count = 1
	expect {
	count = 3
	}.to change { count }from(1).to(3)

	# raise-rescue - exception handling
	expect {2 / 0}.to raise_error("divided by 0")
	expect {2 / 0}.to raise_error(/by 0/)
	expect {2 / 0}.to raise_error(ZeroDivisionError)

	# try-catch - expected circumstance handling
	lambda { throw :room_is_full }.should throw_symbol(:room_is_full)

	# predicates
	nil.should be_nil #call nil.nil?
	[].should be_empty # calls [].empty?
	[1,2,3].should_not be_empty # calls [1,2,3].empty

	# convert anything that begins with have_ to a predicate on the target object beginning with has_
	{:id => 1}.has_key?(:id).should == true
	# can be written as
	{:id => 1}.should have_key(:id) # calls {:id => 1}.has_key?(:id)

	# collections
	obj = {}
	def obj.numbers
	[1,2,3,4]
	end

	obj.should have(4).numbers # calls obj.numbers.length
	[1,2,3,4].should have(4).items # 'items' is 'reserved' to say "ensure number of items on the collection"
	[1,2,3,4].should be_any {\|n\| n % 2 == 0} # [1,2,3,4].any? {\|n\| n %% 2 == 0}.should be_true
	"stringy".should have(7).charaters # same as items, just syntactic sugar
	[1,2,3,4].should have_exactly(24).items # same as 'have'
	obj.should have_at_least(3).numbers


	end
	end # built-in matchers





	context "custom matchers" do
	# TODO: describe multiple ways

	#define class
	class SimilarTo
	# mandatory - link to the object under test
	def initialize(it)
	# object under test
	@it = it
	end
	# mandatory - check the positive condition
	def matches?(that)
	@that = that # save to use it in messages
	@that.to_s.downcase.should == @it.to_s.downcase
	end
	# optional - opoosite to mathch?
	def does_not_matche?(that)
	result = !matches?(that)
	@that, @it = @it, @that # swap for negative condition or additionally cusomtize messages
	result # don't forget to return
	end
	# mandatory
	def failure_message_for_should
	"expected #{@it} to be similar to #{@that}"
	end
	# optional
	def failure_message_for_should_not
	"expected #{@it} to be different from #{@that}"
	end
	#optional
	def description
	"#{@it} should be similar to #{@that}"
	end
	end

	#define method on example (see set-up to incude in all examples)
	def similar_to(that)
	SimilarTo.new(that)
	end
	end # custom matchers




	context "macros" do
	module ControllerMacros
	def should_render(template)
	it "should render the #{template} template" do
	do_request
	response.should render_template(template)
	end
	end

	def should_assign(hash)
	variable_name = hash.keys.first
	model, method = hash[variable_name]
	model_access_method = [model, method].join('.')
	it "should assign @#{variable_name} => #{model_access_method}" do
	expected = "the value returned by #{model_access_method}"
	model.should_receive(method).and_return(expected)
	do_request
	assigns[variable_name].should == expected
	end
	end

	def get(action)
	define_method :do_request do
	get action
	end
	yield
	end
	end

	RSpec.configure do \|config\|
	config.use_transactional_fixtures = true
	config.use_instantiated_fixtures = false
	config.fixture_path = RAILS_ROOT + '/spec/fixtures/'
	config.extend(ControllerMacros, :type => :controller)
	end
	end # macros

	end # module