AsciiDoc input format

AsciiDoc is a lightweight markup language popular in technical documentation. Doc Detective supports inline tests in AsciiDoc files.

File extensions

Doc Detective processes AsciiDoc files with the following extensions:

• .adoc
• .asciidoc
• .asc

Inline test syntax

AsciiDoc files use line comments for inline tests:

// (test { "testId": "my-test" })
// (step { "goTo": "https://example.com" })
// (test end)

The comment syntax uses parentheses to distinguish test comments from regular AsciiDoc comments.

Test start:

// (test { "testId": "my-test" })

Step:

// (step { "goTo": "https://example.com" })

Test end:

// (test end)

Ignore blocks:

// (test ignore start)
Content to ignore
// (test ignore end)

Example

Here’s a complete example of an AsciiDoc file with inline tests:

// (test { "testId": "doc-test" })
== Getting Started
Navigate to the application:
// (step { "goTo": "https://app.example.com" })
Click the *Start* button:
// (step { "click": "Start" })
Enter your username:
// (step { "type": { "keys": "testuser", "selector": "[name=username]" } })
Submit the form:
// (step { "click": "Submit" })
// (test end)

Detected tests

To add detected test functionality to AsciiDoc files, you can define custom markup patterns in your configuration. See custom inputs for examples.

Example custom pattern for AsciiDoc:

{
  "fileTypes": [
    {
      "name": "asciidoc",
      "extensions": ["adoc", "asciidoc", "asc"],
      "markup": [
        {
          "name": "clickOnscreenText",
          "regex": ["\\b(?:[Cc]lick|[Tt]ap)\\b\\s+\\*(.+?)\\*"],
          "actions": ["click"]
        },
        {
          "name": "goToUrl",
          "regex": ["\\b(?:[Gg]o\\s+to|[Nn]avigate\\s+to)\\b\\s+link:(https?:\\/\\/[^\\[]+)\\["],
          "actions": ["goTo"]
        }
      ]
    }
  ]
}

JSON and YAML syntax

AsciiDoc inline tests support both JSON and YAML syntax:

JSON syntax:

// (test { "testId": "my-test", "description": "Test description" })
// (step { "goTo": "https://example.com" })

YAML syntax:

// (test testId: my-test description: Test description)
// (step goTo: https://example.com)

Both formats work identically. Choose the format that’s most readable for your team.

Best practices

• Use parentheses in comments to distinguish test statements from regular comments
• Keep test comments on a single line
• Use descriptive test IDs to identify tests in results
• Combine inline tests with custom markup patterns for comprehensive coverage
• Use YAML syntax for simpler, more readable inline tests

Integration with AsciiDoc toolchains

AsciiDoc test comments are standard AsciiDoc comments and don’t affect document rendering. This makes Doc Detective tests invisible to your documentation build process while still being testable.

Common AsciiDoc toolchains that work with Doc Detective:

• Asciidoctor: The most popular AsciiDoc processor
• Antora: Site generator for AsciiDoc documentation
• Jekyll AsciiDoc: AsciiDoc plugin for Jekyll
• Hugo: Static site generator with AsciiDoc support

Next steps

• Learn about inline tests for manual test definition
• See custom inputs to add detected test patterns for AsciiDoc
• Explore Markdown and DITA formats for detected test examples