asciidoctor-doctest 1.5.2.0 → 2.0.0.beta.1

data/lib/asciidoctor/doctest/io/xml.rb

@@ -0,0 +1,69 @@
+require 'asciidoctor/doctest/io/base'
+require 'corefines'
+
+using Corefines::Object[:blank?, :presence]
+using Corefines::String::concat!
+
+module Asciidoctor::DocTest
+  module IO
+    ##
+    # Subclass of {IO::Base} for XML-based backends.
+    #
+    # @example Format of the example's header
+    #   <!-- .example-name
+    #     Any text that is not the example's name or an option is considered
+    #     as a description.
+    #     :option_1: value 1
+    #     :option_2: value 1
+    #     :option_2: value 2
+    #     :boolean_option:
+    #   -->
+    #   <p>The example's content in <strong>HTML</strong>.</p>
+    #
+    #   <div class="note">The trailing new line (below this) will be removed.</div>
+    #
+    class XML < Base
+
+      def parse(input, group_name)
+        examples = []
+        current = create_example(nil)
+        in_comment = false
+
+        input.each_line do |line|
+          line.chomp!
+          if line =~ /^<!--\s*\.([^ \n]+)/
+            name = $1
+            current.content.chomp!
+            examples << (current = create_example([group_name, name]))
+            in_comment = true
+          elsif in_comment
+            if line =~ /^\s*:([^:]+):(.*)/
+              current[$1.to_sym] = $2.blank? ? true : $2.strip
+            else
+              desc = line.rstrip.chomp('-->').strip
+              (current.desc ||= '').concat!(desc, "\n") unless desc.empty?
+            end
+          else
+            current.content.concat!(line, "\n")
+          end
+          in_comment &= !line.end_with?('-->')
+        end
+
+        examples
+      end
+
+      def serialize(examples)
+        Array(examples).map { |exmpl|
+          header = [
+            ".#{exmpl.local_name}",
+            exmpl.desc.presence,
+            *format_options(exmpl.opts)
+          ].compact
+
+          header_str = header.one? ? (header.first + ' ') : (header.join("\n") + "\n")
+          [ "<!-- #{header_str}-->", exmpl.content.presence ].compact.join("\n") + "\n"
+        }.join("\n")
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/no_fallback_template_converter.rb

@@ -0,0 +1,42 @@
+require 'asciidoctor/converter/template'
+require 'delegate'
+
+module Asciidoctor
+  module DocTest
+    ##
+    # @private
+    # TemplateConverter that doesn't fallback to a built-in converter when
+    # no template for a node is found.
+    #
+    class NoFallbackTemplateConverter < SimpleDelegator
+      # NOTE: It didn't work with subclass of TemplateConverter instead of
+      # delegator, I have no idea why.
+
+      # Placeholder to be written in a rendered output in place of the node's
+      # content that cannot be rendered due to missing template.
+      NOT_FOUND_MARKER = '--TEMPLATE NOT FOUND--'
+
+      def initialize(backend, opts = {})
+        super Asciidoctor::Converter::TemplateConverter.new(backend, opts[:template_dirs], opts)
+      end
+
+      ##
+      # Delegates to the template converter and returns results, or prints
+      # warning and returns {NOT_FOUND_MARKER} if there is no template to
+      # handle the specified +template_name+.
+      def convert(node, template_name = nil, opts = {})
+        template_name ||= node.node_name
+
+        if handles? template_name
+          super
+        else
+          warn "Could not find a custom template to handle template_name: #{template_name}"
+          NOT_FOUND_MARKER
+        end
+      end
+
+      # Alias for backward compatibility.
+      alias_method :convert_with_options, :convert
+    end
+  end
+end

data/lib/asciidoctor/doctest/rake_tasks.rb

@@ -0,0 +1,229 @@
+require 'asciidoctor/doctest/asciidoc_converter'
+require 'asciidoctor/doctest/generator'
+require 'asciidoctor/doctest/test_reporter'
+require 'asciidoctor/doctest/tester'
+require 'asciidoctor/doctest/io/asciidoc'
+require 'corefines'
+require 'rake/tasklib'
+
+using Corefines::String[:to_b, :unindent]
+
+module Asciidoctor
+  module DocTest
+    ##
+    # Rake tasks for testing and generating output examples.
+    class RakeTasks < Rake::TaskLib
+
+      # Genetates a description of a given task when
+      # {#test_description} is not set.
+      DEFAULT_TEST_DESC = ->(task) do
+        <<-EOS.unindent
+          Run integration tests for the #{task.subject}.
+
+          Options (env. variables):
+            PATTERN   glob pattern to select examples to test. [default: #{task.pattern}]
+                      E.g. *:*, block_toc:basic, block*:*, *list:with*, ...
+            VERBOSE   prints out more details [default: #{task.verbose? ? 'yes' : 'no'}]
+        EOS
+      end
+
+      # Genetates a description of a given task when
+      # {#generate_description} is not set.
+      DEFAULT_GENERATE_DESC = ->(task) do
+        <<-EOS.unindent
+          Generate test examples for the #{task.subject}.
+
+          Options (env. variables):
+            PATTERN   glob pattern to select examples to (re)generate. [default: #{task.pattern}]
+                      E.g. *:*, block_toc:basic, block*:*, *list:with*, ...
+            FORCE     overwrite existing examples (yes/no)? [default: #{task.force? ? 'yes' : 'no'}]
+        EOS
+      end
+
+      private_constant :DEFAULT_TEST_DESC, :DEFAULT_GENERATE_DESC
+
+      # @return [#to_sym] namespace for the +:test+ and +:generate+ tasks. The
+      #         +:test+ task will be set as the default task of this namespace.
+      attr_accessor :tasks_namespace
+
+      # @return [#to_s, #call] description of the test task.
+      attr_accessor :test_description
+
+      # @return [#to_s, #call] description of the generator task.
+      attr_accessor :generate_description
+
+      attr_accessor :converter
+
+      # @return [Hash] options for the Asciidoctor converter.
+      # @see AsciidocConverter#initialize
+      attr_accessor :converter_opts
+
+      # @return [String] glob pattern to select examples to test or
+      #   (re)generate. May be overriden with +PATTERN+ variable on the command
+      #   line (default: +\*:*+).
+      attr_accessor :pattern
+
+      # @return [Minitest::Reporter] an instance of +Reporter+ subclass to
+      #   report test results.
+      # @note Used only in the test task.
+      attr_accessor :test_reporter
+
+      # @return [Boolean] whether to print out more details (default: false).
+      #   May be overriden with +VERBOSE+ variable on the command line.
+      # @note Used only in the test task and with the default {#test_reporter}.
+      attr_accessor :verbose
+
+      # @return [Boolean] whether to rewrite an already existing testing
+      #   example. May be overriden with +FORCE+ variable on the command line
+      #   (default: false).
+      # @note Used only in the generator task.
+      attr_accessor :force
+
+
+      ##
+      # Defines and configures +:test+ and +:generate+ rake tasks under the
+      # specified namespace.
+      #
+      # @param tasks_namespace [#to_sym] namespace for the +:test+ and
+      #        +:generate+ tasks.
+      # @yield [self] Gives self to the block.
+      #
+      def initialize(tasks_namespace = :doctest)
+        @tasks_namespace = tasks_namespace
+        @test_description = DEFAULT_TEST_DESC
+        @generate_description = DEFAULT_GENERATE_DESC
+        @input_examples = IO.create(:asciidoc)
+        @converter_opts = {}
+        @force = false
+        @pattern = '*:*'
+
+        yield self
+
+        fail ArgumentError, 'The output_examples must be provided!' unless @output_examples
+
+        @converter = converter.new(converter_opts) if converter.is_a? Class
+        @test_reporter ||= TestReporter.new($stdout, verbose: verbose?,
+          title: "Running DocTest for the #{subject}.")
+
+        namespace(tasks_namespace) do
+          define_test_task!
+          define_generate_task!
+        end
+
+        desc "Alias for #{tasks_namespace}:test."
+        task tasks_namespace => "#{tasks_namespace}:test"
+      end
+
+      ##
+      # Specifies a reader for the input examples. Defaults to +:asciidoc+ with
+      # the built-in reference examples.
+      #
+      # @overload input_examples(format, opts)
+      #   @param format [Symbol, String]
+      #   @param opts [Hash]
+      #   @option opts :path see {#output_examples}
+      #   @option opts :file_ext see {#output_examples}
+      #
+      # @overload input_examples(io)
+      #   @param io [IO::Base]
+      #
+      def input_examples(*args)
+        @input_examples = create_io(*args)
+      end
+
+      ##
+      # Specifies a reader/writer for the output examples (required).
+      #
+      # @overload output_examples(format, opts)
+      #   @param format [Symbol, String]
+      #   @param opts [Hash]
+      #   @option opts :path [String, Array<String>] path of the directory
+      #           (or multiple directories) where to look for the examples.
+      #           Default is {DocTest.examples_path}.
+      #   @option opts :file_ext [String] the filename extension (e.g. +.adoc+)
+      #           of the examples files. Default value depends on the
+      #           specified format.
+      #
+      # @overload output_examples(io)
+      #   @param io [IO::Base]
+      #
+      def output_examples(*args)
+        @output_examples = create_io(*args)
+      end
+
+      def pattern
+        ENV['PATTERN'] || @pattern
+      end
+
+      # (see #force)
+      def force?
+        ENV.fetch('FORCE', @force.to_s).to_b
+      end
+
+      alias_method :force, :force?
+
+      # (see #verbose)
+      def verbose?
+        ENV.fetch('VERBOSE', @verbose.to_s).to_b
+      end
+
+      alias_method :verbose, :verbose?
+
+      # @private
+      def subject
+        {
+          converter: 'converter',
+          template_dirs: 'templates',
+          backend_name: 'backend'
+        }
+        .each do |key, desc|
+          val = converter_opts[key]
+          return "#{desc}: #{val}" if val
+        end
+      end
+
+      protected
+
+      def run_tests!
+        tester = Tester.new(@input_examples, @output_examples, @converter, @test_reporter)
+        fail unless tester.run_tests(pattern: pattern)
+      end
+
+      ##
+      # @param desc [#to_s, #call] description of the next rake task. When the
+      #        given object responds to +#call+, then it's invoked with +self+
+      #        as a parameter. The result is expected to be a +String+.
+      def desc(desc)
+        super desc.respond_to?(:call) ? desc.call(self) : desc.to_s
+      end
+
+      private
+
+      def define_test_task!
+        desc test_description
+        task :test do
+          run_tests!
+        end
+      end
+
+      def define_generate_task!
+        desc generate_description
+        task :generate do
+          puts "Generating test examples #{pattern} in #{@output_examples.path.first}"
+
+          Generator.new(@input_examples, @output_examples, @converter)
+                   .generate! pattern: pattern, rewrite: force?
+        end
+      end
+
+      def create_io(*args)
+        case args.first
+        when Symbol, String
+          IO.create(*args)
+        else
+          args.first
+        end
+      end
+    end
+  end
+end

data/lib/asciidoctor/doctest/test_reporter.rb

@@ -0,0 +1,110 @@
+# coding: utf-8
+require 'minitest'
+
+using Corefines::String[:color, :indent]
+
+module Asciidoctor
+  module DocTest
+    ##
+    # This class is responsible for printing a formatted output of the test run.
+    class TestReporter < Minitest::StatisticsReporter
+
+      RESULT_COLOR  = { :'.' => :green, E: :yellow, F: :red, S: :cyan }
+      RESULT_SYMBOL = { :'.' => '✓', E: '⚠', F: '✗', S: '∅' }
+
+      private_constant :RESULT_COLOR, :RESULT_SYMBOL
+
+      ##
+      # @note Overrides method from +Minitest::StatisticsReporter+.
+      def start
+        super
+        io.puts "\n" + (options[:title] || 'Running DocTest:') + "\n\n"
+      end
+
+      ##
+      # @param result [Minitest::Test] a single test result.
+      # @note Overrides method from +Minitest::StatisticsReporter+.
+      def record(result)
+        result.extend ResultExt
+
+        if verbose?
+          io.puts [ result.symbol.color(result.color), result.name ].join('  ')
+        else
+          io.print result.result_code.color(result.color)
+        end
+
+        super
+      end
+
+      ##
+      # Outputs the summary of the run.
+      # @note Overrides method from +Minitest::StatisticsReporter+.
+      def report
+        super
+        io.puts unless verbose? # finish the dots
+        io.puts ['', aggregated_results, summary, ''].compact.join("\n")
+      end
+
+      # @private
+      def aggregated_results
+        filtered_results = verbose? ? results : results.reject(&:skipped?)
+
+        return nil if filtered_results.empty?
+
+        str = "Aggregated results:\n"
+        filtered_results.each do |res|
+          str << "\n#{res.symbol}  #{res.failure.result_label}: ".color(res.color)
+          str << "#{res.name}\n#{res.failure.message.indent(3)}\n\n"
+        end
+
+        str
+      end
+
+      # @private
+      def summary
+        str = "#{count} examples ("
+        str << [
+          ("#{passes} passed".color(:green) if passes > 0),
+          ("#{failures} failed".color(:red) if failures > 0),
+          ("#{errors} errored".color(:yellow) if errors > 0),
+          ("#{skips} skipped".color(:cyan) if skips > 0)
+        ].compact.join(', ') + ")\n\n"
+
+        str << "Finished in %.3f s.\n" % total_time
+
+        if results.any?(&:skipped?) && !verbose?
+          str << "\nYou have skipped tests. Run with VERBOSE=yes for details.\n"
+        end
+
+        str
+      end
+
+      ##
+      # @return [Integer] number of passed tests (examples).
+      def passes
+        count - failures - errors - skips
+      end
+
+      ##
+      # @return [Boolean] whether verbose mode is enabled.
+      def verbose?
+        !!options[:verbose]
+      end
+
+
+      ##
+      # @private
+      # Module to be included into +Minitest::Test+.
+      module ResultExt
+
+        def symbol
+          RESULT_SYMBOL[result_code.to_sym]
+        end
+
+        def color
+          RESULT_COLOR[result_code.to_sym]
+        end
+      end
+    end
+  end
+end