Skip to content
Browse files

use github-flavored-markup in readme

  • Loading branch information...
1 parent 1354f1a commit d13d28f329a5ba7284c4df3f2610efc74ba4a90f @dchelimsky dchelimsky committed Dec 4, 2011
Showing with 113 additions and 87 deletions.
  1. +1 −1 Gemfile-custom.sample
  2. +112 −86 README.md
View
2 Gemfile-custom.sample
@@ -1,6 +1,6 @@
group :development do
gem 'interactive_rspec'
- gem 'yard'
+ gem 'yard', "~> 0.7.4"
gem "relish", "~> 0.5.0"
gem "guard-rspec", "0.5.0"
gem "growl", "1.0.3"
View
198 README.md
@@ -1,5 +1,12 @@
# rspec-core
+```
+gem install rspec # for rspec-core, rspec-expectations, rspec-mocks
+gem install rspec-core # for rspec-core only
+```
+
+# overview
+
rspec-core provides the structure for writing executable examples of how
your code should behave. It uses the words "describe" and "it" so we can
express concepts like a conversation:
@@ -9,19 +16,21 @@ express concepts like a conversation:
## basic structure
- describe Order do
- it "sums the prices of its line items" do
- order = Order.new
- order.add_entry(LineItem.new(:item => Item.new(
- :price => Money.new(1.11, :USD)
- )
- order.add_entry(LineItem.new(:item => Item.new(
- :price => Money.new(2.22, :USD),
- :quantity => 2
- )
- order.total.should eq(Money.new(5.55, :USD))
- end
- end
+```ruby
+describe Order do
+ it "sums the prices of its line items" do
+ order = Order.new
+ order.add_entry(LineItem.new(:item => Item.new(
+ :price => Money.new(1.11, :USD)
+ )))
+ order.add_entry(LineItem.new(:item => Item.new(
+ :price => Money.new(2.22, :USD),
+ :quantity => 2
+ )))
+ order.total.should eq(Money.new(5.55, :USD))
+ end
+end
+```
The `describe` method creates an [ExampleGroup](../RSpec/Core/ExampleGroup). Within the
block passed to `describe` you can declare examples using the `it` method.
@@ -35,19 +44,21 @@ context of an _instance_ of that class.
You can also declare nested nested groups using the `describe` or `context`
methods:
- describe Order to
- context "with no items" do
- it "behaves one way" do
- # ...
- end
- end
-
- context "with one item" do
- it "behaves another way" do
- # ...
- end
- end
+```ruby
+describe Order do
+ context "with no items" do
+ it "behaves one way" do
+ # ...
+ end
+ end
+
+ context "with one item" do
+ it "behaves another way" do
+ # ...
end
+ end
+end
+```
## aliases
@@ -62,19 +73,21 @@ You can declare examples within a group using any of `it`, `specify`, or
Declare a shared example group using `shared_examples`, and then include it
in any group using `include_examples`.
- shared_examples "collections" do |collection_class|
- it "is empty when first created" do
- collection_class.new.should be_empty
- end
- end
+```ruby
+shared_examples "collections" do |collection_class|
+ it "is empty when first created" do
+ collection_class.new.should be_empty
+ end
+end
- describe Array do
- include_examples "collections", Array
- end
+describe Array do
+ include_examples "collections", Array
+end
- describe Hash do
- include_examples "collections", Hash
- end
+describe Hash do
+ include_examples "collections", Hash
+end
+```
Nearly anything that can be declared within an example group can be declared
within a shared example group. This includes `before`, `after`, and `around`
@@ -96,39 +109,45 @@ and filtering before and after hooks.
Although you probably won't ever need this unless you are writing an
extension, you can access it from an example like this:
- it "does something" do
- example.metadata[:description].should eq("does something")
- end
+```ruby
+it "does something" do
+ example.metadata[:description].should eq("does something")
+end
+```
### `described_class`
When a class is passed to `describe`, you can access it from an example
using the `described_class` method, which is a wrapper for
`example.metadata[:described_class]`.
- describe Widget do
- example do
- described_class.should equal(Widget)
- end
- end
+```ruby
+describe Widget do
+ example do
+ described_class.should equal(Widget)
+ end
+end
+```
This is useful in extensions or shared example groups in which the specific
class is unknown. Taking the shared examples example from above, we can
clean it up a bit using `described_class`:
- shared_examples "collections" do
- it "is empty when first created" do
- described.new.should be_empty
- end
- end
+```ruby
+shared_examples "collections" do
+ it "is empty when first created" do
+ described.new.should be_empty
+ end
+end
- describe Array do
- include_examples "collections"
- end
+describe Array do
+ include_examples "collections"
+end
- describe Hash do
- include_examples "collections"
- end
+describe Hash do
+ include_examples "collections"
+end
+```
## the `rspec` command
@@ -146,52 +165,59 @@ Run `rspec --help` to see the complete list.
Start with a simple example of behavior you expect from your system. Do
this before you write any implementation code:
- # in spec/calculator_spec.rb
- describe Calculator do
- it "add(x,y) returns the sum of its arguments" do
- Calculator.new.add(1, 2).should eq(3)
- end
- end
+```ruby
+# in spec/calculator_spec.rb
+describe Calculator do
+ it "add(x,y) returns the sum of its arguments" do
+ Calculator.new.add(1, 2).should eq(3)
+ end
+end
+```
Run this with the rspec command, and watch it fail:
- $ rspec spec/calculator_spec.rb
- ./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
+$ rspec spec/calculator_spec.rb
+./spec/calculator_spec.rb:1: uninitialized constant Calculator
+```
Implement the simplest solution:
- # in lib/calculator.rb
- class Calculator
- def add(a,b)
- a + b
- end
- end
+```ruby
+# in lib/calculator.rb
+class Calculator
+ def add(a,b)
+ a + b
+ end
+end
+```
Be sure to require the implementation file in the spec:
- # in spec/calculator_spec.rb
- # - RSpec adds ./lib to the $LOAD_PATH
- require "calculator"
+```ruby
+# in spec/calculator_spec.rb
+# - RSpec adds ./lib to the $LOAD_PATH
+require "calculator"
+```
Now run the spec again, and watch it pass:
- $ rspec spec/calculator_spec.rb
- .
+```
+$ rspec spec/calculator_spec.rb
+.
- Finished in 0.000315 seconds
- 1 example, 0 failures
+Finished in 0.000315 seconds
+1 example, 0 failures
+```
Use the `documentation` formatter to see the resulting spec:
- $ rspec spec/calculator_spec.rb --format doc
- Calculator add
- returns the sum of its arguments
-
- Finished in 0.000379 seconds
- 1 example, 0 failures
-
-## install
+```
+$ rspec spec/calculator_spec.rb --format doc
+Calculator add
+ returns the sum of its arguments
- gem install rspec # for rspec-core, rspec-expectations, rspec-mocks
- gem install rspec-core # for rspec-core only
+Finished in 0.000379 seconds
+1 example, 0 failures
+```

0 comments on commit d13d28f

Please sign in to comment.
Something went wrong with that request. Please try again.