asciidoctor-doctest 1.5.2.0 → 2.0.0.beta.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 17448118b205d1f1a39fb2ccde52df38b512899e
-  data.tar.gz: 22caa40c2925809f7931347b267639676cc9c88a
+  metadata.gz: adc5657c9e7bcd1f4dfda82cdbce7789414b7129
+  data.tar.gz: 1549da48c04eb0b58148e7e0e37b81483274d366
 SHA512:
-  metadata.gz: 098697a3599f989cf9b39a463182467c06ef6c2fb8dfeb9beca1510967899ad8a406368fcc392cdf16e7eef287b0d2deda3097f3692bb18207326891716fb41e
-  data.tar.gz: 119b67494d4af4d29eb09ddb22e1a2f189290b5bc3e095bd74a40469109c16317754d30111178e7a4b1a10eb677d9f283b9887b7b5cb7ac7a4d33ed75837c6ae
+  metadata.gz: 412eb45db40fe2eec88e7a8507be9531a855ecb8efe898bc22f4fed70a12e7d3b4a044110a39fdd5706a9a647b9371e86c301edaa8042b9d3e0d112186f17316
+  data.tar.gz: a49cc812d65eade759965016fb5a816726af906b18f0367f90adde476c4f373aa0ab10ea4c1f9c00086c9caa51525f342438870fe37ddefffbdee5f6b8ea0170

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright 2014-2015 Jakub Jirutka <jakub@jirutka.cz> and the Asciidoctor Project.
+Copyright 2014-2017 Jakub Jirutka <jakub@jirutka.cz> and the Asciidoctor Project.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.adoc

@@ -1,11 +1,6 @@
 = Asciidoctor::DocTest
 Jakub Jirutka <https://github.com/jirutka[@jirutka]>
-:page-layout: base
-:idprefix:
-ifdef::env-github[:idprefix: user-content-]
-:idseparator: -
 :source-language: ruby
-:language: {source-language}
 // custom
 :gem-name: asciidoctor-doctest
 :gh-name: asciidoctor/{gem-name}
@@ -55,83 +50,62 @@ mkdir -p test/examples/asciidoc
 
 . Add development dependency on `asciidoctor-doctest` to your gemspec:
 +
-[source]
-s.add_development_dependency 'asciidoctor-doctest', '~> 1.5.2'
+[source, ruby]
+s.add_development_dependency 'asciidoctor-doctest', '~> 2.0.0'
 +
 or Gemfile if you’re not distributing the backend as a gem:
 +
-[source]
-gem 'asciidoctor-doctest', '~> 1.5.2'
+[source, ruby]
+gem 'asciidoctor-doctest', '~> 2.0.0'
 +
 and run `bundle install`.
 
-. Create or edit `test/test_helper.rb`; require test dependencies and setup `examples_path`:
+. Create or edit `Rakefile` and configure DocTest tasks:
 +
-[source]
+[source, ruby]
 ----
 require 'asciidoctor/doctest'
-require 'minitest/autorun'
-
-# used to colorize output
-require 'minitest/rg'
-
-# needed if you're testing templates-based backend
+require 'thread_safe'
 require 'tilt'
 
-# extra input examples (optional)
-DocTest.examples_path.unshift 'test/examples/asciidoc'
-
-# output examples
-DocTest.examples_path.unshift 'test/examples/shiny'
-----
-
-. Create test file `test/templates_test.rb` and extend class link:{src-base}/test.rb[DocTest::Test]. Specify `converter_opts` and then call `generate_tests!` macro with a specific subclass of `BaseExamplesSuite`:
-+
-[source]
-----
-require 'test_helper'
-
-class TestTemplates < DocTest::Test
-  converter_opts template_dirs: 'data/templates'
-  generate_tests! DocTest::HTML::ExamplesSuite
+DocTest::RakeTasks.new(:doctest) do |t|
+  t.output_suite = DocTest::HTML::ExamplesSuite
+  t.output_suite_opts = {
+    examples_path: 'test/examples/shiny'
+  }
+  # add extra input examples (optional)
+  t.input_suite_opts = {
+    examples_path: [ *DocTest.examples_path, 'test/examples/asciidoc' ]
+  }
+  t.converter_opts = {
+    template_dirs: 'data/templates'
+  }
 end
 ----
 
-. Create or edit `Rakefile`; add tasks to run tests and optionally a generator of output examples:
+. Check if rake loads the DocTest tasks _doctest_, _doctest:test_ and _doctest:generate_.
 +
-[source]
-----
-require 'asciidoctor/doctest'
-require 'rake/testtask'
-require 'thread_safe'
-require 'tilt'
+[source, sh]
+bundle exec rake -D
 
-Rake::TestTask.new(:test) do |task|
-  task.description = 'Run tests for templates'
-  task.pattern = 'test/templates_test.rb'
-  task.libs << 'test'
-end
 
-DocTest::GeneratorTask.new(:generate) do |task|
-  task.output_suite = DocTest::HTML::ExamplesSuite.new(examples_path: 'test/examples/shiny')
-  task.converter_opts[:template_dirs] = 'data/templates'
-  #
-  # add extra input examples (optional)
-  task.examples_path.unshift 'test/examples/asciidoc'
-end
+== Run tests
 
-# When no task specified, run test.
-task :default => :test
-----
+Assume that you have defined the Rake tasks in the default namespace _doctest_ (see above).
+Then you can simply run:
 
+[source, sh]
+bundle exec rake doctest:test
 
-== Run tests
+To test only specific examples, use `PATTERN` with glob-like expression:
 
-Assume that you have defined the test Rake task named `:test` (see above).
-Then you can simply run:
+[source, sh]
+bundle exec rake doctest:test PATTERN='block_*:*'
+
+For verbose output, use `VERBOSE=yes`:
 
 [source, sh]
-bundle exec rake test
+bundle exec rake doctest:test VERBOSE=yes
 
 image::doc/img/failing-test-term.gif[Failing test in term, align="center"]
 
@@ -225,11 +199,17 @@ NOTE: The trailing new line (below this) will be removed.
 HtmlTest assumes that paragraphs are enclosed in `<p></p>` tags and implicitly sets the _include_ option to `./p/node()` for `inline_*:*` examples (if _include_ is not already set).
 If it’s not your case, then you must overwrite it:
 
-[source]
+[source, ruby]
 ----
-class TestShiny < DocTest::Test
-  converter_opts template_dirs: 'data/templates'
-  generate_tests! DocTest::HTML::ExamplesSuite.new(paragraph_xpath: './div/p/node()')
+DocTest::RakeTasks.new(:doctest) do |t|
+  t.output_suite = DocTest::HTML::ExamplesSuite
+  t.output_suite_opts = {
+    examples_path: 'test/examples/shiny',
+    paragraph_xpath: './div/p/node()'  //<1>
+  }
+  t.converter_opts = {
+    template_dirs: 'data/templates'
+  }
 end
 ----
 
@@ -290,27 +270,27 @@ Therefore DocTest provides a generator.
 When you have at least partially working Asciidoctor _backend_ (converter or a set of templates), you can pass the input examples through it and generate your output examples.
 Then you should verify them and modify if needed.
 
-Assume that you have defined the generator Rake task named `:generator` (see <<setup-doctest>>).
+Assume that you have defined the Rake tasks in the default namespace _doctest_ (see <<setup-doctest>>).
 
 Now you can generate output examples from all the input examples (those with `.adoc` extension) found on the examples_path that doesn’t already exist (i.e. it doesn’t rewrite existing):
 
 [source, sh]
-bundle exec rake generate
+bundle exec rake doctest:generate
 
 Same as previous, but rewrite existing tested examples:
 
 [source, sh]
-bundle exec rake generate FORCE=yes
+bundle exec rake doctest:generate FORCE=yes
 
 Generate just examples for `block_ulist` node (i.e. all examples in `block_ulist.adoc` file(s) found on the examples_path) that doesn’t exist yet:
 
 [source, sh]
-bundle exec rake generate PATTERN='block_ulist:*'
+bundle exec rake doctest:generate PATTERN='block_ulist:*'
 
 (Re)generate examples which name starts with `basic` for all _block_ nodes (i.e. files that starts with `block_`):
 
 [source, sh]
-bundle exec rake generate PATTERN='block_*:basic*' FORCE=yes
+bundle exec rake doctest:generate PATTERN='block_*:basic*' FORCE=yes
 
 
 == How to extend it

data/features/fixtures/html-slim/Rakefile

@@ -1,15 +1,9 @@
 require 'asciidoctor/doctest'
-require 'rake/testtask'
 require 'tilt'
 
-DocTest::GeneratorTask.new(:generate) do |task|
-  task.output_suite = DocTest::HTML::ExamplesSuite.new(examples_path: 'examples/html')
-  task.examples_path = 'examples/asciidoc'
-  task.converter_opts[:template_dirs] = 'templates'
-end
-
-Rake::TestTask.new(:test) do |task|
-  task.description = 'Run tests for custom HTML backend'
-  task.pattern = 'test/html_test.rb'
-  task.libs << 'test'
+DocTest::RakeTasks.new do |t|
+  t.output_examples :html, path: 'examples/html'
+  t.input_examples :asciidoc, path: 'examples/asciidoc'
+  t.converter = DocTest::HTML::Converter
+  t.converter_opts = { template_dirs: 'templates' }
 end

data/features/generator_html.feature

@@ -4,10 +4,10 @@ Feature: Generating output examples for a custom HTML backend
     Given I do have a template-based HTML backend with DocTest
 
   Scenario: Generate missing output examples
-    When I run `bundle exec rake generate`
+    When I run `bundle exec rake doctest:generate`
     Then the output should contain:
       """
-      Generate testing examples *:*.
+      Generating test examples *:* in examples/html
        --> Unchanged block_quote:with_id_and_role
        --> Generating block_quote:with_title
        --> Skipping block_quote:with_attribution
@@ -71,10 +71,10 @@ Feature: Generating output examples for a custom HTML backend
       """
 
   Scenario: Regenerate all outdated output examples
-    When I run `bundle exec rake generate FORCE=yes`
+    When I run `bundle exec rake doctest:generate FORCE=yes`
     Then the output should contain:
       """
-      Generate testing examples *:*.
+      Generating test examples *:* in examples/html
        --> Unchanged block_quote:with_id_and_role
        --> Generating block_quote:with_title
        --> Rewriting block_quote:with_attribution
@@ -132,10 +132,10 @@ Feature: Generating output examples for a custom HTML backend
       """
 
   Scenario: Regenerate outdated output examples specified by filter
-    When I run `bundle exec rake generate PATTERN="*:*attribution" FORCE=yes`
+    When I run `bundle exec rake doctest:generate PATTERN="*:*attribution" FORCE=yes`
     Then the output should contain:
       """
-      Generate testing examples *:*attribution.
+      Generating test examples *:*attribution in examples/html
        --> Rewriting block_quote:with_attribution
 
       """

data/features/test_html.feature

@@ -4,53 +4,95 @@ Feature: Testing a custom HTML backend
     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`
+    When I run `bundle exec rake doctest:test`
     Then the output should contain:
       """
-        1) Failure:
-      TestHtml :: block_quote : with_attribution:
-      Failing example..
+      Running DocTest for the templates: templates.
 
-         <div class="quoteblock">
-           <blockquote>A person who never made a mistake <em>never</em> tried anything new.</blockquote>
-      E    <div>Albert Einstein</div>
-      A    <div class="attribution">— Albert Einstein</div>
-         </div>
+      .SFFS
+      """
+    Then the output should contain:
+      """
+      ✗  Failure: block_quote:with_attribution
+         Failing example..
+
+            <div class="quoteblock">
+              <blockquote>A person who never made a mistake <em>never</em> tried anything new.</blockquote>
+         E    <div>Albert Einstein</div>
+         A    <div class="attribution">— Albert Einstein</div>
+            </div>
       """
     And the output should contain:
       """
-        2) Failure:
-      TestHtml :: document : title_with_author:
-      This example should fail..
+      ✗  Failure: 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>
+            <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 examples (1 passed, 2 failed, 2 skipped)
       """
     And the output should contain:
       """
-      5 runs, 3 assertions, 2 failures, 0 errors, 2 skips
+      You have skipped tests. Run with VERBOSE=yes for details.
+      """
+
+    When I run `bundle exec rake doctest:test VERBOSE=yes`
+    Then the output should contain:
+      """
+      Running DocTest for the templates: templates.
+
+      ✓  block_quote:with_id_and_role
+      ∅  block_quote:with_title
+      ✗  block_quote:with_attribution
+      ✗  document:title_with_author
+      ∅  inline_quoted:emphasis
+
+      """
+    And the output should contain:
+      """
+      ∅  Skipped: block_quote:with_title
+         No expected output found
+      """
+    And the output should contain:
+      """
+      ∅  Skipped: inline_quoted:emphasis
+         No expected output found
+      """
+
+  Scenario: Test only examples matching the pattern
+    When I run `bundle exec rake doctest:test PATTERN=block_*:* VERBOSE=yes`
+    Then the output should contain:
+      """
+      Running DocTest for the templates: templates.
+
+      ✓  block_quote:with_id_and_role
+      ∅  block_quote:with_title
+      ✗  block_quote:with_attribution
+
       """
 
   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`
+    And I run `bundle exec rake doctest: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..
+      ✗  Failure: block_quote:with_attribution
+         Failing example..
 
-         <div class="quoteblock">
-      E    <blockquote>A person who never made a mistake <em>never</em> tried anything new.</blockquote>
-      E    <div>Albert Einstein</div>
-      A    <blockquote>A person who never made a mistake --TEMPLATE NOT FOUND-- tried anything new.</blockquote>
-      A    <div class="attribution">— Albert Einstein</div>
-         </div>
+            <div class="quoteblock">
+         E    <blockquote>A person who never made a mistake <em>never</em> tried anything new.</blockquote>
+         E    <div>Albert Einstein</div>
+         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.rb

@@ -3,16 +3,13 @@ require 'pathname'
 module Asciidoctor
   module DocTest
 
-    BUILTIN_EXAMPLES_PATH = Pathname.new(
+    @examples_path = Pathname.new(
       '../../data/examples/asciidoc').expand_path(__dir__).to_s.freeze
 
-    @examples_path = [ BUILTIN_EXAMPLES_PATH ]
-
-    class << self
-      # @return [Array<String>] paths of the directories where to look for the
-      #   examples suites. Use +unshift+ to add your paths before the built-in
-      #   reference input examples (default: +["{asciidoctor-doctest}/data/examples/asciidoc"]+).
-      attr_accessor :examples_path
+    # @return [Array<String>] paths of the built-in input examples. It always
+    #   returns a new array.
+    def self.examples_path
+      [ @examples_path ]
     end
   end
 end
@@ -21,10 +18,10 @@ end
 DocTest = Asciidoctor::DocTest unless defined? DocTest
 
 require 'asciidoctor/doctest/version'
-require 'asciidoctor/doctest/base_example'
-require 'asciidoctor/doctest/base_examples_suite'
+require 'asciidoctor/doctest/example'
 require 'asciidoctor/doctest/generator'
-require 'asciidoctor/doctest/generator_task'
-require 'asciidoctor/doctest/test'
-require 'asciidoctor/doctest/asciidoc/examples_suite'
-require 'asciidoctor/doctest/html/examples_suite'
+require 'asciidoctor/doctest/rake_tasks'
+require 'asciidoctor/doctest/test_reporter'
+require 'asciidoctor/doctest/tester'
+require 'asciidoctor/doctest/io'
+require 'asciidoctor/doctest/html/converter'

data/lib/asciidoctor/doctest/asciidoc_converter.rb

@@ -0,0 +1,85 @@
+require 'asciidoctor'
+require 'asciidoctor/doctest/no_fallback_template_converter'
+require 'corefines'
+
+using Corefines::Hash[:rekey, :+]
+using Corefines::Object::blank?
+
+module Asciidoctor
+  module DocTest
+    ##
+    # This class is basically a wrapper for +Asciidoctor.convert+ that allows to
+    # preset and validate some common parameters.
+    class AsciidocConverter
+
+      # @return [Hash] the default options to be passed to Asciidoctor.
+      attr_reader :default_opts
+
+      ##
+      # @param opts [Hash] the default options to be passed to Asciidoctor.
+      #        For a complete list of all available options see the
+      #        Asciidoctor's documentation
+      #
+      # @option opts :backend [#to_s, nil] the name of the tested backend.
+      # @option opts :backend_name [#to_s, nil] alias for the +:backend+.
+      #
+      # @option opts :converter [Class, Asciidoctor::Converter::Base, nil]
+      #         the backend's converter class (or its instance). When not
+      #         specified, the default converter for the specified backend is
+      #         used.
+      #
+      # @option opts :template_dirs [Array<String>, String] path of the
+      #         directory (or multiple directories) where to look for the
+      #         backend's templates. Relative paths are referenced from the
+      #         working directory.
+      #
+      # @option opts :templates_fallback [Boolean] allow to fall back to using
+      #         an appropriate built-in converter when there is no required
+      #         template in the tested backend?
+      #         This is actually a default behaviour in Asciidoctor, but since
+      #         it's inappropriate for testing of custom backends, it's
+      #         disabled by default.
+      #
+      # @option opts :safe [Symbol] the safe mode, one of +:unsafe+, +:safe+,
+      #         +:server+, or +:secure+. Default is +:safe+.
+      #
+      # @raise [ArgumentError] if some path from the +template_dirs+ doesn't
+      #        exist or is not a directory.
+      #
+      def initialize(opts = {})
+        opts = opts.rekey(&:to_sym).rekey(:backend_name => :backend)
+
+        template_dirs = Array(opts[:template_dirs]).freeze
+        template_dirs.each do |path|
+          fail ArgumentError, "Templates directory '#{path}' doesn't exist!" unless Dir.exist? path
+        end
+
+        unless template_dirs.empty?
+          opts[:template_dirs] = template_dirs
+          opts[:converter] ||= NoFallbackTemplateConverter unless opts[:templates_fallback]
+        end
+
+        opts[:safe] ||= :safe
+        opts.delete(:backend) if opts[:backend].blank?
+
+        @default_opts = opts
+      end
+
+      ##
+      # 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. This will be merged
+      #        with {#default_opts} with precedence of +opts+.
+      # @return [String] converted input.
+      #
+      def convert(text, opts = {})
+        Asciidoctor.convert(text.to_s, @default_opts + opts)
+      end
+
+      alias_method :opts, :default_opts
+      alias_method :call, :convert
+    end
+  end
+end