docspec 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50f8d84c839b9b2c42002526d2a71b7ba77c3e4593e3bd11707b15437b8ff8fd
-  data.tar.gz: 03b17f9c88a24ac31c405954aadd080b65b8c288ccb3f8b92d25b3ec45d03017
+  metadata.gz: ad249396cfc15361e8f19e3932b5c75ab565b5042ce3431204daf0a39d4f0a14
+  data.tar.gz: a0772e8fd3692466756215f0786709fae4c0772248d1715a0503810a7e0af719
 SHA512:
-  metadata.gz: ad12b1aa05ab33e0fa3d506375c7f5de01edd4da59c3423d995af02b642ce56b6d08820fa0ea602998b6f895e4be8e2b0b2b5cbb4774f46cec4a1e19e7fb26ed
-  data.tar.gz: ed148aa6718aaa0b9c624e9af55b0029a115a6cb48e710d55acb1029ebce895001e5ff77ae9af8c0ee3cdac39cb4972a994a94a2490040dcf1322dce59fab18f
+  metadata.gz: 4985a1fcb629b102bd560fc4a33bb24d18b0ef91368619cfbcc1f053ac2ac3fffa15426e81f1826de87bebeb5233ad4d416551f8eaad9c52f2513cd273d0b04f
+  data.tar.gz: cae6a31e132105853a6015d53d39a3d0ad13bbd99b94fd03e10bedada81e635d7409a2495940d98d9447ff51e9f8249de719e5bd8dfa1aec8a1c4af8dd2a52cc

data/README.md

@@ -20,40 +20,49 @@ Installation
 Usage
 --------------------------------------------------
 
-Add ruby or shell code blocks to your `README.md` document, then run 
-`docspec` to evaluate them.
+Docspec expects one or more Markdown files with embedded code snippets to 
+test.
 
+Code snippets should be enclosed in a `ruby` or `shell` code fence:
 
-Rules
---------------------------------------------------
+    ```ruby
+    code_to_test = 'here'
+    #=> expected output
+    ```
+
+This document itself serves as the test suite for this gem, so you can take a
+look at its source.
 
-- Anything outside of a code fence is ignored.
-- Both `ruby` and `shell` code blocks are supported.
-- Inside a code block, any piece of code that we care about should print
-  something.
-- Inside a code block, anything starting with `#=>` should define the 
-  expected output.
-- If a piece of code raises an error, the captured output will be the 
-  `#inspect` string of that exception.
-- If the first line of a code block includes the string `[:ignore_failure]`, 
-  the example will not be considered an error if it fails.
 
+### Testing with the `docspec` command line
 
-To test the `README.md` in the current folder, just run:
+Test the examples in `./README.md`:
 
     $ docspec
 
-To test a different file, provide it as the first argument:
+Test a different file:
 
     $ docspec TESTS.md
 
 
+### Testing from Ruby code
+
+```ruby
+# Running from Ruby code
+document = Docspec::Document.from_file 'sample.md'
+document.test
+#=> pass : Sample Test
+
+puts document.success?
+#=> true
+```
+
+
 Examples
 --------------------------------------------------
 
-These will be tested with `docspec`:
-
-### Ruby
+Code examples that you want to test, should output something to stdout. 
+Specify the expected output by prefixing it with `#=>`:
 
 ```ruby
 # The first line is an optional label
@@ -61,12 +70,17 @@ puts 'hello world'.upcase
 #=> HELLO WORLD
 ```
 
+If an example raises an exception, the captured output will be the `#inspect`
+string of that exception:
+
 ```ruby
 # Exceptions are captured
 raise ArgumentError, "Testing error raising"
 #=> #<ArgumentError: Testing error raising>
 ```
 
+Your code and expected output can contain multiple lines of code:
+
 ```ruby
 # Multiple lines of code
 string = "hello"
@@ -78,6 +92,8 @@ end
 #=> hello
 ```
 
+and you can alternate between code and expected output:
+
 ```ruby
 # Interleaving code and output 
 puts 2 + 3
@@ -87,6 +103,13 @@ puts 2 - 3
 #=> -1
 ```
 
+The first line of the example may contain specially formatted flags. Flags 
+are always formatted like this: `[:flag_name]`. 
+
+The `[:ignore_failure]` flag allows the example to fail. It will show the 
+failure in the output, but will not elevate the exit status to a failure 
+state:
+
 ```ruby
 # This example may fail [:ignore_failure]
 # Due to the :ignore_failure flag, it will show the failure diff, but will
@@ -95,26 +118,43 @@ puts 'hello world'.upcase
 #=> hello world
 ```
 
+Another available flag, is the `[:skip]` flag, which will omit the example
+from the test run:
+
 ```ruby
-# Code that does not generate any output will be executed before each
-# of the subsequent examples.
+# [:skip]
+this will not be executed
+```
+
+Sometimes it is useful to build the example over several different code 
+blocks. To help achieve this, docspec will treat any example that does not 
+output anything as a code that needs to be executed before all subsequent 
+examples:
+
+```ruby
+# Define a function for later use
 def create_caption(text)
   [text.upcase, ("=" * text.length)].join "\n"
 end
 ```
 
+All the examples below this line, will have the above function available:
+
 ```ruby
-# Example that builds upon code that was defined earlier
+# Use a previously defined function
 puts create_caption "tada!"
 #=> TADA!
 #=> =====
 ```
 
 
-### Shell
+Finally, examples marked with a `shell` code fence will be executed by the
+shell, and not by ruby:
 
 ```shell
 # Shell commands
 echo hello world
 #=> hello world
 ```
+
+

data/bin/docspec

@@ -8,16 +8,16 @@ include Colsole
 
 document = ARGV[0] || 'README.md'
 abort "File not found #{document}" unless File.exist? document
-tester = Docspec::Tester.new document
-success = tester.execute
+document = Docspec::Document.from_file document
+document.test
 
 say ''
 
-if success
-  say "!txtgrn!#{tester.total} tests, #{tester.errors} failed\n"
+if document.success?
+  say "!txtgrn!#{document.total_examples} tests, #{document.failed_examples} failed\n"
   exit 0
 else
-  say "!txtred!#{tester.total} tests, #{tester.errors} failed\n"
+  say "!txtred!#{document.total_examples} tests, #{document.failed_examples} failed\n"
   exit 1
 end
 

data/lib/docspec/document.rb

@@ -1,13 +1,14 @@
 module Docspec
   class Document
-    attr_reader :filename
+    include Testable
+    attr_reader :filename, :markdown
 
-    def initialize(filename)
-      @filename = filename
+    def self.from_file(filename)
+      new File.read(filename)
     end
 
-    def markdown
-      @markdown ||= File.read filename
+    def initialize(markdown)
+      @markdown = markdown
     end
 
     def examples
@@ -19,7 +20,8 @@ module Docspec
     def examples!
       result = []
       markdown.scan(/```(ruby|shell)\s*\n(.*?)```/m) do |type, code|
-        result << Example.new(code, type)
+        example = Example.new(code, type)
+        result << example unless example.skip?
       end
       result
     end

data/lib/docspec/example.rb

@@ -48,6 +48,10 @@ module Docspec
       @full_code = "#{codes}\n#{@full_code}"
     end
 
+    def skip?
+      flags.include? :skip
+    end
+
     def success?
       actual == expected
     end

data/lib/docspec/testable.rb

@@ -0,0 +1,57 @@
+require 'colsole'
+
+module Docspec
+  module Testable
+    include Colsole
+    attr_reader :failed_examples, :total_examples
+
+    def before_codes
+      @before_codes ||= []
+    end
+
+    def success?
+      failed_examples == 0
+    end
+
+    def each_example
+      reset_counters
+
+      examples.each do |example|
+        if example.empty?
+          before_codes << example.code
+        else
+          @total_examples += 1
+          example.prepend before_codes
+          @failed_examples += 1 unless example.success? or example.ignore_failure?
+        end
+        
+        yield example
+      end
+    end
+
+    def test
+      each_example do |example|
+        if example.empty?
+          say "!txtpur!void :!txtrst! #{example.label}"          
+        elsif example.success?
+          say "!txtgrn!pass :!txtrst! #{example.label}"
+        else
+          say "!txtred!FAIL : #{example.label}"
+          say "---"
+          puts example.diff
+          say "---"
+        end
+      end
+    end
+
+  protected
+
+    def reset_counters
+      @before_codes = nil
+      @failed_examples = 0
+      @total_examples = 0
+    end
+
+  end
+end
+

data/lib/docspec/version.rb

@@ -1,3 +1,3 @@
 module Docspec
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/docspec.rb

@@ -2,5 +2,5 @@ require 'byebug' if ENV['BYEBUG']
 
 require 'docspec/output_capturer'
 require 'docspec/example'
-require 'docspec/tester'
+require 'docspec/testable'
 require 'docspec/document'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docspec
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Danny Ben Shitrit
@@ -65,7 +65,7 @@ files:
 - lib/docspec/document.rb
 - lib/docspec/example.rb
 - lib/docspec/output_capturer.rb
-- lib/docspec/tester.rb
+- lib/docspec/testable.rb
 - lib/docspec/version.rb
 homepage: https://github.com/dannyben/docspec
 licenses:

data/lib/docspec/tester.rb

@@ -1,45 +0,0 @@
-require 'colsole'
-
-module Docspec
-  class Tester
-    include Colsole
-    attr_reader :document, :errors, :total
-
-    def initialize(document)
-      document = Document.new document unless document.is_a? Document
-      @document = document
-      @errors = 0
-      @total = 0
-    end
-
-    def before_codes
-      @before_codes ||= []
-    end
-
-    def execute
-      document.examples.each do |example|
-        if example.empty?
-          before_codes << example.code
-          next
-        end
-
-        @total += 1
-
-        example.prepend before_codes
-
-        if example.success?
-          say "!txtgrn!PASS: #{example.label}"
-        else
-          @errors += 1 unless example.ignore_failure?
-          say "!txtred!FAIL: #{example.label}"
-          say "---"
-          puts example.diff
-          say "---"
-        end
-      end
-
-      errors == 0
-    end
-  end
-end
-