pandoc

The atago project wrote these specs on its own initiative and runs them in its own CI, to exercise atago against a real program. They are not pandoc’s official test suite, and the pandoc project is not affiliated with atago.

Summary #

2 suites · 8 scenarios

Contents #

pandoc + changes (a conversion writes exactly its output) #

Converting a document should produce the converted document — and nothing besides. This suite states that exactly: with the source file present as the baseline, a conversion creates precisely one new file, the one named on the command line.

Anything else pandoc happened to write would fail the assertion, which is what makes this a claim about its footprint rather than a check that the output exists.

Source: test/e2e/thirdparty/pandoc/changes.atago.yaml

Scenario: markdown-to-html creates exactly the output file #

only when pandoc --version succeeds

Given #

  • Fixture file in.md is created.

Inputs #

Fixture in.md:

# Title

Some text with *emphasis*.

When #

pandoc in.md -o out.html

Then #

  • exit code is 0
  • the step changed exactly created out.html, modified nothing, deleted nothing
  • file out.html contains <em>emphasis</em>

pandoc (document conversion filter) #

Pandoc converts documents between formats, and it can be used two entirely different ways: as a file-to-file converter, or as a filter in a pipeline reading stdin and writing stdout.

Both are pinned, because a script may depend on either, and they must agree: the same input converted either way must produce the same document.

Beyond the rendered output, pandoc can emit its internal AST as JSON — a structured oracle that says what pandoc understood the document to be, not merely what it printed. Asserting on that catches a parsing regression that happens to render plausibly.

Source: test/e2e/thirdparty/pandoc/pandoc.atago.yaml

Scenario: markdown converts to HTML and a binary docx #

only when pandoc --version succeeds

Given #

  • Fixture file doc.md is created.

Inputs #

Fixture doc.md:

# Title

Some *emphasis* and a [link](https://example.org).

**bold text**

When #

pandoc doc.md -o doc.html
pandoc doc.md -o doc.docx
unzip -p doc.docx word/document.xml

Then #

  • after pandoc doc.md -o doc.html:
    • exit code is 0
    • file doc.html contains <h1, <em>emphasis</em>, <strong>bold text</strong>
  • after pandoc doc.md -o doc.docx:
    • exit code is 0
    • file doc.docx exists
  • after unzip -p doc.docx word/document.xml:
    • exit code is 0
    • stdout contains Title, bold text

Generated artifacts #

  • doc.docx

Scenario: pandoc is a stdin-to-stdout filter #

only when pandoc --version succeeds

Given #

  • Fixture file snippet.md is created.

Inputs #

Fixture snippet.md:

**strong** and _italic_

stdin for pandoc:

(read from file snippet.md)

When #

pandoc -f markdown -t html

Then #

  • exit code is 0
  • stdout contains <strong>strong</strong>, <em>italic</em>

Scenario: the JSON AST is a queryable contract #

only when pandoc --version succeeds

Given #

  • Fixture file doc.md is created.

Inputs #

Fixture doc.md:

# Heading One

A paragraph.

When #

pandoc -t json doc.md

Then #

  • exit code is 0
  • stdout at $.blocks[0].t equals Header
  • stdout at $['pandoc-api-version'] has length 3

Scenario: standalone HTML carries the metadata title #

only when pandoc --version succeeds

Given #

  • Fixture file doc.md is created.

Inputs #

Fixture doc.md:

# Body

When #

pandoc --metadata title=Atago -s doc.md -o standalone.html

Then #

  • exit code is 0
  • file standalone.html contains <title>Atago</title>

Scenario: an unknown output format is rejected #

only when pandoc --version succeeds

Given #

  • Fixture file doc.md is created.

Inputs #

Fixture doc.md:

# X

When #

pandoc -t nosuchformat doc.md

Then #

  • exit code is one of 21, 22, 23
  • stderr contains Unknown output format

Scenario: markdown survives a round-trip through HTML #

only when pandoc --version succeeds

Given #

  • Fixture file doc.md is created.

Inputs #

Fixture doc.md:

Some *emphasis* and **bold text**.

When #

pandoc doc.md -o rt.html
pandoc -f html -t markdown rt.html -o rt.md

Then #

  • after pandoc doc.md -o rt.html:
    • exit code is 0
  • after pandoc -f html -t markdown rt.html -o rt.md:
    • exit code is 0
    • file rt.md contains *emphasis*, **bold text**

Scenario: a missing input file fails cleanly #

only when pandoc --version succeeds

When #

pandoc no-such-file.md

Then #

  • exit code is not 0
  • stdout is empty
  • stderr contains does not exist