anchor.diff:  === HTML
   
   [source, html]
  -.Syntax
   ----
   <!-- .first-example
  -  Each example must be preceded by a comment; the first line must contain the
  -  example’s name prefixed with dot.
  +  Each example must be preceded by a header (comment); the first line must
  +  contain the example’s name prefixed with a dot. This text is interpreted
  +  as a description.
   -->
   <p>The example’s content in <strong>HTML</strong>.</p>
   
  
positive.code: 
  ----
  
  == TODO
  
  * describe how to use it
  
negative.code: = 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}
  //variables
  :doctor-man-uri: http://asciidoctor.org/docs/user-manual
  :src-base: lib/asciidoctor/doctest
  
  image:https://badge.fury.io/rb/asciidoctor-doctest.svg[Gem Version, link="http://badge.fury.io/rb/asciidoctor-doctest"] image:https://codeclimate.com/github/asciidoctor/asciidoctor-doctest/badges/gpa.svg[Code Climate, link="https://codeclimate.com/github/asciidoctor/asciidoctor-doctest"] image:http://inch-ci.org/github/asciidoctor/asciidoctor-doctest.svg?branch=master[Inline docs, link="http://inch-ci.org/github/asciidoctor/asciidoctor-doctest"] image:https://img.shields.io/badge/yard-docs-blue.svg[Yard Docs, link="http://www.rubydoc.info/github/asciidoctor/asciidoctor-doctest/frames"]
  
  DocTest is a tool and a test suite for easy end-to-end testing of Asciidoctor backends (i.e.
  converters/renderers) based on comparing of textual output. It provides a collection of categorized
  “scenario-oriented” input _examples_ (documents in AsciiDoc syntax) that can be used for systematic
  testing of any Asciidoctor backend.
  
  TODO
  
  
  == Setup DocTest
  
  Let’s say that you’re developing a new shiny HTML template-based backend named
  simply “shiny” and assume that you have templates in the directory
  `data/templates`.
  
  . Create directory for your output examples: `test/examples/shiny`.
  
  . Add development dependency on `asciidoctor-doctest` to your gemspec:
  +
  [source]
  s.add_development_dependency 'asciidoctor-doctest'
  +
  or Gemfile if you’re not distributing the backend as a gem:
  +
  [source]
  gem 'asciidoctor-doctest'
  +
  and run `bundle install`.
  
  . Create or edit `test/test_helper.rb`; require test dependencies and setup paths:
  +
  [source]
  ----
  require 'asciidoctor/doctest'
  require 'minitest/autorun'
  require 'minitest/rg'
  require 'tilt'
  
  # Setup paths
  Asciidoctor::DocTest.examples_path.unshift 'test/examples/shiny'
  ----
  
  . Create test file `test/templates_test.rb`, extend one of the DocTest’s test
  classes and call `generate_tests!` macro:
  +
  [source]
  ----
  require 'test_helper'
  
  class TestTemplates < Asciidoctor::DocTest::HtmlTest
    templates_path 'data/templates'
    generate_tests!
  end
  ----
  
  . Create or edit `Rakefile`; add tasks to run tests and generator of output
  examples:
  +
  [source]
  ----
  require 'asciidoctor/doctest'
  require 'rake/testtask'
  require 'thread_safe'
  require 'tilt'
  
  Rake::TestTask.new :test do |task|
    task.description = 'Run tests for templates'
    task.pattern = 'test/templates_test.rb'
    task.libs << 'test'
  end
  
  module Asciidoctor
    module DocTest
      GeneratorTask.new(:generate, HtmlGenerator) do |task|
        task.output_dir = 'test/examples/shiny'
        task.templates_path = 'data/templates'
      end
    end
  end
  
  # When no task specified, run test.
  task :default => :test
  ----
  
  == Test examples
  
  Test _example_ is just a document fragment — in AsciiDoc syntax (a reference input) or the
  backend’s target syntax (an expected output) — that should ideally cover one use case from the
  perspective of the generated output (i.e. code branch in converter or template). Examples are
  grouped in so called _example suites_; each focusing on one block or inline element — more
  precisely Asciidoctor’s AST node (paragraph, table, anchor, footnote…).
  
  DocTest provides a collection of the reference (input) examples (see link:data/examples/asciidoc[])
  that should cover test cases usable for most of the Asciidoctor backends.
  
  Examples suite is stored in a textual file named by the AST node (e.g. block_table, inline_anchor…)
  with an extension according to its syntax (e.g. block_table.adoc, block_table.html) — similarly as
  Asciidoctor templates. Individual examples in the suite are separated by a special header with the
  name of the example, an optional description and options. This header should be written as a
  comment (so you can render the examples suite as a valid AsciiDoc/HTML/TeX/… document).
  
  Each example is uniquely identified with its name and the suite name like this:
  `{suite_name}:{example_name}` (e.g. `block_table:with_title`).
  
  [horizontal]
  .Example suites / Asciidoctor’s AST nodes
  document:: TODO
  embedded:: TODO
  section:: {doctor-man-uri}/#sections[document sections], i.e. headings
  block_admonition:: {doctor-man-uri}/#admonition[an admonition block]
  block_audio:: {doctor-man-uri}/#audio[an audio block]
  block_colist:: {doctor-man-uri}/#callouts[a code callouts] list
  block_dlist:: {doctor-man-uri}/#labeled-list[a labeled list] (aka definition list) and {doctor-man-uri}/#question-and-answer-style-list[a Q&A style list]
  block_example:: {doctor-man-uri}/#example[an example block]
  block_floating_title:: {doctor-man-uri}/#discrete-or-floating-section-titles[a discrete or floating section title]
  block_image:: {doctor-man-uri}/#images[an image block]
  block_listing:: {doctor-man-uri}/#listing-blocks[a listing and source code block]
  block_literal:: {doctor-man-uri}/#literal-text-and-blocks[a literal block]
  block_olist:: {doctor-man-uri}/#ordered-lists[an ordered list] (i.e. numbered list)
  block_open:: {doctor-man-uri}/#open-blocks[open blocks], {doctor-man-uri}/#user-abstractabstract[abstract], …
  block_outline:: an actual {doctor-man-uri}/#user-toc[TOC] content (i.e. list of links), usually recursively called
  block_page_break:: {doctor-man-uri}/#page-break[page break]
  block_paragraph:: {doctor-man-uri}/#paragraph[a paragraph]
  block_pass:: {doctor-man-uri}/#pass-bl[a passthrough block]
  block_preamble:: {doctor-man-uri}/#doc-preamble[a preamble], optionally with a TOC
  block_quote:: {doctor-man-uri}/#quote[a quote block]
  block_sidebar:: {doctor-man-uri}/#sidebar[a sidebar]
  block_stem:: {doctor-man-uri}/#stem[a STEM block] (Science, Technology, Engineering and Math)
  block_table:: {doctor-man-uri}/#tables[a table]
  block_thematic_break:: {doctor-man-uri}/#horizontal-rules[a thematic break] (i.e. horizontal rule)
  block_toc:: {doctor-man-uri}/#manual-placement[a TOC macro] (i.e. manually placed TOC); This block is used for `toc::[]` macro only and it’s responsible just for rendering of a the TOC “envelope,” not an actual TOC content.
  block_ulist:: {doctor-man-uri}/#unordered-lists[an unordered list] (aka bullet list) and a {doctor-man-uri}/#checklist[checklist] (e.g. TODO list)
  block_verse:: {doctor-man-uri}/#verse[a verse block]
  block_video:: {doctor-man-uri}/#video[a video block]
  inline_anchor:: {doctor-man-uri}/#url[anchors] (links, cross references and bibliography references)
  inline_break:: {doctor-man-uri}/#line-breaks[line break]
  inline_button:: {doctor-man-uri}/#ui-buttons[UI button]
  inline_callout:: {doctor-man-uri}/#callouts[code callout] icon/mark inside a code block
  inline_footnote:: {doctor-man-uri}/#user-footnotes[footnote]
  inline_image:: {doctor-man-uri}/#images[inline image] and {doctor-man-uri}/#inline-icons[inline icon]
  inline_kbd:: {doctor-man-uri}/#keyboard-shortcuts[keyboard shortcut]
  inline_menu:: {doctor-man-uri}/#menu-selections[menu section]
  inline_quoted:: {doctor-man-uri}/#quotes[text formatting]; emphasis, strong, monospaced, superscript, subscript, curved quotes and inline STEM
  
  
  === AsciiDoc
  
  [source, asciidoc]
  ----
  // .first-example
  // Each block must be preceded by a header (comment); the first line must
  // contain the example’s name prefixed with a dot. This text is interpreted
  // as a description.
  The example’s content in *Asciidoc*.
  
  NOTE: The trailing new line (below this) will be removed.
  
  // .second-example
  * List item level 1
  ** List item level 2
  
  