yard-doctest 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd5ed8e592d798085c06707ac39cc89772b80bca
-  data.tar.gz: 026c3d35c873ddb3ee9c5847d5ca8d89cb46b599
+  metadata.gz: ca18f61aa4d2ab189d9e0edb48011a7423bf7a3c
+  data.tar.gz: 0a84c6dd74503b1abcfe4b5b494725f6af6800ec
 SHA512:
-  metadata.gz: 98762b209916d0d4e5da1f62f30b5189cacb07ed56f3c066abb3f3b15f12db2b84f6d5b2123a7254ee914bb7e7cbd20ca75b88cf4f5b993c7bb9dd72808f599f
-  data.tar.gz: 695cb4f162d40bafa601b1736fe8c9d2f639e3094ffbab6b2a7cd128bec756698741433c87a8ec13db42481665a57b682f3899acb39982e6c4a773bcb49362db
+  metadata.gz: 3ff564c3d96544f560d361c385330967844c19d7de10bca805673261b3f36ceb48dcf29b57e24efe83533ff1e360d9da15a4dd61967316ef13a42accdfa14d61
+  data.tar.gz: 63d7ab908736488e14cd50ecbdde1c272d8f25399b00b5b3d340afbe6b3ccc1c65d01ff1bd64542f311e6eb195b261f2e8eeb89b2f773efd2d4a4ffa06421e02

data/README.md

@@ -98,11 +98,11 @@ $ bundle exec yard config -a autoload_plugins yard-doctest
 Next, you'll need to create test helper, which will be required before each of your test. Think about it as `spec_helper.rb` in RSpec or `env.rb` in Cucumber. You should require everything necessary for your examples to run there.
 
 ```bash
-$ touch yard-doctest_helper.rb
+$ touch doctest_helper.rb
 ```
 
 ```ruby
-# yard-doctest_helper.rb
+# doctest_helper.rb
 require 'lib/cat'
 require 'lib/dog'
 ```
@@ -195,6 +195,8 @@ It is actually delegated to amazing [minitest](https://github.com/seattlerb/mini
 
 ## Advanced usage
 
+### Test helper
+
 You can define any methods and instance variables in test helper and they will be available in examples.
 
 For example, if we change the examples for `Cat#can_hunt_dogs?` like that:
@@ -224,7 +226,7 @@ NameError: undefined local variable or method `cat' for Object:Class
 If you don't want to create new instance of class each time (or include module if you're testing it), you can fix this by defining a method in test helper:
 
 ```ruby
-# yard-doctest_helper.rb
+# doctest_helper.rb
 require 'lib/cat'
 require 'lib/dog'
 
@@ -233,26 +235,58 @@ def cat
 end
 ```
 
+### Hooks
+
 In case you need to do some preparations/cleanup between tests, hooks are at your service to be defined in test helper:
 
 ```ruby
-YARD::Doctest.before do
-  # this is called before each example and
-  # evaluated in the same context as example
-  # (i.e. has access to the same instance variables)
+YARD::Doctest.configure do |doctest|
+  doctest.before do
+    # this is called before each example and
+    # evaluated in the same context as example
+    # (i.e. has access to the same instance variables)
+  end
+
+  doctest.after do
+    # same as `before`, but runs after each example
+  end
+
+  doctest.after_run do
+    # runs after all the examples and
+    # has different context
+    # (i.e. no access to instance variables)
+  end
 end
+```
+
+There is also a way to limit hooks to specific tests based on class/method name:
 
-YARD::Doctest.after do
-  # same as `before`, but runs after each example
+```ruby
+YARD::Doctest.configure do |doctest|
+  doctest.before('MyClass') do
+    # this will only be called for doctests of `MyClass` class
+    # and all its methods (i.e. `MyClass.foo`, `MyClass#bar`)
+  end
+
+  doctest.after('MyClass#foo') do
+    # this will only be called for doctests of `MyClass#foo`
+  end
 end
+```
 
-YARD::Doctest.after_run do
-  # runs after all the examples and
-  # has different context
-  # (i.e. no access to instance variables)
+### Skip
+
+You can skip running some of the tests:
+
+```ruby
+YARD::Doctest.configure do |doctest|
+  doctest.skip 'MyClass' # will skip doctests for `MyClass` and all its methods
+  doctest.skip 'MyClass#foo' # will skip doctests for `MyClass#foo`
 end
 ```
 
+### Rake
+
 There is also a Rake task for you:
 
 ```ruby

data/features/yard-doctest.feature

@@ -11,7 +11,7 @@ Feature: yard doctest
     Then the output should contain "doctest  Doctests from @example tags"
 
   Scenario: looks for files in app/lib directories by default
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       require 'lib/lib'
@@ -36,7 +36,7 @@ Feature: yard doctest
     Then the output should contain "2 runs, 2 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario Outline: looks for files only in passed glob
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       require 'lib/lib'
@@ -68,7 +68,7 @@ Feature: yard doctest
       | app/app.rb  |
 
   Scenario: generates test names from unit name
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -109,7 +109,7 @@ Feature: yard doctest
     And the output should contain "B#div"
 
   Scenario: asserts using equality
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -129,7 +129,7 @@ Feature: yard doctest
       """
 
   Scenario Outline: properly handles different return values
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -159,7 +159,7 @@ Feature: yard doctest
       | 1.0   |
 
   Scenario: handles multiple @example tags
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -177,7 +177,7 @@ Feature: yard doctest
     Then the output should contain "2 runs, 2 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: handles multiple return comments
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -195,7 +195,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 2 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: runs @example tags without return comment
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -211,7 +211,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 0 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: handles `# =>` return comment
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -227,7 +227,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: handles return comment on newline
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -244,7 +244,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: handles multiple lines
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -263,7 +263,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: names test with example title when it's present
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -279,7 +279,7 @@ Feature: yard doctest
     Then the output should contain "#sum#test_0001_sums two numbers"
 
   Scenario: doesn't name test when title is not present
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -295,7 +295,7 @@ Feature: yard doctest
     Then the output should contain "#sum#test_0001_"
 
   Scenario: adds unit definition to backtrace on failures
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -311,7 +311,7 @@ Feature: yard doctest
     Then the output should contain "app/app.rb:3"
 
   Scenario: has rake task to run the tests
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -335,7 +335,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: requires doctest helper
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
 
@@ -359,7 +359,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: shares binding between asserts
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -378,7 +378,7 @@ Feature: yard doctest
     Then the output should contain "1 runs, 2 assertions, 0 failures, 0 errors, 0 skips"
 
   Scenario: does not share binding between examples
-    Given a file named "yard-doctest_helper.rb" with:
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
       """
@@ -397,23 +397,67 @@ Feature: yard doctest
     When I run `bundle exec yard doctest`
     Then the output should contain "NameError: undefined local variable or method `a'"
 
-  Scenario: supports hooks
-    Given a file named "yard-doctest_helper.rb" with:
+  Scenario: supports global hooks
+    Given a file named "doctest_helper.rb" with:
       """
       require 'app/app'
 
-      @flag = true
+      YARD::Doctest.before { @flag = false  }
+      YARD::Doctest.after { @flag = true  }
+      YARD::Doctest.after_run { puts 'Run after all by minitest' }
+      """
+    And a file named "app/app.rb" with:
+      """
+      # @example
+      #   flag #=> false
+      def flag
+        @flag
+      end
+      """
+    When I run `bundle exec yard doctest`
+    Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
+    And the output should contain "Run after all by minitest"
+
+  Scenario: supports test-name hooks
+    Given a file named "doctest_helper.rb" with:
+      """
+      require 'app/app'
 
       YARD::Doctest.before do
+        @flag = true
+        @foo = true
+      end
+
+      YARD::Doctest.before('#flag') do
         @flag = false
+        @foo = false
+      end
+      """
+    And a file named "app/app.rb" with:
+      """
+      # @example
+      #   flag #=> false
+      def flag
+        @flag && @foo
       end
 
-      YARD::Doctest.after do
-        @flag = true
+      # @example
+      #   foo #=> true
+      def foo
+        @foo && @flag
       end
+      """
+    When I run `bundle exec yard doctest`
+    Then the output should contain "2 runs, 2 assertions, 0 failures, 0 errors, 0 skips"
 
-      YARD::Doctest.after_run do
-        puts 'Run after all by minitest'
+  Scenario: can skip tests
+    Given a file named "doctest_helper.rb" with:
+      """
+      require 'app/app'
+
+      YARD::Doctest.configure do |doctest|
+        doctest.skip '#flag'
+        doctest.skip 'A.foo'
       end
       """
     And a file named "app/app.rb" with:
@@ -423,7 +467,14 @@ Feature: yard doctest
       def flag
         @flag
       end
+
+      class A
+        # @example
+        #   A.foo => true
+        def self.foo
+          true
+        end
+      end
       """
     When I run `bundle exec yard doctest`
-    Then the output should contain "1 runs, 1 assertions, 0 failures, 0 errors, 0 skips"
-    And the output should contain "Run after all by minitest"
+    Then the output should contain "0 runs, 0 assertions, 0 failures, 0 errors, 0 skips"

data/lib/yard-doctest.rb

@@ -9,38 +9,79 @@ require 'yard/doctest/version'
 
 module YARD
   module Doctest
+    extend self
 
-    class << self
-      #
-      # Passed block called before each example and
-      # evaluated in the same context as example.
-      #
-      # @param [Proc] blk
-      #
-      def before(&blk)
-        block_given? ? @before = blk : @before
-      end
+    #
+    # Configures YARD doctest.
+    #
+    # @yield [self]
+    #
+    def configure
+      yield self
+    end
 
-      #
-      # Passed block called after each example and
-      # evaluated in the same context as example.
-      #
-      # @param [Proc] blk
-      #
-      def after(&blk)
-        block_given? ? @after = blk : @after
-      end
+    #
+    # Passed block called before each example
+    # or specific tests based on passed name.
+    #
+    # It is evaluated in the same context as example.
+    #
+    # @param [String] test
+    # @param [Proc] blk
+    #
+    def before(test = nil, &blk)
+      hooks[:before] << {test: test, block: blk} if block_given?
+    end
+
+    #
+    # Passed block called after each example
+    # or specific tests based on passed name.
+    #
+    # It is evaluated in the same context as example.
+    #
+    # @param [String] test
+    # @param [Proc] blk
+    #
+    def after(test = nil, &blk)
+      hooks[:after] << {test: test, block: blk} if block_given?
+    end
+
+    #
+    # Passed block called after all examples and
+    # evaluated in the different context from examples.
+    #
+    # It actually just sends block to `Minitest.after_run`.
+    #
+    # @param [Proc] blk
+    #
+    def after_run(&blk)
+      Minitest.after_run &blk
+    end
+
+    #
+    # Adds definition of test to be skipped.
+    #
+    # @param [Array<String>] test
+    #
+    def skip(test)
+      skips << test
+    end
+
+    #
+    # Array of tests to be skipped.
+    # @api private
+    #
+    def skips
+      @skips ||= []
+    end
 
-      #
-      # Passed block called after all examples and
-      # evaluated in the different context from examples.
-      #
-      # It actually just sends block to `Minitest.after_run`.
-      #
-      # @param [Proc] blk
-      #
-      def after_run(&blk)
-        Minitest.after_run &blk
+    #
+    # Returns hash with arrays of before/after hooks.
+    # @api private
+    #
+    def hooks
+      @hooks ||= {}.tap do |hash|
+        hash[:before], hash[:after] = [], []
       end
     end
 

data/lib/yard/doctest/example.rb

@@ -21,23 +21,24 @@ module YARD
 
         Class.new(this.class).class_eval do
           require 'minitest/autorun'
-          require 'yard-doctest_helper'
+          require 'doctest_helper'
 
-          describe this.definition do
-            before { evaluate YARD::Doctest.before } if YARD::Doctest.before.is_a?(Proc)
-            after  { evaluate YARD::Doctest.after  } if YARD::Doctest.after.is_a?(Proc)
+          unless YARD::Doctest.skips.any? { |skip| this.definition.include?(skip) }
+            describe this.definition do
+              register_hooks(this.definition, YARD::Doctest.hooks)
 
-            it this.name do
-              this.asserts.each do |assert|
-                expected, actual = assert[:expected], assert[:actual]
-                actual = context.eval(actual)
+              it this.name do
+                this.asserts.each do |assert|
+                  expected, actual = assert[:expected], assert[:actual]
+                  actual = context.eval(actual)
 
-                unless expected.empty?
-                  begin
-                    assert_equal evaluate(expected), actual
-                  rescue Minitest::Assertion => error
-                    add_filepath_to_backtrace(error, this.filepath)
-                    raise error
+                  unless expected.empty?
+                    begin
+                      assert_equal evaluate(expected), actual
+                    rescue Minitest::Assertion => error
+                      add_filepath_to_backtrace(error, this.filepath)
+                      raise error
+                    end
                   end
                 end
               end
@@ -59,12 +60,28 @@ module YARD
 
       def add_filepath_to_backtrace(exception, filepath)
         backtrace = exception.backtrace
-        line = backtrace.find { |line| line =~ %r(lib/yard/doctest/example) }
+        line = backtrace.find { |l| l =~ %r(lib/yard/doctest/example) }
         index = backtrace.index(line)
         backtrace = backtrace.insert(index, filepath)
         exception.set_backtrace backtrace
       end
 
+      def self.register_hooks(definition, all_hooks)
+        all_hooks.each do |type, hooks|
+          hooks.each do |hook|
+            if hook[:test]
+              # test-name hooks
+              if definition.include?(hook[:test])
+                send(type) { evaluate(hook[:block]) }
+              end
+            else
+              # global hooks
+              send(type) { evaluate(hook[:block]) }
+            end
+          end
+        end
+      end
+
     end # Example
   end # Doctest
 end # YARD

data/lib/yard/doctest/version.rb

@@ -1,5 +1,5 @@
 module YARD
   module Doctest
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yard-doctest
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Alex Rodionov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-17 00:00:00.000000000 Z
+date: 2014-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard