specdown 0.4.0.beta.1 → 0.4.0.beta.2

data/CHANGELOG.markdown

@@ -1,5 +1,9 @@
 ## CHANGELOG
 
+## 0.4.0.beta.2
+
+Refactoring everything. Hopefully it all works.
+
 ## 0.4.0.beta.1
 
 First beta release with implicit specs support. See the "Implicit Specs"

data/README.markdown

@@ -210,6 +210,8 @@ executed, then just don't specifically flag it as Ruby:
 
 ## Implicit Specs
 
+**Note: This feature requires version 0.4.0.beta.1 or greater.** 
+
 In all of the examples so far, we've made all code that we want executed
 explicit within the markdown. Sometimes, however, it's advantageous to
 simply state a specification, and then map that to code
@@ -267,9 +269,9 @@ The article should now be deleted from the database.
 ```
 
 The ".specdown" file is simply a markdown file with a different
-extension. It should consist of an unordered list of spec / definition pairs.
+extension. It should consist simply of headings (of any level) and code blocks. Any other elements within the file will simply be ignore by `specdown`. This allows you to organize the file and add extra comments into it in any way you desire.  
 
-Note that we didn't surround our code with a github-flavored backtick
+Also, Note that we didn't surround our code with a github-flavored backtick
 fence. Since ".specdown" files are solely used for defining implicit
 specifications, it's assumed that all code blocks (unless they're
 spefically marked as something other than ruby) will be executed.
@@ -418,14 +420,6 @@ Specdown::Config.format = :short
 
 The default is `:condensed`.
 
-## TODO
-
-This library is quite new, but I am rapidly adding features to it. Here's what is on the immediate horizon:
-
-* allow flagged text in the markdown to execute code, like a cucumber step definition
-* offer the option of outputing the actual markdown while it executes, instead of "..F....FF......"
-* Better stack traces / reporting
-
 ## LICENSE
 
 This software is [public domain](http://en.wikipedia.org/wiki/Public_domain). GO WILD

data/VERSION

@@ -1 +1 @@
-0.4.0.beta.1
+0.4.0.beta.2

data/features/exception_facade.feature

@@ -6,14 +6,14 @@ Feature: Specdown::ExceptionFacade
       
       exception = Exception.new "exception simulation"
 
-  And given the following fake test_runner:
+  And given the following fake test readme:
 
-      runner = Class.new { attr_accessor :file_name }.new
-      runner.file_name = "test_file.markdown"
+      readme = Class.new { attr_accessor :file_name }.new
+      readme.file_name = "test_file.markdown"
 
   We can now generate an exception facade:
 
-      exception_facade = Specdown::ExceptionFacade.new exception, runner
+      exception_facade = Specdown::ExceptionFacade.new exception, readme
 
       exception_facade.test_filename.should       == "test_file.markdown"
       exception_facade.exception_class.should     == Exception
@@ -26,15 +26,15 @@ Feature: Specdown::ExceptionFacade
         @exception = Exception.new "exception simulation"
       """
 
-    And the following fake runner:
+    And the following fake readme:
       """
-        @runner = Class.new { attr_accessor :file_name }.new
-        @runner.file_name = "test_file.markdown"
+        @readme = Class.new { attr_accessor :file_name }.new
+        @readme.file_name = "test_file.markdown"
       """
 
     When I generate an exception facade:
       """
-        @exception_facade = Specdown::ExceptionFacade.new @exception, @runner
+        @exception_facade = Specdown::ExceptionFacade.new @exception, @readme
       """
 
     Then it should return all kinds of information about the exception and it's context:

data/features/readme.feature

@@ -0,0 +1,97 @@
+Feature: Specdown::Readme
+
+  The `Specdown::Readme` class accepts a markdown parse tree, and runs the tests found within.
+
+  Imagine we start with this markdown file (saved at "specdown.markdown"):
+
+      \# Specdown Example
+
+      This is an example specdown file.
+
+      \## Child Node
+
+      This section is a child node. It contains some ruby code: 
+          
+      ```ruby
+      "simple code".should_not be(nil)
+      ```
+
+      \### First Leaf
+
+      This section has a failure simulation:
+          
+      ```ruby
+      raise "specdown error simulation!"
+      ```
+
+      \## Last Leaf
+
+      This section is a leaf node. It contains some ruby code:
+
+      ```ruby
+      1.should satisfy(&:odd?)
+      ```
+  
+  We can generate a `Specdown::Readme` instance and run the tests in our markdown by simply passing the filename on instantiation:
+
+      readme = Specdown::Readme.new "specdown.markdown"
+      readme.run
+
+  While running, it will emit events during the processing to the Specdown::EventServer. This enables all kinds of functionality, like printing the progress of the tests.
+
+  We can access statistics about the readme execution programatically:
+      
+      readme.stats.num_tests                   #==> 2
+      readme.stats.num_failing                 #==> 1
+      readme.stats.num_passing                 #==> 1
+
+  Scenario: Running tests
+
+    Given the following specdown example file:
+      """
+        # Specdown Example
+
+        This is an example specdown file.
+
+        ## Child Node
+
+        This section is a child node. It contains some ruby code: 
+            
+        ```ruby
+        "simple code".should_not be(nil)
+        ```
+
+        ### First Leaf
+
+        This section has a failure simulation:
+            
+        ```ruby
+        raise "specdown error simulation!"
+        ```
+
+        ## Last Leaf
+
+        This section is a leaf node. It contains some ruby code:
+
+        ```ruby
+        1.should satisfy(&:odd?)
+        ```
+      """
+
+    When I generate a `Specdown::Readme` instance from it:
+      """
+        @readme = Specdown::Readme.new "features/fixtures/parser_example.markdown"
+      """
+
+    Then I should be able to execute the tests:
+      """
+        @readme.execute
+      """
+    
+    And I should be able to access the report data programatically:
+      """
+        @readme.file_name.should == 'parser_example.markdown'
+        @readme.stats.num_tests.should == 2
+        @readme.stats.num_failing.should == 1
+        @readme.stats.num_passing.should == 1
+      """

data/features/report_summary.feature

@@ -1,14 +1,14 @@
 Feature: Specdown::ReportSummary
   
-  A `Specdown::ReportSummary` will provide you with aggregate statistical information about your test suite runners.
+  A `Specdown::ReportSummary` will provide you with aggregate statistical information about your readmes.
 
-  For example, suppose you have several runners that you've executed. You could pass one or more of them off to a `Specdown::ReportSummary` to obtain the aggregate totals:
+  For example, suppose you have several readmes that you've executed. You could pass one or more of them off to a `Specdown::ReportSummary` to obtain the aggregate totals:
 
-      summary = Specdown::ReportSummary.new(runners)
+      summary = Specdown::ReportSummary.new(readmes)
       summary.num_markdowns
       summary.num_tests
-      summary.num_failures
-      summary.num_successes
+      summary.num_failing
+      summary.num_passing
   
   Scenario: A Specdown::Reporter instantiated with a single stats object
 
@@ -43,23 +43,23 @@ Feature: Specdown::ReportSummary
       ```
       """
     
-    And the following runner:
+    And the following readme:
       """
-        @runner = Specdown::Runner.new("features/fixtures/parser_example.markdown")
+        @readme = Specdown::Readme.new("features/fixtures/parser_example.markdown")
       """
 
-    When I run the tests in the runner:
+    When I run the tests in the readme:
       """
-        @runner.run
+        @readme.execute
       """
 
-    Then `Specdown::ReportSummary.new(@runner)` should give me aggregate statistics about my run:
+    Then `Specdown::ReportSummary.new(@readme)` should give me aggregate statistics about my readme execution:
       """
-        summary = Specdown::ReportSummary.new(@runner)
+        summary = Specdown::ReportSummary.new(@readme)
         summary.num_markdowns.should == 1
         summary.num_tests.should == 2
-        summary.num_failures.should == 1
-        summary.num_successes.should == 1
+        summary.num_failing.should == 1
+        summary.num_passing.should == 1
         summary.exceptions.count.should == 1
         summary.exceptions.first.test_filename.should == "parser_example.markdown"
         summary.exceptions.first.exception_class.should == RuntimeError

data/features/step_definitions/exception_facade.rb

@@ -3,7 +3,7 @@ Given /^the following exception:$/ do |string|
   eval string
 end
 
-Given /^the following fake runner:$/ do |string|
+Given /^the following fake readme:$/ do |string|
   eval string
 end
 

data/features/step_definitions/{runner.rb → readme.rb}

@@ -1,8 +1,8 @@
-When /^I generate a `Specdown::Runner` instance from it:$/ do |string|
+When /^I generate a `Specdown::Readme` instance from it:$/ do |string|
   eval string
 end
 
-Then /^I should be able to run the tests:$/ do |string|
+Then /^I should be able to execute the tests:$/ do |string|
   eval string
 end
 

data/features/step_definitions/report_summary.rb

@@ -1,3 +1,3 @@
-Then /^`Specdown::ReportSummary\.new\(@runner\)` should give me aggregate statistics about my run:$/ do |string|
+Then /^`Specdown::ReportSummary\.new\(@readme\)` should give me aggregate statistics about my readme execution:$/ do |string|
   eval string
 end

data/features/step_definitions/reporter.rb

@@ -1,8 +1,8 @@
-Given /^the following runner:$/ do |string|
+Given /^the following readme:$/ do |string|
   eval string
 end
 
-When /^I run the tests in the runner:$/ do |string|
+When /^I run the tests in the readme:$/ do |string|
   eval string
 end
 
@@ -17,7 +17,7 @@ Given /^the following of Specdown::Stats instances:$/ do |string|
   eval string
 end
 
-Then /^`Specdown::Reporter\.new\.summary\(@runner\)` should return a report summary object:$/ do |string|
+Then /^`Specdown::Reporter\.new\.summary\(@readme\)` should return a report summary object:$/ do |string|
   eval string
 end
 

data/features/step_definitions/test.rb

@@ -0,0 +1,129 @@
+Given /^a `Specdown::Test` instance:$/ do |string|
+  eval string
+  @test.code.should be_empty
+end
+
+Then /^I should be able to add code to it:$/ do |string|
+  eval string
+  @test.code.should_not be_empty
+end
+
+Given /^a `Specdown::Test` instance `@test`$/ do
+  @test = Specdown::Test.new
+end
+
+Then /^I should be able to add undefined implicits to it:$/ do |string|
+  @test.undefined_implicits.should be_empty
+  eval string
+  @test.undefined_implicits.should_not be_empty
+end
+
+Given /^a `Specdown::Test` instance `@test` with undefined implicits$/ do
+  @test = Specdown::Test.new
+  @test.undefined_implicits << "1"
+end
+
+When /^I execute the test:$/ do |string|
+  eval string
+end
+
+Then /^`@test\.status` should be :([^\ ]*)$/ do |status|
+  @test.status.should == status.to_sym
+end
+
+When /^I execute it, the test status should be:$/ do
+end
+
+Given /^:passing   if it doesn't throw any exceptions and has no undefined implicits$/ do
+  @test = generate_test(:passing)
+  @test.execute
+  @test.status.should == :passing
+end
+
+Given /^:undefined if it has any undefined implicits$/ do
+  @test = generate_test(:undefined)
+  @test.execute
+  @test.status.should == :undefined
+end
+
+Given /^:pending   if it throws a `Specdown::Pending` exception$/ do
+  @test = generate_test(:pending)
+  @test.execute
+  @test.status.should == :pending
+end
+
+Given /^:failing   if it throws an exception other than `Specdown::Pending`$/ do
+  @test = generate_test(:failing)
+  @test.execute
+  @test.status.should == :failing
+end
+
+Given /^If your test throws an exception, you can access it via the `exception` method$/ do
+  @test = generate_test :failing
+  @test.exception.should be(nil)
+  @test.execute
+  @test.exception.should_not be(nil)
+end
+
+Given /^The `Specdown::Test\.before_execute` method allows you to add code that runs before every test:$/ do |string|
+  before = false
+  Specdown::Test.before_execute do
+    before = true
+  end
+
+  Specdown::Test.new.execute
+  before.should be(true)
+end
+
+Given /^The `Specdown::Test\.after_execute` method allows you to add code that runs after every test:$/ do |string|
+  after = false
+  Specdown::Test.after_execute do
+    after = true
+  end
+
+  Specdown::Test.new.execute
+  after.should be(true)
+end
+
+Given /^The `Specdown::Test\.around_execute` method allows you to add code that runs around every test:$/ do |string|
+  around = nil
+  Specdown::Test.around_execute do
+    if around
+      around = false
+    else
+      around = true
+    end
+  end
+
+  Specdown::Test.new.execute
+  around.should be(false)
+end
+
+Given /^You can remove all `Specdown::Test` callbacks by calling `Specdown::Test\.remove_callbacks!`$/ do
+  Specdown::Test.before_execute do |test|
+    puts "I'm a callback!"
+  end
+
+  Specdown::Test.before_hooks["execute"].should_not be_empty
+
+  Specdown::Test.remove_callbacks!
+
+  Specdown::Test.before_hooks["execute"].should be_empty
+end
+
+def generate_test(status)
+  @test = Specdown::Test.new
+
+  case status
+    when :passing 
+      @test.code << "1"
+    when :failing
+      @test.code << "raise 'exception!'"
+    when :undefined
+      @test.undefined_implicits << "undefined implicit!"
+    when :pending
+      @test.code << "pending"
+  end
+
+  @test
+end

data/features/test.feature

@@ -0,0 +1,131 @@
+Feature: Specdown::Test
+
+  A `Specdown::Test` is constructed by specdown for every path from the root of a markdown file to a leaf section.
+
+  For example, consider the following markdown file:
+
+      \# The Calculator Gem
+
+      ...
+
+      \## A calculation object
+
+      ...
+
+      \### Basic Usage
+
+      ...
+
+      \## Static Operations
+
+      ...
+      
+      \### Saving Results
+
+      ...
+  
+  The headings in this markdown naturally form a tree:
+
+
+                      The Calculator Gem
+                           /     \
+                          /       \
+          A calculation object   Static Operations
+                        /           \ 
+                       /             \
+          Static Operations      Saving Results
+
+
+  Specdown will construct a `Specdown::Test` object for each path from the root ("The Calculator Gem") to a leaf, gathering any code (whether explicit or implicit) along the way:
+  
+  * The Calculator Gem -> A calculation object -> Static Operations
+  * The Calculator Gem -> Static Operations    -> Saving Results
+
+  It will also tell the test about any undefined implicits it finds within the markdown.
+
+  You can add code to a test via the "code" array accessor:
+
+      test      = Specdown::Test.new
+      test.code << "puts 'hi'"
+      test.code << "howdy"
+
+  If your markdown contains any undefined implicit specifications, you can add them to a `Specdown::Test` instance via the "undefined_implicits" method:
+
+      test.undefined_implicits << "I am an implicit specification that is not yet defined!"
+
+  You can execute the test via the "execute" method:
+
+      test.execute
+
+  After the test executes, you can get the status of the test via the `status` method. It will return one of the following symbols: `:passing`, `:failing`, `:pending`, `:undefined`.
+
+  If a test throws an exception, that exception will be captured and made accessible via the `exception` method.
+
+  You can add callbacks to tests via the "before_execute", "after_execute", and "around_execute" methods:
+
+      Specdown::Test.after_execute do |test|
+        case test.status
+          when :passing   then Specdown.reporter.print_success(test)
+          when :failing   then Specdown.reporter.print_failure(test)
+          when :pending   then Specdown.reporter.print_pending(test)
+          when :undefined then Specdown.reporter.print_undefined(test)
+        end
+      end
+
+
+  Scenario: Reset callbacks
+    * You can remove all `Specdown::Test` callbacks by calling `Specdown::Test.remove_callbacks!`
+
+  Scenario: Add code
+    Given a `Specdown::Test` instance:
+      """
+        @test = Specdown::Test.new
+      """
+
+    Then I should be able to add code to it:
+      """
+        @test.code << "1"
+        @test.code << "2"
+      """
+
+
+  Scenario: Add undefined implicits
+    Given a `Specdown::Test` instance `@test`
+    Then I should be able to add undefined implicits to it:
+      """
+        @test.undefined_implicits << "implicit 1"
+        @test.undefined_implicits << "implicit 2"
+      """
+
+  Scenario: Status after test execution
+    Given a `Specdown::Test` instance `@test`
+    When I execute it, the test status should be:
+      * :passing   if it doesn't throw any exceptions and has no undefined implicits
+      * :undefined if it has any undefined implicits
+      * :pending   if it throws a `Specdown::Pending` exception
+      * :failing   if it throws an exception other than `Specdown::Pending` 
+
+  Scenario: Capturing exceptions  
+    * If your test throws an exception, you can access it via the `exception` method
+
+  Scenario: Hooks
+    * The `Specdown::Test.before_execute` method allows you to add code that runs before every test:
+      """
+        Specdown::Test.before do |test|
+          puts "I run before every test!"
+        end
+      """
+
+    * The `Specdown::Test.after_execute` method allows you to add code that runs after every test:
+      """
+        Specdown::Test.after do |test|
+          puts "I run after every test!"
+        end
+      """
+
+    * The `Specdown::Test.around_execute` method allows you to add code that runs around every test:
+      """
+        Specdown::Test.around do |test|
+          puts "I run around every test!"
+        end
+      """