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: = 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 test suite for Asciidoctor backends based on comparing of textual examples.
  
  TODO
  
  
  == Installation
  
  Add this line to your Asciidoctor backend’s Gemfile:
  
  ```ruby
  gem 'asciidoctor-doctest'
  ```
  
  And then execute:
  
   $ bundle
  
  
  == Testing examples
  
  === AsciiDoc
  
  The reference examples in Asciidoc(tor) syntax.
  
  [source, asciidoc]
  .Syntax
  ----
  // .first-example
  // Each block must be preceded by a comment; the first line must contain the
  // example’s name prefixed with a dot.
  The example’s content in *Asciidoc*.
  
  NOTE: The trailing new line (below this) will be removed.
  
  // .second-example
  // :option name: value
  * List item level 1
  ** List item level 2
  
  
negative.code: 
  ----
  
  === Custom
  
  You can extend DocTest to support any textual format you want. All what you need is to implement
  a custom suite parser (extend link:{src-base}/base_suite_parser.rb[BaseSuiteParser]), a test class
  (extend link:{src-base}/base_test.rb[BaseTest]) and optionally a generator (extend
  link:{src-base}/base_generator.rb[BaseGenerator]).
  
  
  == Generate examples
  
  Writing examples of an expected output for all the reference
  input examples from scratch is quite a chore. Therefore DocTest provides a
  generator, so when you have at least partially working Asciidoctor _backend_
  (converter or 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>>).
  
  Now you can generate output examples from all the reference examples (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
  
  Same as previous, but rewrite existing tested examples:
  
  [source, sh]
  bundle exec rake 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:*'
  
  (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
  
  
  == Run tests
  
  Assume that you have defined the test Rake task named `:test` (see <<setup-doctest>>). Then you
  can simply run:
  
  [source, sh]
  bundle exec rake test
  
  
  == TODO
  
  * describe how to use it
  