README.rdoc in shared_should-0.5.6 vs README.rdoc in shared_should-0.6.0

- old
+ new

@@ -14,53 +14,53 @@ context "Book" do context "with an in-stock book" do setup { @book = Book.new(:quantity => 1, :price => 10_00 } ### Define a shared should - shared_should_be "available for checkout" { assert @book.available_for_checkout? } + share_should "be available for checkout" { assert @book.available_for_checkout? } context "with a rentable book" do setup { @book.rentable = true } - ### Use the "available for checkout" shared_should - should_be "available for checkout" + ### Use the "be available for checkout" share_should + use_should "be available for checkout" end context "with a purchasable book" do setup { @book.purchasable = true } - ### Use the "available for checkout" shared_should in this context too - should_be "available for checkout" + ### Use the "be available for checkout" share_should in this context too + use_should "be available for checkout" end ### ...or DRY it up by using .with or .when and an initialization block - should_be("available for checkout").when("rentable") { @book.rentable = true } - should_be("available for checkout").when("purchasable") { @book.purchasable = true } + use_should("be available for checkout").when("rentable") { @book.rentable = true } + use_should("be available for checkout").when("purchasable") { @book.purchasable = true } end end === Shared Setup Sharing setups is easy, too. context "Book" do ### Define a shared setup - shared_setup_for "an in-stock book" { @book = Book.new(:quantity => 1, :price => 10_00) } + share_setup "for an in-stock book" { @book = Book.new(:quantity => 1, :price => 10_00) } context "with an in-stock rentable book" do ### Use the shared setup here - setup_for "an in-stock book" + use_setup "for an in-stock book" ### Do some additional setup after the shared setup setup { @book.rentable = true } should "be available for checkout" { assert @book.available_for_checkout? } end context "with an in-stock purchasable book" do ### Use the shared setup again - setup_for "an in-stock book" + use_setup "for an in-stock book" setup { @book.purchasable = true } should "be available for checkout" { assert @book.available_for_checkout? } end @@ -73,42 +73,42 @@ context "Book" do context "with an in-stock book" do setup { @book = Book.new(:quantity => 1, :price => 10_00) } ### Define a shared context - shared_context_for "a book available for checkout" do + share_context "for a book available for checkout" do should "be in stock" { assert @book.quantity > 0 } should "have a non-negative price" { assert @book.price > 0 } should "be rentable or purchasable" { assert @book.rentable || @book.purchasable } end context "with a rentable book" do setup { @book.rentable = true } ### Run the shoulds inside the shared context with a rentable book - should_be "a book available for checkout" + use_context "for a book available for checkout" end context "with a purchasable book" do setup { @book.purchasable = true } ### Run the shoulds inside the shared context again with a purchasable book - should_be "a book available for checkout" + use_context "for a book available for checkout" end ### ...or DRY it up by using .with or .when and an initialization block - should_be("a book available for checkout").when("rentable") { @book.rentable = true } - should_be("a book available for checkout").when("purchasable") { @book.purchasable = true } + use_context("for a book available for checkout").when("rentable") { @book.rentable = true } + use_context("for a book available for checkout").when("purchasable") { @book.purchasable = true } end end == More Information on Syntax and Usage === Finding Your Share Some rules: -* When <tt>should_be</tt> or <tt>setup_for</tt> is invoked, it searches up the context hierarchy to find a matching shared definition. +* When <tt>use_should</tt>, <tt>use_context</tt> or <tt>use_setup</tt> is invoked, it searches up the context hierarchy to find a matching shared definition. * You can redefine your shares by using the same name. These shares will only be available in in the current and descendant contexts. * Shares defined at the root (on your TestCase) are available in all contexts. * If you define a shared setup at the root level, you will need to call <tt>super</tt> if you have a setup instance method for your test. === Initialization Block @@ -116,34 +116,34 @@ The shared invocation accepts an initialization block by chaining <tt>when</tt> or <tt>with</tt>. This block can be used to create or modify instance variables used by the shared functionality. It always executes before the shared functionality. context "Book" do setup { @book = Book.new(:quantity => 1, :price => 10_00) } - shared_should_be "available for checkout" { assert @book.available_for_checkout? } + share_should "be available for checkout" { assert @book.available_for_checkout? } context "with a rentable book" do - # when shared_should_be "available for checkout" is executed, @book will have rentable equal to true - should_be "available for checkout".when("rentable") { @book.rentable = true } + # when share_should "be available for checkout" is executed, @book will have rentable equal to true + use_should "be available for checkout".when("rentable") { @book.rentable = true } end context "with a purchasable book" do - should_be "available for checkout".when("purchasable") { @book.purchasable = true } + use_should "be available for checkout".when("purchasable") { @book.purchasable = true } end end === Parameterizing Shares Shared functions can also be parameterized using block parameters. This can be done for shared setups, shoulds, and the setups and shoulds contained within a shared context. The value passed to the declared shared function is the return value of the initialization block. The below example parameterizes a shared setup. context "Book" do - shared_setup_for "an in-stock book" do |rentable| + share_setup "for an in-stock book" do |rentable| @book = Book.new(:quantity => 1, :price => 10_00, :rentable => rentable, :purchasable => false) end context "with rentable book" do # the return value of the block is "true" which will be passed as the block parameter "rentable" - setup_for("an in-stock book").with("a rentable book") { true } + use_setup("for an in-stock book").with("a rentable book") { true } should "be available for checkout" { assert @book.available_for_checkout? } end end @@ -151,73 +151,73 @@ context "Book" do context "with in-stock book" do setup { @book = Book.new(:quantity => 1) } - shared_should_be "unavailable for checkout for price" do |price| + share_should "be unavailable for checkout for price" do |price| @book.price = price assert_false @book.available_for_checkout? end - should_be("unavailable for checkout for price").when("zero") { 0 } - should_be("unavailable for checkout for price").when("negative") { -1 } + use_should("be unavailable for checkout for price").when("zero") { 0 } + use_should("be unavailable for checkout for price").when("negative") { -1 } end end And a parameterized shared context. context "Book" do context "with in-stock book" do setup { @book = Book.new(:quantity => 1) } - shared_context_for "a book available for checkout at price" do + share_context "for a book available for checkout at price" do # parameters are on the setup and shoulds, not on the context setup { |price| @book.price = price } # we could also access price in the should blocks, but we don't need it again should "be in stock" { assert @book.quantity > 0 } should "have a non-negative price" { assert @book.price > 0 } should "be rentable or purchasable" { assert @book.rentable || @book.purchasable } end - should_be("a book available for checkout at price").when("positive") { 10_00 } + use_context("for a book available for checkout at price").when("positive") { 10_00 } end end The shared functions also accept multiple parameters when the initialization block returns an array. context "Book" do context "with rentable book" do setup { @book = Book.new(:rentable => true) } - shared_should_be "unavailable for checkout for quantity and price" do |quantity, price| + share_should "be unavailable for checkout for quantity and price" do |quantity, price| @book.quantity = quantity @book.price = price assert_false @book.available_for_checkout? end - should_be("unavailable for checkout for quantity and price").when("zero quantity") { [0, 10_00] } - should_be("unavailable for checkout for quantity and price").when("zero price") { [1, 0] } + use_should("be unavailable for checkout for quantity and price").when("zero quantity") { [0, 10_00] } + use_should("be unavailable for checkout for quantity and price").when("zero price") { [1, 0] } end end === Creating a Library of Shared Functionality The shared functions can also be re-usable across multiple test cases. In your test helper file: class Test::Unit::TestCase - shared_setup_for "an in-stock book" do |rentable, purchasable| + share_setup "for an in-stock book" do |rentable, purchasable| @book = Book.new(:quantity => 1, :price => 10_00, :rentable => rentable, :purchasable => purchasable) end end In your test file: class BookTest < Test::Unit::TestCase context "with an in-stock book" do - shared_setup_for "an in-stock book".with { [true, true] } + share_setup "for an in-stock book".with { [true, true] } should "be in stock" { assert @book.quantity > 0 } end end