docspec 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 285211d9493c575fb886a6e587e6163440017936c9171a015f323ee5b5e75f12
+  data.tar.gz: 8481fd32a94801a88e995c82acee35cbf82f703f59212194e5b8da07d88c1607
+SHA512:
+  metadata.gz: acee792d5459ed127e6508feb898c3dc37f7cd0a705c3076ac0adbe457470de40b13282a465527a58275cdc7c21785a4e74cd8fd9d692bb3c24d1e026c6e0def
+  data.tar.gz: c5e0e51cef54cf5080914695a1f6292bdd50bfbf113deb10d439e5b093d5265715d02f0172df6f4d551161ea002e5a9416ea00f8b51d30c607ee4f1f1b1a817d

data/README.md

@@ -0,0 +1,96 @@
+Docspec
+==================================================
+
+[![Gem Version](https://badge.fury.io/rb/docspec.svg)](https://badge.fury.io/rb/docspec)
+
+Inline tests in Markdown documents.
+
+---
+
+
+Installation
+--------------------------------------------------
+
+    $ gem install docspec
+
+
+Usage
+--------------------------------------------------
+
+Add ruby or shell code blocks to your `README.md` document, then run 
+`docspec` to evaluate them.
+
+
+Rules
+--------------------------------------------------
+
+- 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.
+
+To test the `README.md` in the current folder, just run:
+
+    $ docspec
+
+To test a different file, provide it as the first argument:
+
+    $ docspec TESTS.md
+
+
+Examples
+--------------------------------------------------
+
+These will be tested with `docspec`:
+
+### Ruby
+
+```ruby
+# The first line is an optional label
+puts 'hello world'.upcase
+#=> HELLO WORLD
+```
+
+```ruby
+# Exceptions are captured
+raise ArgumentError, "Testing error raising"
+#=> #<ArgumentError: Testing error raising>
+```
+
+```ruby
+# Multiple lines of code
+string = "hello"
+3.times do 
+  puts string
+end
+#=> hello
+#=> hello
+#=> hello
+```
+
+```ruby
+# Interleaving code and output 
+puts 2 + 3
+#=> 5
+
+puts 2 - 3
+#=> -1
+```
+
+```ruby
+# This example should fail
+puts 'hello world'.upcase
+#=> hello world
+```
+
+### Shell
+
+```shell
+# Shell commands
+echo hello world
+#=> hello world
+```

data/bin/docspec

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+require 'simplecov'
+SimpleCov.start
+
+require 'docspec'
+require 'colsole'
+include Colsole
+
+document = ARGV[0] || 'README.md'
+abort "File not found #{document}" unless File.exist? document
+tester = Docspec::Tester.new document
+success = tester.execute
+
+say ''
+
+if tester.expected_failures != 0
+  say "!txtblu!Expected failures: #{tester.expected_failures}"
+end
+
+if success
+  say "!txtgrn!#{tester.total} tests, #{tester.errors} failed\n"
+  exit 0
+else
+  say "!txtred!#{tester.total} tests, #{tester.errors} failed\n"
+  exit 1
+end
+
+

data/lib/docspec.rb

@@ -0,0 +1,6 @@
+require 'byebug' if ENV['BYEBUG']
+
+require 'docspec/output_capturer'
+require 'docspec/example'
+require 'docspec/tester'
+require 'docspec/document'

data/lib/docspec/document.rb

@@ -0,0 +1,28 @@
+module Docspec
+  class Document
+    attr_reader :filename
+
+    def initialize(filename)
+      @filename = filename
+    end
+
+    def markdown
+      @markdown ||= File.read filename
+    end
+
+    def examples
+      @examples ||= examples!
+    end
+
+  protected
+
+    def examples!
+      result = []
+      markdown.scan(/```(ruby|shell)\n(.*?)```/m) do |type, code|
+        result << Example.new(code, type)
+      end
+      result
+    end
+
+  end
+end

data/lib/docspec/example.rb

@@ -0,0 +1,52 @@
+require 'diffy'
+
+module Docspec
+  class Example
+    include OutputCapturer
+
+    attr_reader :code, :type
+
+    def initialize(code, type)
+      @code, @type = code, type
+    end
+
+    def label
+      @label ||= label!
+    end
+
+    def expected
+      @expected ||= code.scan(/#=>\s*(.*)/).map { |match| match.first.strip }.join "\n"
+    end
+
+    def actual
+      @actual ||= actual!
+    end
+
+    def passing?
+      actual == expected
+    end
+
+    def diff
+      Diffy::Diff.new(expected, actual, context: 2).to_s :color
+    end
+
+  protected
+
+    def label!
+      first_line = code.split("\n").first
+      first_line.gsub(/^#\s*/, '').strip
+    end
+
+    def actual!
+      capture_output do
+        case type
+        when 'ruby'
+          instance_eval(code)
+        when 'shell'
+          puts `#{code}`
+        end
+      end.strip
+    end
+
+  end
+end

data/lib/docspec/output_capturer.rb

@@ -0,0 +1,16 @@
+module Docspec
+  module OutputCapturer
+    def capture_output
+      original_stdout = $stdout
+      $stdout = StringIO.new
+      begin
+        yield
+        $stdout.string
+      rescue => e
+        "#{$stdout.string}#{e.inspect}"
+      ensure
+        $stdout = original_stdout
+      end
+    end
+  end
+end

data/lib/docspec/tester.rb

@@ -0,0 +1,39 @@
+require 'colsole'
+
+module Docspec
+  class Tester
+    include Colsole
+    attr_reader :document, :errors
+
+    def initialize(document)
+      document = Document.new document unless document.is_a? Document
+      @document = document
+      @errors = 0
+    end
+
+    def total
+      @total ||= document.examples.count
+    end
+
+    def execute
+      document.examples.each do |example|
+        if example.passing?
+          say "!txtgrn!PASS: #{example.label}"
+        else
+          @errors += 1
+          say "!txtred!FAIL: #{example.label}"
+          say "---"
+          puts example.diff
+          say "---"
+        end
+      end
+
+      errors == expected_failures
+    end
+
+    def expected_failures
+      ENV['DOCSPEC_EXPECTED_FAILURES']&.to_i || 0
+    end
+  end
+end
+

data/lib/docspec/version.rb

@@ -0,0 +1,3 @@
+module Docspec
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: docspec
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Danny Ben Shitrit
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-10-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colsole
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: diffy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+description: Make your READMEs testable
+email: db@dannyben.com
+executables:
+- docspec
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/docspec
+- lib/docspec.rb
+- lib/docspec/document.rb
+- lib/docspec/example.rb
+- lib/docspec/output_capturer.rb
+- lib/docspec/tester.rb
+- lib/docspec/version.rb
+homepage: https://github.com/dannyben/docspec
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.4
+signing_key: 
+specification_version: 4
+summary: Embedded tests in Markdown documents
+test_files: []