[ANN] MarkdownTest 1.0

[John Gruber]

Here's the simple testing system I've been using to develop
Markdown:

  <http://daringfireball.net/projects/downloads/MarkdownTest_1.0.zip>

Unless you're writing your own port or implementation of Markdown,
this isn't going to be very interesting.

The package contains:

1.  A Perl script named MarkdownTest.pl
2.  A folder full of test cases

Each test consists of two files, "test name.text" and "test
name.html", where the .text file is the Markdown-formatted input,
and the .html file is the expected output.

**Note**: The current set of tests includes one that is known to
fail in both Markdown.pl and PHP-Markdown. This is a test of
advanced inline HTML, in ways that aren't currently supported by
Markdown. It's my plan to rejigger Markdown's inline HTML parser so
that it can pass this test in the future; for now, I've left the
test in because I'm lazy, and because I like having a test in there
that I know should fail.

Note also that there probably ought to be a lot more tests.

MarkdownTest.pl simply spins through each pair of test files in the
Tests folder, processing the .text file and comparing the output to
the .html file. If they match, the test passes.

MarkdownTest.pl accepts the following command-line options:

    --script
        Specify the path to the Markdown script to test. Defaults to
        "./Markdown.pl". Example:

                ./MarkdownTest.pl --script ./PHP-Markdown/php-markdown

    --testdir
        Specify the path to a directory containing test data. Defaults to
        "Tests".

    --tidy
        Flag to turn on using the command line 'tidy' tool to normalize HTML
        output before comparing script output to the expected test result.
        Assumes that the 'tidy' command is available in your PATH. Defaults
        to off.

By default, it looks for a script named "Markdown.pl" in the same
folder as MarkdownTest.pl to use as the script to test. Using the
`--script` option, you can test a Markdown implementation at any path
location. However, the script to test must be executable, and it
must accept an input file as an argument.

Here's how I have my scripts arranged:

    Mardown/
        Markdown.pl
        MarkdownTest.pl
        Tests/

Then, with the Markdown parent folder as my working directory, I can
run the suite of tests with this command:

    ./MarkdownTest.pl

To test PHP Markdown, I added another folder:

    Mardown/
        Markdown.pl
        MarkdownTest.pl
        PHP-Markdown/
            markdown.php
            php-markdown
        Tests/

"markdown.php" is Michael's script, but as a regular web-oriented
PHP file, it doesn't accept command line input. So I wrote a short
wrapper named "php-markdown", which looks like this:

    #!/usr/bin/php
    <?php
      include_once('markdown.php');
      $text = file_get_contents($argv[1]);
      echo Markdown($text);
    ?>

And then to test it, still the parent "Markdown" folder as the
working directory:

    ./MarkdownTest.pl --script ./PHP-Markdown/php-markdown

The `--tidy` uses the W3C's `tidy` command-line tool to normalize
the markup before comparing the test ouput to the correct output.
This way, a Markdown implementation that generates markup which is
semantically identical to the correct output, but
character-for-character identical, will still pass the tests.

For example, my Markdown.pl generates `<p>` tags like this:

    <p>This is a paragraph.</p>

Some other Markdown implementation might generate this:

    <p>This is a paragraph.
    </p>

Without the `--tidy` option, this output will fail the test. With
the `--tidy` option, it will pass.

Tidy is open source software that can be downloaded here:

    http://tidy.sourceforge.net/

Anyone who has questions about MarkdownTest can ask them here.

-J.G.