asciidoctor-doctest 1.5.0 → 1.5.1

data/features/step_definitions/doctest_steps.rb

@@ -0,0 +1,5 @@
+require 'fileutils'
+
+Given 'I do have a template-based HTML backend with DocTest' do
+  FileUtils.cp_r Dir.glob("#{FIXTURES_DIR}/html-slim/**"), TEMP_DIR
+end

data/features/support/env.rb

@@ -0,0 +1,21 @@
+require 'aruba'
+require 'aruba/cucumber'
+require 'asciidoctor/doctest'
+require 'fileutils'
+require 'rspec/expectations'
+
+Dir["#{__dir__}/../step_definitions/**/*.rb"].each { |file| require file }
+
+PROJECT_DIR  = File.expand_path('../../', __dir__)
+FIXTURES_DIR = File.expand_path('../fixtures', __dir__)
+TEMP_DIR     = File.join(PROJECT_DIR, 'tmp/aruba')
+
+Before do
+  FileUtils.mkdir_p TEMP_DIR
+  # overwrite Aruba's default temp directory location
+  @dirs = [TEMP_DIR]
+end
+
+After do
+  FileUtils.rm_rf(TEMP_DIR) if Dir.exist? TEMP_DIR
+end

data/features/test_html.feature

@@ -0,0 +1,59 @@
+Feature: Testing a custom HTML backend
+
+  Background:
+    Given I do have a template-based HTML backend with DocTest
+
+  Scenario: Some examples do not match the expected output
+    When I run `bundle exec rake test`
+    Then the output should contain:
+      """
+        1) Failure:
+      TestHtml :: block_quote : with_attribution:
+      Failing example..
+
+           <blockquote>A person who never made a mistake
+             <em>never</em>
+             tried anything new.</blockquote>
+      E    <span>Albert Einstein</span>
+      A    <div class="attribution">— Albert Einstein</div>
+         </div>
+      """
+    And the output should contain:
+      """
+        2) Failure:
+      TestHtml :: document : title_with_author:
+      This example should fail..
+
+         <div id="header">
+           <h1>The Dangerous and Thrilling Documentation Chronicles</h1>
+      E    <div id="author">Kismet Rainbow Chameleon</div>
+      A    <div class="details"><span id="author">Kismet Rainbow Chameleon</span></div>
+         </div>
+      """
+    And the output should contain:
+      """
+      5 runs, 3 assertions, 2 failures, 0 errors, 2 skips
+      """
+
+  Scenario: A necessary template is missing and fallback to the built-in converter is disabled
+    When I remove the file "templates/inline_quoted.html.slim"
+    And I run `bundle exec rake test`
+    Then the output should contain:
+      """
+      Could not find a custom template to handle template_name: inline_quoted
+      """
+    And the output should contain:
+      """
+        1) Failure:
+      TestHtml :: block_quote : with_attribution:
+      Failing example..
+
+         <div class="quoteblock">
+      E    <blockquote>A person who never made a mistake
+      E      <em>never</em>
+      E      tried anything new.</blockquote>
+      E    <span>Albert Einstein</span>
+      A    <blockquote>A person who never made a mistake --TEMPLATE NOT FOUND-- tried anything new.</blockquote>
+      A    <div class="attribution">— Albert Einstein</div>
+         </div>
+      """

data/lib/asciidoctor/doctest/asciidoc_renderer.rb

@@ -5,7 +5,7 @@ require 'asciidoctor/converter/template'
 module Asciidoctor
   module DocTest
     ##
-    # This class is basically a wrapper for +Asciidoctor.render+ that allows to
+    # This class is basically a wrapper for +Asciidoctor.convert+ that allows to
     # preset and validate some common parameters.
     class AsciidocRenderer
 
@@ -33,45 +33,50 @@ module Asciidoctor
       # @raise [ArgumentError] if some path from the +template_dirs+ doesn't
       #        exist or is not a directory.
       #
-      def initialize(backend_name: nil, converter: nil, template_dirs: [],
+      def initialize(backend_name: '', converter: nil, template_dirs: [],
                      templates_fallback: false)
 
         @backend_name = backend_name.freeze
         @converter = converter
-        @converter ||= TemplateConverterAdapter unless template_dirs.empty? || templates_fallback
+        @converter ||= NoFallbackTemplateConverter unless template_dirs.empty? || templates_fallback
 
         template_dirs = Array.wrap(template_dirs).freeze
-
-        unless template_dirs.all? { |path| Dir.exist? path }
-          fail ArgumentError, "Templates directory '#{path}' doesn't exist!"
+        template_dirs.each do |path|
+          fail ArgumentError, "Templates directory '#{path}' doesn't exist!" unless Dir.exist? path
         end
         @template_dirs = template_dirs unless template_dirs.empty?
       end
 
       ##
-      # Renders the given +text+ in AsciiDoc syntax with Asciidoctor using the
-      # tested backend.
+      # Converts the given +text+ into AsciiDoc syntax with Asciidoctor using
+      # the tested backend.
       #
       # @param text [#to_s] the input text in AsciiDoc syntax.
       # @param opts [Hash] options to pass to Asciidoctor.
-      # @return [String] rendered input.
+      # @return [String] converted input.
       #
-      def render(text, opts = {})
-        renderer_opts = {
+      def convert(text, opts = {})
+        converter_opts = {
           safe: :safe,
           backend: backend_name,
           converter: converter,
           template_dirs: template_dirs
         }.merge(opts)
 
-        Asciidoctor.render(text.to_s, renderer_opts)
+        Asciidoctor.convert(text.to_s, converter_opts)
       end
+
+      # Alias for backward compatibility.
+      alias_method :render, :convert
     end
 
     ##
     # @private
-    # Adapter for +Asciidoctor::Converter::TemplateConverter+.
-    class TemplateConverterAdapter < SimpleDelegator
+    # 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.

data/lib/asciidoctor/doctest/base_example.rb

@@ -102,7 +102,7 @@ module Asciidoctor
 
       ##
       # @note The default implementation returns content as-is; subclasses
-      # should override this method.
+      #   should override this method.
       #
       # @return [String] copy of the content in a form that is suitable for
       #         semantic comparison with another content.
@@ -112,15 +112,21 @@ module Asciidoctor
       end
 
       ##
-      # @note The default implementation returns content as-is; subclasses
-      # should override this method.
+      # @note (see #content_normalized)
       #
-      # @return [String] a human-readable (formatted) version of the content.
+      # @return [String] copy of the content in a human-readable (formatted)
+      #         shape for pretty print.
       #
-      def to_s
+      def content_pretty
         content.dup
       end
 
+      ##
+      # @return (see #content_pretty)
+      def to_s
+        content_pretty
+      end
+
       ##
       # @param other the object to compare with.
       # @return [Boolean] +true+ if +self+ and +other+ equals in attributes

data/lib/asciidoctor/doctest/base_examples_suite.rb

@@ -62,7 +62,7 @@ module Asciidoctor
       # @abstract
       # @param example [BaseExample] the input example to convert.
       # @param opts [Hash] the options to pass to a new example.
-      # @param renderer [#render]
+      # @param renderer [#convert]
       # @return [BaseExample]
       # :nocov:
       def convert_example(example, opts, renderer)

data/lib/asciidoctor/doctest/generator.rb

@@ -17,7 +17,7 @@ module Asciidoctor
       #        {BaseExamplesSuite} subclass to read the reference input
       #        examples.
       #
-      # @param renderer [#render]
+      # @param renderer [#convert]
       #
       # @param pattern [String] glob-like pattern to select examples to
       #        (re)generate (see {BaseExample#name_match?}).
@@ -42,6 +42,8 @@ module Asciidoctor
             log["Unknown %s, doesn't exist in input examples!"]
           else
             rendered = output_suite.convert_example(input, output.opts, renderer)
+            rendered.desc = output.desc
+
             if output.empty?
               log['Generating %s', :magenta]
               updated << rendered

data/lib/asciidoctor/doctest/generator_task.rb

@@ -39,24 +39,27 @@ module Asciidoctor
       #   (default: *:*).
       attr_accessor :pattern
 
-      # @return [Hash] options for Asciidoctor renderer.
+      # @return [Hash] options for Asciidoctor converter.
       # @see AsciidocRenderer#initialize
-      attr_accessor :renderer_opts
+      attr_accessor :converter_opts
 
       # @return [String] title of the task's description.
       attr_accessor :title
 
+      # Alias for backward compatibility.
+      alias_method :renderer_opts, :converter_opts
+
 
       ##
       # @param name [#to_sym] name of the task.
       # @yield The block to configure this task.
       def initialize(name)
         @name = name
-        @examples_path = DocTest.examples_path
+        @examples_path = DocTest.examples_path.dup
         @force = false
         @input_suite = nil
         @output_suite = nil
-        @renderer_opts = {}
+        @converter_opts = {}
         @pattern = '*:*'
         @title = "Generate testing examples #{pattern}#{" for #{name}" if name != :generate}."
 
@@ -68,7 +71,7 @@ module Asciidoctor
         end
 
         @input_suite ||= Asciidoc::ExamplesSuite.new(examples_path: @examples_path)
-        @renderer ||= AsciidocRenderer.new(renderer_opts)
+        @renderer ||= AsciidocRenderer.new(converter_opts)
 
         define
       end

data/lib/asciidoctor/doctest/html/example.rb

@@ -13,7 +13,7 @@ module Asciidoctor::DocTest
         Nokogiri::HTML.fragment(content).normalize!.to_s
       end
 
-      def to_s
+      def content_pretty
         HtmlBeautifier.beautify content_normalized
       end
     end

data/lib/asciidoctor/doctest/html/examples_suite.rb

@@ -81,7 +81,7 @@ module Asciidoctor::DocTest
       def convert_example(example, opts, renderer)
         header_footer = !!opts[:header_footer] || example.name.start_with?('document')
 
-        html = renderer.render(example.to_s, header_footer: header_footer)
+        html = renderer.convert(example.content, header_footer: header_footer)
         html = parse_html(html, !header_footer)
 
         # When asserting inline examples, ignore paragraph "wrapper".
@@ -98,7 +98,7 @@ module Asciidoctor::DocTest
 
         html.normalize!
 
-        create_example example.name, content: html.to_s, opts: opts
+        create_example example.name, content: HtmlBeautifier.beautify(html), opts: opts
       end
 
       private

data/lib/asciidoctor/doctest/minitest_diffy.rb

@@ -66,7 +66,7 @@ module Diffy
           padding + line.chomp
         end
       end
-      "\n" + ary.join("\n")
+      "\n" + ary.compact.join("\n")
     end
   end
 end

data/lib/asciidoctor/doctest/test.rb

@@ -14,10 +14,13 @@ module Asciidoctor
 
       ##
       # (see AsciidocRenderer#initialize)
-      def self.renderer_opts(**kwargs)
+      def self.converter_opts(**kwargs)
         @renderer = AsciidocRenderer.new(**kwargs)
       end
 
+      # Alias for backward compatibility.
+      alias_class_method :renderer_opts, :converter_opts
+
       ##
       # Generates tests for all the input/output examples.
       # When some output example is missing, it's reported as skipped test.

data/lib/asciidoctor/doctest/version.rb

@@ -1,5 +1,5 @@
 module Asciidoctor
   module DocTest
-    VERSION = '1.5.0'
+    VERSION = '1.5.1'
   end
 end

data/spec/asciidoc_renderer_spec.rb

@@ -0,0 +1,98 @@
+require 'fileutils'
+
+describe DocTest::AsciidocRenderer do
+
+  subject { described_class }
+
+  it { is_expected.to have_method :convert, :render }
+
+
+  describe '#initialize' do
+
+    context 'with defaults' do
+      subject { described_class.new }
+      it { is_expected.to have_attributes backend_name: '', converter: nil, template_dirs: nil }
+    end
+
+    context 'with backend_name' do
+      subject { described_class.new(backend_name: 'html5') }
+      it { is_expected.to have_attributes backend_name: 'html5' }
+    end
+
+    context 'with template_dirs' do
+      include FakeFS::SpecHelpers
+
+      subject { described_class.new(template_dirs: template_dirs) }
+      let(:template_dirs) { ['/tmp/html5'] }
+
+      before { FileUtils.mkpath template_dirs[0] }
+
+      context 'that exists' do
+        it do
+          is_expected.to have_attributes(
+            template_dirs: template_dirs,
+            converter: DocTest::NoFallbackTemplateConverter
+          )
+        end
+
+        context 'and templates_fallback = true' do
+          subject { described_class.new(template_dirs: template_dirs, templates_fallback: true) }
+          it { is_expected.to have_attributes template_dirs: template_dirs, converter: nil }
+        end
+
+        context 'and custom converter' do
+          subject { described_class.new(template_dirs: template_dirs, converter: converter) }
+          let(:converter) { Asciidoctor::Converter::TemplateConverter }
+
+          it { is_expected.to have_attributes template_dirs: template_dirs, converter: converter }
+        end
+      end
+
+      context "that doesn't exist" do
+        let(:template_dirs) { ['/tmp/html5', '/tmp/revealjs'] }
+
+        it { expect { subject }.to raise_error ArgumentError }
+      end
+    end
+  end
+end
+
+
+describe DocTest::NoFallbackTemplateConverter do
+
+  subject(:delegator) { described_class.new('html5', template_dirs: ['/tmp/html5']) }
+
+  describe '#convert' do
+
+    let(:converter) { delegator.__getobj__ }
+    let(:node) { double('Node', node_name: 'block_foo') }
+
+    before do
+      expect(converter).to receive(:handles?).with('block_foo').and_return(handles)
+    end
+
+    context 'when template is not found' do
+      let(:handles) { false }
+
+      it 'returns a not found marker instead of converted node' do
+        expect(converter).to_not receive(:convert)
+        expect(delegator.convert node).to eq described_class::NOT_FOUND_MARKER
+      end
+
+      it 'prints a warning on stderr' do
+        expect { delegator.convert node }.to output(/Could not find a custom template/i).to_stderr
+      end
+    end
+
+    context 'when template is found' do
+      let(:handles) { true }
+
+      it 'delegates to the original #convert and returns result' do
+        expect(converter).to receive(:convert)
+          .with(node, 'block_foo', {}).and_return('allons-y!')
+
+        expect(delegator.convert node).to eq 'allons-y!'
+      end
+    end
+  end
+end

data/spec/base_example_spec.rb

@@ -2,7 +2,10 @@ describe DocTest::BaseExample do
 
   subject(:o) { described_class.new ['foo', 'bar'] }
 
-  it { is_expected.to respond_to :group_name, :local_name, :content, :desc, :opts }
+  it do
+    is_expected.to respond_to :group_name, :local_name, :desc, :opts, :content,
+                              :content_normalized, :content_pretty
+  end
 
   describe '#name' do
 

data/spec/html/examples_suite_spec.rb

@@ -155,7 +155,7 @@ describe DocTest::HTML::ExamplesSuite do
     let(:input) { create_example 's:dummy', content: '*chunky* bacon' }
     let(:opts) { {dummy: 'value'} }
     let(:renderer) { double 'AsciidocRenderer' }
-    let(:renderer_opts) { {header_footer: false} }
+    let(:converter_opts) { {header_footer: false} }
 
     subject(:result) { suite.convert_example input, opts, renderer }
 
@@ -175,8 +175,8 @@ describe DocTest::HTML::ExamplesSuite do
     end
 
     before do
-      expect(renderer).to receive(:render)
-        .with(input.content, renderer_opts).and_return(rendered)
+      expect(renderer).to receive(:convert)
+        .with(input.content, converter_opts).and_return(rendered)
     end
 
     it 'returns instance of HTML::Example' do
@@ -218,7 +218,7 @@ describe DocTest::HTML::ExamplesSuite do
 
     context 'with example named /^document.*/' do
       let(:input) { create_example 'document:dummy', content: '*chunky* bacon' }
-      let(:renderer_opts) { {header_footer: true} }
+      let(:converter_opts) { {header_footer: true} }
 
       it 'renders content with :header_footer => true' do
         suite.convert_example input, {}, renderer
@@ -230,7 +230,7 @@ describe DocTest::HTML::ExamplesSuite do
       let(:rendered) { '<p><b>chunky</b> bacon</p>' }
 
       it 'returns content without top-level <p> tags' do
-        expect(result.content).to eq '<b>chunky</b> bacon'
+        expect(result.content.gsub(/\s+/, ' ')).to eq '<b>chunky</b> bacon'
       end
 
       it 'does not add implicit include into returned example' do